System.Data.SQLite
Hex Artifact Content
Not logged in

Artifact ebce16262666035672c21b76a04ac1d007ed7f29:


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 38 2e 20 20 42  ersion 3.7.8.  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: 57 49 4e 33 32 5f 4d 41 4c 4c 4f 43 20 20 20 20  WIN32_MALLOC    
3440: 20 20 20 20 20 20 20 2f 2f 20 55 73 65 20 57 69         // Use Wi
3450: 6e 33 32 20 6e 61 74 69 76 65 20 68 65 61 70 20  n32 native heap 
3460: 41 50 49 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54  API.**     SQLIT
3470: 45 5f 4d 45 4d 44 45 42 55 47 20 20 20 20 20 20  E_MEMDEBUG      
3480: 20 20 20 20 20 20 20 20 20 2f 2f 20 44 65 62 75           // Debu
3490: 67 67 69 6e 67 20 76 65 72 73 69 6f 6e 20 6f 66  gging version of
34a0: 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29   system malloc()
34b0: 0a 2a 2a 0a 2a 2a 20 4f 6e 20 57 69 6e 64 6f 77  .**.** On Window
34c0: 73 2c 20 69 66 20 74 68 65 20 53 51 4c 49 54 45  s, if the SQLITE
34d0: 5f 57 49 4e 33 32 5f 4d 41 4c 4c 4f 43 5f 56 41  _WIN32_MALLOC_VA
34e0: 4c 49 44 41 54 45 20 6d 61 63 72 6f 20 69 73 20  LIDATE macro is 
34f0: 64 65 66 69 6e 65 64 20 61 6e 64 20 74 68 65 0a  defined and the.
3500: 2a 2a 20 61 73 73 65 72 74 28 29 20 6d 61 63 72  ** assert() macr
3510: 6f 20 69 73 20 65 6e 61 62 6c 65 64 2c 20 65 61  o is enabled, ea
3520: 63 68 20 63 61 6c 6c 20 69 6e 74 6f 20 74 68 65  ch call into the
3530: 20 57 69 6e 33 32 20 6e 61 74 69 76 65 20 68 65   Win32 native he
3540: 61 70 20 73 75 62 73 79 73 74 65 6d 0a 2a 2a 20  ap subsystem.** 
3550: 77 69 6c 6c 20 63 61 75 73 65 20 48 65 61 70 56  will cause HeapV
3560: 61 6c 69 64 61 74 65 20 74 6f 20 62 65 20 63 61  alidate to be ca
3570: 6c 6c 65 64 2e 20 20 49 66 20 68 65 61 70 20 76  lled.  If heap v
3580: 61 6c 69 64 61 74 69 6f 6e 20 73 68 6f 75 6c 64  alidation should
3590: 20 66 61 69 6c 2c 20 61 6e 0a 2a 2a 20 61 73 73   fail, an.** ass
35a0: 65 72 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 74  ertion will be t
35b0: 72 69 67 67 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20  riggered..**.** 
35c0: 28 48 69 73 74 6f 72 69 63 61 6c 20 6e 6f 74 65  (Historical note
35d0: 3a 20 20 54 68 65 72 65 20 75 73 65 64 20 74 6f  :  There used to
35e0: 20 62 65 20 73 65 76 65 72 61 6c 20 6f 74 68 65   be several othe
35f0: 72 20 6f 70 74 69 6f 6e 73 2c 20 62 75 74 20 77  r options, but w
3600: 65 27 76 65 0a 2a 2a 20 70 61 72 65 64 20 69 74  e've.** pared it
3610: 20 64 6f 77 6e 20 74 6f 20 6a 75 73 74 20 74 68   down to just th
3620: 65 73 65 20 74 77 6f 2e 29 0a 2a 2a 0a 2a 2a 20  ese two.).**.** 
3630: 49 66 20 6e 6f 6e 65 20 6f 66 20 74 68 65 20 61  If none of the a
3640: 62 6f 76 65 20 61 72 65 20 64 65 66 69 6e 65 64  bove are defined
3650: 2c 20 74 68 65 6e 20 73 65 74 20 53 51 4c 49 54  , then set SQLIT
3660: 45 5f 53 59 53 54 45 4d 5f 4d 41 4c 4c 4f 43 20  E_SYSTEM_MALLOC 
3670: 61 73 0a 2a 2a 20 74 68 65 20 64 65 66 61 75 6c  as.** the defaul
3680: 74 2e 0a 2a 2f 0a 23 69 66 20 64 65 66 69 6e 65  t..*/.#if define
3690: 64 28 53 51 4c 49 54 45 5f 53 59 53 54 45 4d 5f  d(SQLITE_SYSTEM_
36a0: 4d 41 4c 4c 4f 43 29 2b 64 65 66 69 6e 65 64 28  MALLOC)+defined(
36b0: 53 51 4c 49 54 45 5f 57 49 4e 33 32 5f 4d 41 4c  SQLITE_WIN32_MAL
36c0: 4c 4f 43 29 2b 64 65 66 69 6e 65 64 28 53 51 4c  LOC)+defined(SQL
36d0: 49 54 45 5f 4d 45 4d 44 45 42 55 47 29 3e 31 0a  ITE_MEMDEBUG)>1.
36e0: 23 20 65 72 72 6f 72 20 22 41 74 20 6d 6f 73 74  # error "At most
36f0: 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c   one of the foll
3700: 6f 77 69 6e 67 20 63 6f 6d 70 69 6c 65 2d 74 69  owing compile-ti
3710: 6d 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  me configuration
3720: 20 6f 70 74 69 6f 6e 73 5c 0a 20 69 73 20 61 6c   options\. is al
3730: 6c 6f 77 73 3a 20 53 51 4c 49 54 45 5f 53 59 53  lows: SQLITE_SYS
3740: 54 45 4d 5f 4d 41 4c 4c 4f 43 2c 20 53 51 4c 49  TEM_MALLOC, SQLI
3750: 54 45 5f 57 49 4e 33 32 5f 4d 41 4c 4c 4f 43 2c  TE_WIN32_MALLOC,
3760: 20 53 51 4c 49 54 45 5f 4d 45 4d 44 45 42 55 47   SQLITE_MEMDEBUG
3770: 22 0a 23 65 6e 64 69 66 0a 23 69 66 20 64 65 66  ".#endif.#if def
3780: 69 6e 65 64 28 53 51 4c 49 54 45 5f 53 59 53 54  ined(SQLITE_SYST
3790: 45 4d 5f 4d 41 4c 4c 4f 43 29 2b 64 65 66 69 6e  EM_MALLOC)+defin
37a0: 65 64 28 53 51 4c 49 54 45 5f 57 49 4e 33 32 5f  ed(SQLITE_WIN32_
37b0: 4d 41 4c 4c 4f 43 29 2b 64 65 66 69 6e 65 64 28  MALLOC)+defined(
37c0: 53 51 4c 49 54 45 5f 4d 45 4d 44 45 42 55 47 29  SQLITE_MEMDEBUG)
37d0: 3d 3d 30 0a 23 20 64 65 66 69 6e 65 20 53 51 4c  ==0.# define SQL
37e0: 49 54 45 5f 53 59 53 54 45 4d 5f 4d 41 4c 4c 4f  ITE_SYSTEM_MALLO
37f0: 43 20 31 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a  C 1.#endif../*.*
3800: 2a 20 49 66 20 53 51 4c 49 54 45 5f 4d 41 4c 4c  * If SQLITE_MALL
3810: 4f 43 5f 53 4f 46 54 5f 4c 49 4d 49 54 20 69 73  OC_SOFT_LIMIT is
3820: 20 6e 6f 74 20 7a 65 72 6f 2c 20 74 68 65 6e 20   not zero, then 
3830: 74 72 79 20 74 6f 20 6b 65 65 70 20 74 68 65 0a  try to keep the.
3840: 2a 2a 20 73 69 7a 65 73 20 6f 66 20 6d 65 6d 6f  ** sizes of memo
3850: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 62  ry allocations b
3860: 65 6c 6f 77 20 74 68 69 73 20 76 61 6c 75 65 20  elow this value 
3870: 77 68 65 72 65 20 70 6f 73 73 69 62 6c 65 2e 0a  where possible..
3880: 2a 2f 0a 23 69 66 20 21 64 65 66 69 6e 65 64 28  */.#if !defined(
3890: 53 51 4c 49 54 45 5f 4d 41 4c 4c 4f 43 5f 53 4f  SQLITE_MALLOC_SO
38a0: 46 54 5f 4c 49 4d 49 54 29 0a 23 20 64 65 66 69  FT_LIMIT).# defi
38b0: 6e 65 20 53 51 4c 49 54 45 5f 4d 41 4c 4c 4f 43  ne SQLITE_MALLOC
38c0: 5f 53 4f 46 54 5f 4c 49 4d 49 54 20 31 30 32 34  _SOFT_LIMIT 1024
38d0: 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 57  .#endif../*.** W
38e0: 65 20 6e 65 65 64 20 74 6f 20 64 65 66 69 6e 65  e need to define
38f0: 20 5f 58 4f 50 45 4e 5f 53 4f 55 52 43 45 20 61   _XOPEN_SOURCE a
3900: 73 20 66 6f 6c 6c 6f 77 73 20 69 6e 20 6f 72 64  s follows in ord
3910: 65 72 20 74 6f 20 65 6e 61 62 6c 65 0a 2a 2a 20  er to enable.** 
3920: 72 65 63 75 72 73 69 76 65 20 6d 75 74 65 78 65  recursive mutexe
3930: 73 20 6f 6e 20 6d 6f 73 74 20 55 6e 69 78 20 73  s on most Unix s
3940: 79 73 74 65 6d 73 2e 20 20 42 75 74 20 4d 61 63  ystems.  But Mac
3950: 20 4f 53 20 58 20 69 73 20 64 69 66 66 65 72 65   OS X is differe
3960: 6e 74 2e 0a 2a 2a 20 54 68 65 20 5f 58 4f 50 45  nt..** The _XOPE
3970: 4e 5f 53 4f 55 52 43 45 20 64 65 66 69 6e 65 20  N_SOURCE define 
3980: 63 61 75 73 65 73 20 70 72 6f 62 6c 65 6d 73 20  causes problems 
3990: 66 6f 72 20 4d 61 63 20 4f 53 20 58 20 77 65 20  for Mac OS X we 
39a0: 61 72 65 20 74 6f 6c 64 2c 0a 2a 2a 20 73 6f 20  are told,.** so 
39b0: 69 74 20 69 73 20 6f 6d 69 74 74 65 64 20 74 68  it is omitted th
39c0: 65 72 65 2e 20 20 53 65 65 20 74 69 63 6b 65 74  ere.  See ticket
39d0: 20 23 32 36 37 33 2e 0a 2a 2a 0a 2a 2a 20 4c 61   #2673..**.** La
39e0: 74 65 72 20 77 65 20 6c 65 61 72 6e 20 74 68 61  ter we learn tha
39f0: 74 20 5f 58 4f 50 45 4e 5f 53 4f 55 52 43 45 20  t _XOPEN_SOURCE 
3a00: 69 73 20 70 6f 6f 72 6c 79 20 6f 72 20 69 6e 63  is poorly or inc
3a10: 6f 72 72 65 63 74 6c 79 0a 2a 2a 20 69 6d 70 6c  orrectly.** impl
3a20: 65 6d 65 6e 74 65 64 20 6f 6e 20 73 6f 6d 65 20  emented on some 
3a30: 73 79 73 74 65 6d 73 2e 20 20 53 6f 20 77 65 20  systems.  So we 
3a40: 61 76 6f 69 64 20 64 65 66 69 6e 69 6e 67 20 69  avoid defining i
3a50: 74 20 61 74 20 61 6c 6c 0a 2a 2a 20 69 66 20 69  t at all.** if i
3a60: 74 20 69 73 20 61 6c 72 65 61 64 79 20 64 65 66  t is already def
3a70: 69 6e 65 64 20 6f 72 20 69 66 20 69 74 20 69 73  ined or if it is
3a80: 20 75 6e 6e 65 65 64 65 64 20 62 65 63 61 75 73   unneeded becaus
3a90: 65 20 77 65 20 61 72 65 0a 2a 2a 20 6e 6f 74 20  e we are.** not 
3aa0: 64 6f 69 6e 67 20 61 20 74 68 72 65 61 64 73 61  doing a threadsa
3ab0: 66 65 20 62 75 69 6c 64 2e 20 20 54 69 63 6b 65  fe build.  Ticke
3ac0: 74 20 23 32 36 38 31 2e 0a 2a 2a 0a 2a 2a 20 53  t #2681..**.** S
3ad0: 65 65 20 61 6c 73 6f 20 74 69 63 6b 65 74 20 23  ee also ticket #
3ae0: 32 37 34 31 2e 0a 2a 2f 0a 23 69 66 20 21 64 65  2741..*/.#if !de
3af0: 66 69 6e 65 64 28 5f 58 4f 50 45 4e 5f 53 4f 55  fined(_XOPEN_SOU
3b00: 52 43 45 29 20 26 26 20 21 64 65 66 69 6e 65 64  RCE) && !defined
3b10: 28 5f 5f 44 41 52 57 49 4e 5f 5f 29 20 26 26 20  (__DARWIN__) && 
3b20: 21 64 65 66 69 6e 65 64 28 5f 5f 41 50 50 4c 45  !defined(__APPLE
3b30: 5f 5f 29 20 26 26 20 53 51 4c 49 54 45 5f 54 48  __) && SQLITE_TH
3b40: 52 45 41 44 53 41 46 45 0a 23 20 20 64 65 66 69  READSAFE.#  defi
3b50: 6e 65 20 5f 58 4f 50 45 4e 5f 53 4f 55 52 43 45  ne _XOPEN_SOURCE
3b60: 20 35 30 30 20 20 2f 2a 20 4e 65 65 64 65 64 20   500  /* Needed 
3b70: 74 6f 20 65 6e 61 62 6c 65 20 70 74 68 72 65 61  to enable pthrea
3b80: 64 20 72 65 63 75 72 73 69 76 65 20 6d 75 74 65  d recursive mute
3b90: 78 65 73 20 2a 2f 0a 23 65 6e 64 69 66 0a 0a 2f  xes */.#endif../
3ba0: 2a 0a 2a 2a 20 54 68 65 20 54 43 4c 20 68 65 61  *.** The TCL hea
3bb0: 64 65 72 73 20 61 72 65 20 6f 6e 6c 79 20 6e 65  ders are only ne
3bc0: 65 64 65 64 20 77 68 65 6e 20 63 6f 6d 70 69 6c  eded when compil
3bd0: 69 6e 67 20 74 68 65 20 54 43 4c 20 62 69 6e 64  ing the TCL bind
3be0: 69 6e 67 73 2e 0a 2a 2f 0a 23 69 66 20 64 65 66  ings..*/.#if def
3bf0: 69 6e 65 64 28 53 51 4c 49 54 45 5f 54 43 4c 29  ined(SQLITE_TCL)
3c00: 20 7c 7c 20 64 65 66 69 6e 65 64 28 54 43 4c 53   || defined(TCLS
3c10: 48 29 0a 23 20 69 6e 63 6c 75 64 65 20 3c 74 63  H).# include <tc
3c20: 6c 2e 68 3e 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a  l.h>.#endif../*.
3c30: 2a 2a 20 4d 61 6e 79 20 70 65 6f 70 6c 65 20 61  ** Many people a
3c40: 72 65 20 66 61 69 6c 69 6e 67 20 74 6f 20 73 65  re failing to se
3c50: 74 20 2d 44 4e 44 45 42 55 47 3d 31 20 77 68 65  t -DNDEBUG=1 whe
3c60: 6e 20 63 6f 6d 70 69 6c 69 6e 67 20 53 51 4c 69  n compiling SQLi
3c70: 74 65 2e 0a 2a 2a 20 53 65 74 74 69 6e 67 20 4e  te..** Setting N
3c80: 44 45 42 55 47 20 6d 61 6b 65 73 20 74 68 65 20  DEBUG makes the 
3c90: 63 6f 64 65 20 73 6d 61 6c 6c 65 72 20 61 6e 64  code smaller and
3ca0: 20 72 75 6e 20 66 61 73 74 65 72 2e 20 20 53 6f   run faster.  So
3cb0: 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a   the following.*
3cc0: 2a 20 6c 69 6e 65 73 20 61 72 65 20 61 64 64 65  * lines are adde
3cd0: 64 20 74 6f 20 61 75 74 6f 6d 61 74 69 63 61 6c  d to automatical
3ce0: 6c 79 20 73 65 74 20 4e 44 45 42 55 47 20 75 6e  ly set NDEBUG un
3cf0: 6c 65 73 73 20 74 68 65 20 2d 44 53 51 4c 49 54  less the -DSQLIT
3d00: 45 5f 44 45 42 55 47 3d 31 0a 2a 2a 20 6f 70 74  E_DEBUG=1.** opt
3d10: 69 6f 6e 20 69 73 20 73 65 74 2e 20 20 54 68 75  ion is set.  Thu
3d20: 73 20 4e 44 45 42 55 47 20 62 65 63 6f 6d 65 73  s NDEBUG becomes
3d30: 20 61 6e 20 6f 70 74 2d 69 6e 20 72 61 74 68 65   an opt-in rathe
3d40: 72 20 74 68 61 6e 20 61 6e 20 6f 70 74 2d 6f 75  r than an opt-ou
3d50: 74 0a 2a 2a 20 66 65 61 74 75 72 65 2e 0a 2a 2f  t.** feature..*/
3d60: 0a 23 69 66 20 21 64 65 66 69 6e 65 64 28 4e 44  .#if !defined(ND
3d70: 45 42 55 47 29 20 26 26 20 21 64 65 66 69 6e 65  EBUG) && !define
3d80: 64 28 53 51 4c 49 54 45 5f 44 45 42 55 47 29 20  d(SQLITE_DEBUG) 
3d90: 0a 23 20 64 65 66 69 6e 65 20 4e 44 45 42 55 47  .# define NDEBUG
3da0: 20 31 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a   1.#endif../*.**
3db0: 20 54 68 65 20 74 65 73 74 63 61 73 65 28 29 20   The testcase() 
3dc0: 6d 61 63 72 6f 20 69 73 20 75 73 65 64 20 74 6f  macro is used to
3dd0: 20 61 69 64 20 69 6e 20 63 6f 76 65 72 61 67 65   aid in coverage
3de0: 20 74 65 73 74 69 6e 67 2e 20 20 57 68 65 6e 20   testing.  When 
3df0: 0a 2a 2a 20 64 6f 69 6e 67 20 63 6f 76 65 72 61  .** doing covera
3e00: 67 65 20 74 65 73 74 69 6e 67 2c 20 74 68 65 20  ge testing, the 
3e10: 63 6f 6e 64 69 74 69 6f 6e 20 69 6e 73 69 64 65  condition inside
3e20: 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f   the argument to
3e30: 0a 2a 2a 20 74 65 73 74 63 61 73 65 28 29 20 6d  .** testcase() m
3e40: 75 73 74 20 62 65 20 65 76 61 6c 75 61 74 65 64  ust be evaluated
3e50: 20 62 6f 74 68 20 74 72 75 65 20 61 6e 64 20 66   both true and f
3e60: 61 6c 73 65 20 69 6e 20 6f 72 64 65 72 20 74 6f  alse in order to
3e70: 0a 2a 2a 20 67 65 74 20 66 75 6c 6c 20 62 72 61  .** get full bra
3e80: 6e 63 68 20 63 6f 76 65 72 61 67 65 2e 20 20 54  nch coverage.  T
3e90: 68 65 20 74 65 73 74 63 61 73 65 28 29 20 6d 61  he testcase() ma
3ea0: 63 72 6f 20 69 73 20 69 6e 73 65 72 74 65 64 0a  cro is inserted.
3eb0: 2a 2a 20 74 6f 20 68 65 6c 70 20 65 6e 73 75 72  ** to help ensur
3ec0: 65 20 61 64 65 71 75 61 74 65 20 74 65 73 74 20  e adequate test 
3ed0: 63 6f 76 65 72 61 67 65 20 69 6e 20 70 6c 61 63  coverage in plac
3ee0: 65 73 20 77 68 65 72 65 20 73 69 6d 70 6c 65 0a  es where simple.
3ef0: 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 2f 64 65 63  ** condition/dec
3f00: 69 73 69 6f 6e 20 63 6f 76 65 72 61 67 65 20 69  ision coverage i
3f10: 73 20 69 6e 61 64 65 71 75 61 74 65 2e 20 20 46  s inadequate.  F
3f20: 6f 72 20 65 78 61 6d 70 6c 65 2c 20 74 65 73 74  or example, test
3f30: 63 61 73 65 28 29 0a 2a 2a 20 63 61 6e 20 62 65  case().** can be
3f40: 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 73 75   used to make su
3f50: 72 65 20 62 6f 75 6e 64 61 72 79 20 76 61 6c 75  re boundary valu
3f60: 65 73 20 61 72 65 20 74 65 73 74 65 64 2e 20 20  es are tested.  
3f70: 46 6f 72 0a 2a 2a 20 62 69 74 6d 61 73 6b 20 74  For.** bitmask t
3f80: 65 73 74 73 2c 20 74 65 73 74 63 61 73 65 28 29  ests, testcase()
3f90: 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
3fa0: 6d 61 6b 65 20 73 75 72 65 20 65 61 63 68 20 62  make sure each b
3fb0: 69 74 0a 2a 2a 20 69 73 20 73 69 67 6e 69 66 69  it.** is signifi
3fc0: 63 61 6e 74 20 61 6e 64 20 75 73 65 64 20 61 74  cant and used at
3fd0: 20 6c 65 61 73 74 20 6f 6e 63 65 2e 20 20 4f 6e   least once.  On
3fe0: 20 73 77 69 74 63 68 20 73 74 61 74 65 6d 65 6e   switch statemen
3ff0: 74 73 0a 2a 2a 20 77 68 65 72 65 20 6d 75 6c 74  ts.** where mult
4000: 69 70 6c 65 20 63 61 73 65 73 20 67 6f 20 74 6f  iple cases go to
4010: 20 74 68 65 20 73 61 6d 65 20 62 6c 6f 63 6b 20   the same block 
4020: 6f 66 20 63 6f 64 65 2c 20 74 65 73 74 63 61 73  of code, testcas
4030: 65 28 29 0a 2a 2a 20 63 61 6e 20 69 6e 73 75 72  e().** can insur
4040: 65 20 74 68 61 74 20 61 6c 6c 20 63 61 73 65 73  e that all cases
4050: 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 2e 0a   are evaluated..
4060: 2a 2a 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c  **.*/.#ifdef SQL
4070: 49 54 45 5f 43 4f 56 45 52 41 47 45 5f 54 45 53  ITE_COVERAGE_TES
4080: 54 0a 53 51 4c 49 54 45 5f 50 52 49 56 41 54 45  T.SQLITE_PRIVATE
4090: 20 20 20 76 6f 69 64 20 73 71 6c 69 74 65 33 43     void sqlite3C
40a0: 6f 76 65 72 61 67 65 28 69 6e 74 29 3b 0a 23 20  overage(int);.# 
40b0: 64 65 66 69 6e 65 20 74 65 73 74 63 61 73 65 28  define testcase(
40c0: 58 29 20 20 69 66 28 20 58 20 29 7b 20 73 71 6c  X)  if( X ){ sql
40d0: 69 74 65 33 43 6f 76 65 72 61 67 65 28 5f 5f 4c  ite3Coverage(__L
40e0: 49 4e 45 5f 5f 29 3b 20 7d 0a 23 65 6c 73 65 0a  INE__); }.#else.
40f0: 23 20 64 65 66 69 6e 65 20 74 65 73 74 63 61 73  # define testcas
4100: 65 28 58 29 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a  e(X).#endif../*.
4110: 2a 2a 20 54 68 65 20 54 45 53 54 4f 4e 4c 59 20  ** The TESTONLY 
4120: 6d 61 63 72 6f 20 69 73 20 75 73 65 64 20 74 6f  macro is used to
4130: 20 65 6e 63 6c 6f 73 65 20 76 61 72 69 61 62 6c   enclose variabl
4140: 65 20 64 65 63 6c 61 72 61 74 69 6f 6e 73 20 6f  e declarations o
4150: 72 0a 2a 2a 20 6f 74 68 65 72 20 62 69 74 73 20  r.** other bits 
4160: 6f 66 20 63 6f 64 65 20 74 68 61 74 20 61 72 65  of code that are
4170: 20 6e 65 65 64 65 64 20 74 6f 20 73 75 70 70 6f   needed to suppo
4180: 72 74 20 74 68 65 20 61 72 67 75 6d 65 6e 74 73  rt the arguments
4190: 0a 2a 2a 20 77 69 74 68 69 6e 20 74 65 73 74 63  .** within testc
41a0: 61 73 65 28 29 20 61 6e 64 20 61 73 73 65 72 74  ase() and assert
41b0: 28 29 20 6d 61 63 72 6f 73 2e 0a 2a 2f 0a 23 69  () macros..*/.#i
41c0: 66 20 21 64 65 66 69 6e 65 64 28 4e 44 45 42 55  f !defined(NDEBU
41d0: 47 29 20 7c 7c 20 64 65 66 69 6e 65 64 28 53 51  G) || defined(SQ
41e0: 4c 49 54 45 5f 43 4f 56 45 52 41 47 45 5f 54 45  LITE_COVERAGE_TE
41f0: 53 54 29 0a 23 20 64 65 66 69 6e 65 20 54 45 53  ST).# define TES
4200: 54 4f 4e 4c 59 28 58 29 20 20 58 0a 23 65 6c 73  TONLY(X)  X.#els
4210: 65 0a 23 20 64 65 66 69 6e 65 20 54 45 53 54 4f  e.# define TESTO
4220: 4e 4c 59 28 58 29 0a 23 65 6e 64 69 66 0a 0a 2f  NLY(X).#endif../
4230: 2a 0a 2a 2a 20 53 6f 6d 65 74 69 6d 65 73 20 77  *.** Sometimes w
4240: 65 20 6e 65 65 64 20 61 20 73 6d 61 6c 6c 20 61  e need a small a
4250: 6d 6f 75 6e 74 20 6f 66 20 63 6f 64 65 20 73 75  mount of code su
4260: 63 68 20 61 73 20 61 20 76 61 72 69 61 62 6c 65  ch as a variable
4270: 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 0a   initialization.
4280: 2a 2a 20 74 6f 20 73 65 74 75 70 20 66 6f 72 20  ** to setup for 
4290: 61 20 6c 61 74 65 72 20 61 73 73 65 72 74 28 29  a later assert()
42a0: 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 57 65 20   statement.  We 
42b0: 64 6f 20 6e 6f 74 20 77 61 6e 74 20 74 68 69 73  do not want this
42c0: 20 63 6f 64 65 20 74 6f 0a 2a 2a 20 61 70 70 65   code to.** appe
42d0: 61 72 20 77 68 65 6e 20 61 73 73 65 72 74 28 29  ar when assert()
42e0: 20 69 73 20 64 69 73 61 62 6c 65 64 2e 20 20 54   is disabled.  T
42f0: 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 6d 61 63  he following mac
4300: 72 6f 20 69 73 20 74 68 65 72 65 66 6f 72 65 0a  ro is therefore.
4310: 2a 2a 20 75 73 65 64 20 74 6f 20 63 6f 6e 74 61  ** used to conta
4320: 69 6e 20 74 68 61 74 20 73 65 74 75 70 20 63 6f  in that setup co
4330: 64 65 2e 20 20 54 68 65 20 22 56 56 41 22 20 61  de.  The "VVA" a
4340: 63 72 6f 6e 79 6d 20 73 74 61 6e 64 73 20 66 6f  cronym stands fo
4350: 72 0a 2a 2a 20 22 56 65 72 69 66 69 63 61 74 69  r.** "Verificati
4360: 6f 6e 2c 20 56 61 6c 69 64 61 74 69 6f 6e 2c 20  on, Validation, 
4370: 61 6e 64 20 41 63 63 72 65 64 69 74 61 74 69 6f  and Accreditatio
4380: 6e 22 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f  n".  In other wo
4390: 72 64 73 2c 20 74 68 65 0a 2a 2a 20 63 6f 64 65  rds, the.** code
43a0: 20 77 69 74 68 69 6e 20 56 56 41 5f 4f 4e 4c 59   within VVA_ONLY
43b0: 28 29 20 77 69 6c 6c 20 6f 6e 6c 79 20 72 75 6e  () will only run
43c0: 20 64 75 72 69 6e 67 20 76 65 72 69 66 69 63 61   during verifica
43d0: 74 69 6f 6e 20 70 72 6f 63 65 73 73 65 73 2e 0a  tion processes..
43e0: 2a 2f 0a 23 69 66 6e 64 65 66 20 4e 44 45 42 55  */.#ifndef NDEBU
43f0: 47 0a 23 20 64 65 66 69 6e 65 20 56 56 41 5f 4f  G.# define VVA_O
4400: 4e 4c 59 28 58 29 20 20 58 0a 23 65 6c 73 65 0a  NLY(X)  X.#else.
4410: 23 20 64 65 66 69 6e 65 20 56 56 41 5f 4f 4e 4c  # define VVA_ONL
4420: 59 28 58 29 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a  Y(X).#endif../*.
4430: 2a 2a 20 54 68 65 20 41 4c 57 41 59 53 20 61 6e  ** The ALWAYS an
4440: 64 20 4e 45 56 45 52 20 6d 61 63 72 6f 73 20 73  d NEVER macros s
4450: 75 72 72 6f 75 6e 64 20 62 6f 6f 6c 65 61 6e 20  urround boolean 
4460: 65 78 70 72 65 73 73 69 6f 6e 73 20 77 68 69 63  expressions whic
4470: 68 20 0a 2a 2a 20 61 72 65 20 69 6e 74 65 6e 64  h .** are intend
4480: 65 64 20 74 6f 20 61 6c 77 61 79 73 20 62 65 20  ed to always be 
4490: 74 72 75 65 20 6f 72 20 66 61 6c 73 65 2c 20 72  true or false, r
44a0: 65 73 70 65 63 74 69 76 65 6c 79 2e 20 20 53 75  espectively.  Su
44b0: 63 68 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e  ch.** expression
44c0: 73 20 63 6f 75 6c 64 20 62 65 20 6f 6d 69 74 74  s could be omitt
44d0: 65 64 20 66 72 6f 6d 20 74 68 65 20 63 6f 64 65  ed from the code
44e0: 20 63 6f 6d 70 6c 65 74 65 6c 79 2e 20 20 42 75   completely.  Bu
44f0: 74 20 74 68 65 79 0a 2a 2a 20 61 72 65 20 69 6e  t they.** are in
4500: 63 6c 75 64 65 64 20 69 6e 20 61 20 66 65 77 20  cluded in a few 
4510: 63 61 73 65 73 20 69 6e 20 6f 72 64 65 72 20 74  cases in order t
4520: 6f 20 65 6e 68 61 6e 63 65 20 74 68 65 20 72 65  o enhance the re
4530: 73 69 6c 69 65 6e 63 65 0a 2a 2a 20 6f 66 20 53  silience.** of S
4540: 51 4c 69 74 65 20 74 6f 20 75 6e 65 78 70 65 63  QLite to unexpec
4550: 74 65 64 20 62 65 68 61 76 69 6f 72 20 2d 20 74  ted behavior - t
4560: 6f 20 6d 61 6b 65 20 74 68 65 20 63 6f 64 65 20  o make the code 
4570: 22 73 65 6c 66 2d 68 65 61 6c 69 6e 67 22 0a 2a  "self-healing".*
4580: 2a 20 6f 72 20 22 64 75 63 74 69 6c 65 22 20 72  * or "ductile" r
4590: 61 74 68 65 72 20 74 68 61 6e 20 62 65 69 6e 67  ather than being
45a0: 20 22 62 72 69 74 74 6c 65 22 20 61 6e 64 20 63   "brittle" and c
45b0: 72 61 73 68 69 6e 67 20 61 74 20 74 68 65 20 66  rashing at the f
45c0: 69 72 73 74 0a 2a 2a 20 68 69 6e 74 20 6f 66 20  irst.** hint of 
45d0: 75 6e 70 6c 61 6e 6e 65 64 20 62 65 68 61 76 69  unplanned behavi
45e0: 6f 72 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68  or..**.** In oth
45f0: 65 72 20 77 6f 72 64 73 2c 20 41 4c 57 41 59 53  er words, ALWAYS
4600: 20 61 6e 64 20 4e 45 56 45 52 20 61 72 65 20 61   and NEVER are a
4610: 64 64 65 64 20 66 6f 72 20 64 65 66 65 6e 73 69  dded for defensi
4620: 76 65 20 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 57  ve code..**.** W
4630: 68 65 6e 20 64 6f 69 6e 67 20 63 6f 76 65 72 61  hen doing covera
4640: 67 65 20 74 65 73 74 69 6e 67 20 41 4c 57 41 59  ge testing ALWAY
4650: 53 20 61 6e 64 20 4e 45 56 45 52 20 61 72 65 20  S and NEVER are 
4660: 68 61 72 64 2d 63 6f 64 65 64 20 74 6f 0a 2a 2a  hard-coded to.**
4670: 20 62 65 20 74 72 75 65 20 61 6e 64 20 66 61 6c   be true and fal
4680: 73 65 20 73 6f 20 74 68 61 74 20 74 68 65 20 75  se so that the u
4690: 6e 72 65 61 63 68 61 62 6c 65 20 63 6f 64 65 20  nreachable code 
46a0: 74 68 65 6e 20 73 70 65 63 69 66 79 20 77 69 6c  then specify wil
46b0: 6c 0a 2a 2a 20 6e 6f 74 20 62 65 20 63 6f 75 6e  l.** not be coun
46c0: 74 65 64 20 61 73 20 75 6e 74 65 73 74 65 64 20  ted as untested 
46d0: 63 6f 64 65 2e 0a 2a 2f 0a 23 69 66 20 64 65 66  code..*/.#if def
46e0: 69 6e 65 64 28 53 51 4c 49 54 45 5f 43 4f 56 45  ined(SQLITE_COVE
46f0: 52 41 47 45 5f 54 45 53 54 29 0a 23 20 64 65 66  RAGE_TEST).# def
4700: 69 6e 65 20 41 4c 57 41 59 53 28 58 29 20 20 20  ine ALWAYS(X)   
4710: 20 20 20 28 31 29 0a 23 20 64 65 66 69 6e 65 20     (1).# define 
4720: 4e 45 56 45 52 28 58 29 20 20 20 20 20 20 20 28  NEVER(X)       (
4730: 30 29 0a 23 65 6c 69 66 20 21 64 65 66 69 6e 65  0).#elif !define
4740: 64 28 4e 44 45 42 55 47 29 0a 23 20 64 65 66 69  d(NDEBUG).# defi
4750: 6e 65 20 41 4c 57 41 59 53 28 58 29 20 20 20 20  ne ALWAYS(X)    
4760: 20 20 28 28 58 29 3f 31 3a 28 61 73 73 65 72 74    ((X)?1:(assert
4770: 28 30 29 2c 30 29 29 0a 23 20 64 65 66 69 6e 65  (0),0)).# define
4780: 20 4e 45 56 45 52 28 58 29 20 20 20 20 20 20 20   NEVER(X)       
4790: 28 28 58 29 3f 28 61 73 73 65 72 74 28 30 29 2c  ((X)?(assert(0),
47a0: 31 29 3a 30 29 0a 23 65 6c 73 65 0a 23 20 64 65  1):0).#else.# de
47b0: 66 69 6e 65 20 41 4c 57 41 59 53 28 58 29 20 20  fine ALWAYS(X)  
47c0: 20 20 20 20 28 58 29 0a 23 20 64 65 66 69 6e 65      (X).# define
47d0: 20 4e 45 56 45 52 28 58 29 20 20 20 20 20 20 20   NEVER(X)       
47e0: 28 58 29 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a  (X).#endif../*.*
47f0: 2a 20 52 65 74 75 72 6e 20 74 72 75 65 20 28 6e  * Return true (n
4800: 6f 6e 2d 7a 65 72 6f 29 20 69 66 20 74 68 65 20  on-zero) if the 
4810: 69 6e 70 75 74 20 69 73 20 61 20 69 6e 74 65 67  input is a integ
4820: 65 72 20 74 68 61 74 20 69 73 20 74 6f 6f 20 6c  er that is too l
4830: 61 72 67 65 0a 2a 2a 20 74 6f 20 66 69 74 20 69  arge.** to fit i
4840: 6e 20 33 32 2d 62 69 74 73 2e 20 20 54 68 69 73  n 32-bits.  This
4850: 20 6d 61 63 72 6f 20 69 73 20 75 73 65 64 20 69   macro is used i
4860: 6e 73 69 64 65 20 6f 66 20 76 61 72 69 6f 75 73  nside of various
4870: 20 74 65 73 74 63 61 73 65 28 29 0a 2a 2a 20 6d   testcase().** m
4880: 61 63 72 6f 73 20 74 6f 20 76 65 72 69 66 79 20  acros to verify 
4890: 74 68 61 74 20 77 65 20 68 61 76 65 20 74 65 73  that we have tes
48a0: 74 65 64 20 53 51 4c 69 74 65 20 66 6f 72 20 6c  ted SQLite for l
48b0: 61 72 67 65 2d 66 69 6c 65 20 73 75 70 70 6f 72  arge-file suppor
48c0: 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 49 53  t..*/.#define IS
48d0: 5f 42 49 47 5f 49 4e 54 28 58 29 20 20 28 28 28  _BIG_INT(X)  (((
48e0: 58 29 26 7e 28 69 36 34 29 30 78 66 66 66 66 66  X)&~(i64)0xfffff
48f0: 66 66 66 29 21 3d 30 29 0a 0a 2f 2a 0a 2a 2a 20  fff)!=0)../*.** 
4900: 54 68 65 20 6d 61 63 72 6f 20 75 6e 6c 69 6b 65  The macro unlike
4910: 6c 79 28 29 20 69 73 20 61 20 68 69 6e 74 20 74  ly() is a hint t
4920: 68 61 74 20 73 75 72 72 6f 75 6e 64 73 20 61 20  hat surrounds a 
4930: 62 6f 6f 6c 65 61 6e 0a 2a 2a 20 65 78 70 72 65  boolean.** expre
4940: 73 73 69 6f 6e 20 74 68 61 74 20 69 73 20 75 73  ssion that is us
4950: 75 61 6c 6c 79 20 66 61 6c 73 65 2e 20 20 4d 61  ually false.  Ma
4960: 63 72 6f 20 6c 69 6b 65 6c 79 28 29 20 73 75 72  cro likely() sur
4970: 72 6f 75 6e 64 73 0a 2a 2a 20 61 20 62 6f 6f 6c  rounds.** a bool
4980: 65 61 6e 20 65 78 70 72 65 73 73 69 6f 6e 20 74  ean expression t
4990: 68 61 74 20 69 73 20 75 73 75 61 6c 6c 79 20 74  hat is usually t
49a0: 72 75 65 2e 20 20 47 43 43 20 69 73 20 61 62 6c  rue.  GCC is abl
49b0: 65 20 74 6f 0a 2a 2a 20 75 73 65 20 74 68 65 73  e to.** use thes
49c0: 65 20 68 69 6e 74 73 20 74 6f 20 67 65 6e 65 72  e hints to gener
49d0: 61 74 65 20 62 65 74 74 65 72 20 63 6f 64 65 2c  ate better code,
49e0: 20 73 6f 6d 65 74 69 6d 65 73 2e 0a 2a 2f 0a 23   sometimes..*/.#
49f0: 69 66 20 64 65 66 69 6e 65 64 28 5f 5f 47 4e 55  if defined(__GNU
4a00: 43 5f 5f 29 20 26 26 20 30 0a 23 20 64 65 66 69  C__) && 0.# defi
4a10: 6e 65 20 6c 69 6b 65 6c 79 28 58 29 20 20 20 20  ne likely(X)    
4a20: 5f 5f 62 75 69 6c 74 69 6e 5f 65 78 70 65 63 74  __builtin_expect
4a30: 28 28 58 29 2c 31 29 0a 23 20 64 65 66 69 6e 65  ((X),1).# define
4a40: 20 75 6e 6c 69 6b 65 6c 79 28 58 29 20 20 5f 5f   unlikely(X)  __
4a50: 62 75 69 6c 74 69 6e 5f 65 78 70 65 63 74 28 28  builtin_expect((
4a60: 58 29 2c 30 29 0a 23 65 6c 73 65 0a 23 20 64 65  X),0).#else.# de
4a70: 66 69 6e 65 20 6c 69 6b 65 6c 79 28 58 29 20 20  fine likely(X)  
4a80: 20 20 21 21 28 58 29 0a 23 20 64 65 66 69 6e 65    !!(X).# define
4a90: 20 75 6e 6c 69 6b 65 6c 79 28 58 29 20 20 21 21   unlikely(X)  !!
4aa0: 28 58 29 0a 23 65 6e 64 69 66 0a 0a 2f 2a 2a 2a  (X).#endif../***
4ab0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 49 6e 63 6c  *********** Incl
4ac0: 75 64 65 20 73 71 6c 69 74 65 33 2e 68 20 69 6e  ude sqlite3.h in
4ad0: 20 74 68 65 20 6d 69 64 64 6c 65 20 6f 66 20 73   the middle of s
4ae0: 71 6c 69 74 65 49 6e 74 2e 68 20 2a 2a 2a 2a 2a  qliteInt.h *****
4af0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a 2a 2a  **********/./***
4b00: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 42 65 67 69  *********** Begi
4b10: 6e 20 66 69 6c 65 20 73 71 6c 69 74 65 33 2e 68  n file sqlite3.h
4b20: 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a   ***************
4b30: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
4b40: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a 0a 2a  **********/./*.*
4b50: 2a 20 32 30 30 31 20 53 65 70 74 65 6d 62 65 72  * 2001 September
4b60: 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75   15.**.** The au
4b70: 74 68 6f 72 20 64 69 73 63 6c 61 69 6d 73 20 63  thor disclaims c
4b80: 6f 70 79 72 69 67 68 74 20 74 6f 20 74 68 69 73  opyright to this
4b90: 20 73 6f 75 72 63 65 20 63 6f 64 65 2e 20 20 49   source code.  I
4ba0: 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 61 20  n place of.** a 
4bb0: 6c 65 67 61 6c 20 6e 6f 74 69 63 65 2c 20 68 65  legal notice, he
4bc0: 72 65 20 69 73 20 61 20 62 6c 65 73 73 69 6e 67  re is a blessing
4bd0: 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d 61 79 20 79  :.**.**    May y
4be0: 6f 75 20 64 6f 20 67 6f 6f 64 20 61 6e 64 20 6e  ou do good and n
4bf0: 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20 20 20 20 4d  ot evil..**    M
4c00: 61 79 20 79 6f 75 20 66 69 6e 64 20 66 6f 72 67  ay you find forg
4c10: 69 76 65 6e 65 73 73 20 66 6f 72 20 79 6f 75 72  iveness for your
4c20: 73 65 6c 66 20 61 6e 64 20 66 6f 72 67 69 76 65  self and forgive
4c30: 20 6f 74 68 65 72 73 2e 0a 2a 2a 20 20 20 20 4d   others..**    M
4c40: 61 79 20 79 6f 75 20 73 68 61 72 65 20 66 72 65  ay you share fre
4c50: 65 6c 79 2c 20 6e 65 76 65 72 20 74 61 6b 69 6e  ely, never takin
4c60: 67 20 6d 6f 72 65 20 74 68 61 6e 20 79 6f 75 20  g more than you 
4c70: 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 2a  give..**.*******
4c80: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
4c90: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
4ca0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
4cb0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
4cc0: 2a 2a 0a 2a 2a 20 54 68 69 73 20 68 65 61 64 65  **.** This heade
4cd0: 72 20 66 69 6c 65 20 64 65 66 69 6e 65 73 20 74  r file defines t
4ce0: 68 65 20 69 6e 74 65 72 66 61 63 65 20 74 68 61  he interface tha
4cf0: 74 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62  t the SQLite lib
4d00: 72 61 72 79 0a 2a 2a 20 70 72 65 73 65 6e 74 73  rary.** presents
4d10: 20 74 6f 20 63 6c 69 65 6e 74 20 70 72 6f 67 72   to client progr
4d20: 61 6d 73 2e 20 20 49 66 20 61 20 43 2d 66 75 6e  ams.  If a C-fun
4d30: 63 74 69 6f 6e 2c 20 73 74 72 75 63 74 75 72 65  ction, structure
4d40: 2c 20 64 61 74 61 74 79 70 65 2c 0a 2a 2a 20 6f  , datatype,.** o
4d50: 72 20 63 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e  r constant defin
4d60: 69 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 61  ition does not a
4d70: 70 70 65 61 72 20 69 6e 20 74 68 69 73 20 66 69  ppear in this fi
4d80: 6c 65 2c 20 74 68 65 6e 20 69 74 20 69 73 0a 2a  le, then it is.*
4d90: 2a 20 6e 6f 74 20 61 20 70 75 62 6c 69 73 68 65  * not a publishe
4da0: 64 20 41 50 49 20 6f 66 20 53 51 4c 69 74 65 2c  d API of SQLite,
4db0: 20 69 73 20 73 75 62 6a 65 63 74 20 74 6f 20 63   is subject to c
4dc0: 68 61 6e 67 65 20 77 69 74 68 6f 75 74 0a 2a 2a  hange without.**
4dd0: 20 6e 6f 74 69 63 65 2c 20 61 6e 64 20 73 68 6f   notice, and sho
4de0: 75 6c 64 20 6e 6f 74 20 62 65 20 72 65 66 65 72  uld not be refer
4df0: 65 6e 63 65 64 20 62 79 20 70 72 6f 67 72 61 6d  enced by program
4e00: 73 20 74 68 61 74 20 75 73 65 20 53 51 4c 69 74  s that use SQLit
4e10: 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66  e..**.** Some of
4e20: 20 74 68 65 20 64 65 66 69 6e 69 74 69 6f 6e 73   the definitions
4e30: 20 74 68 61 74 20 61 72 65 20 69 6e 20 74 68 69   that are in thi
4e40: 73 20 66 69 6c 65 20 61 72 65 20 6d 61 72 6b 65  s file are marke
4e50: 64 20 61 73 0a 2a 2a 20 22 65 78 70 65 72 69 6d  d as.** "experim
4e60: 65 6e 74 61 6c 22 2e 20 20 45 78 70 65 72 69 6d  ental".  Experim
4e70: 65 6e 74 61 6c 20 69 6e 74 65 72 66 61 63 65 73  ental interfaces
4e80: 20 61 72 65 20 6e 6f 72 6d 61 6c 6c 79 20 6e 65   are normally ne
4e90: 77 0a 2a 2a 20 66 65 61 74 75 72 65 73 20 72 65  w.** features re
4ea0: 63 65 6e 74 6c 79 20 61 64 64 65 64 20 74 6f 20  cently added to 
4eb0: 53 51 4c 69 74 65 2e 20 20 57 65 20 64 6f 20 6e  SQLite.  We do n
4ec0: 6f 74 20 61 6e 74 69 63 69 70 61 74 65 20 63 68  ot anticipate ch
4ed0: 61 6e 67 65 73 0a 2a 2a 20 74 6f 20 65 78 70 65  anges.** to expe
4ee0: 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66 61  rimental interfa
4ef0: 63 65 73 20 62 75 74 20 72 65 73 65 72 76 65 20  ces but reserve 
4f00: 74 68 65 20 72 69 67 68 74 20 74 6f 20 6d 61 6b  the right to mak
4f10: 65 20 6d 69 6e 6f 72 20 63 68 61 6e 67 65 73 0a  e minor changes.
4f20: 2a 2a 20 69 66 20 65 78 70 65 72 69 65 6e 63 65  ** if experience
4f30: 20 66 72 6f 6d 20 75 73 65 20 22 69 6e 20 74 68   from use "in th
4f40: 65 20 77 69 6c 64 22 20 73 75 67 67 65 73 74 20  e wild" suggest 
4f50: 73 75 63 68 20 63 68 61 6e 67 65 73 20 61 72 65  such changes are
4f60: 20 70 72 75 64 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20   prudent..**.** 
4f70: 54 68 65 20 6f 66 66 69 63 69 61 6c 20 43 2d 6c  The official C-l
4f80: 61 6e 67 75 61 67 65 20 41 50 49 20 64 6f 63 75  anguage API docu
4f90: 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 53 51  mentation for SQ
4fa0: 4c 69 74 65 20 69 73 20 64 65 72 69 76 65 64 0a  Lite is derived.
4fb0: 2a 2a 20 66 72 6f 6d 20 63 6f 6d 6d 65 6e 74 73  ** from comments
4fc0: 20 69 6e 20 74 68 69 73 20 66 69 6c 65 2e 20 20   in this file.  
4fd0: 54 68 69 73 20 66 69 6c 65 20 69 73 20 74 68 65  This file is the
4fe0: 20 61 75 74 68 6f 72 69 74 61 74 69 76 65 20 73   authoritative s
4ff0: 6f 75 72 63 65 0a 2a 2a 20 6f 6e 20 68 6f 77 20  ource.** on how 
5000: 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
5010: 73 20 61 72 65 20 73 75 70 70 6f 73 65 20 74 6f  s are suppose to
5020: 20 6f 70 65 72 61 74 65 2e 0a 2a 2a 0a 2a 2a 20   operate..**.** 
5030: 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 69 73  The name of this
5040: 20 66 69 6c 65 20 75 6e 64 65 72 20 63 6f 6e 66   file under conf
5050: 69 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65  iguration manage
5060: 6d 65 6e 74 20 69 73 20 22 73 71 6c 69 74 65 2e  ment is "sqlite.
5070: 68 2e 69 6e 22 2e 0a 2a 2a 20 54 68 65 20 6d 61  h.in"..** The ma
5080: 6b 65 66 69 6c 65 20 6d 61 6b 65 73 20 73 6f 6d  kefile makes som
5090: 65 20 6d 69 6e 6f 72 20 63 68 61 6e 67 65 73 20  e minor changes 
50a0: 74 6f 20 74 68 69 73 20 66 69 6c 65 20 28 73 75  to this file (su
50b0: 63 68 20 61 73 20 69 6e 73 65 72 74 69 6e 67 0a  ch as inserting.
50c0: 2a 2a 20 74 68 65 20 76 65 72 73 69 6f 6e 20 6e  ** the version n
50d0: 75 6d 62 65 72 29 20 61 6e 64 20 63 68 61 6e 67  umber) and chang
50e0: 65 73 20 69 74 73 20 6e 61 6d 65 20 74 6f 20 22  es its name to "
50f0: 73 71 6c 69 74 65 33 2e 68 22 20 61 73 0a 2a 2a  sqlite3.h" as.**
5100: 20 70 61 72 74 20 6f 66 20 74 68 65 20 62 75 69   part of the bui
5110: 6c 64 20 70 72 6f 63 65 73 73 2e 0a 2a 2f 0a 23  ld process..*/.#
5120: 69 66 6e 64 65 66 20 5f 53 51 4c 49 54 45 33 5f  ifndef _SQLITE3_
5130: 48 5f 0a 23 64 65 66 69 6e 65 20 5f 53 51 4c 49  H_.#define _SQLI
5140: 54 45 33 5f 48 5f 0a 23 69 6e 63 6c 75 64 65 20  TE3_H_.#include 
5150: 3c 73 74 64 61 72 67 2e 68 3e 20 20 20 20 20 2f  <stdarg.h>     /
5160: 2a 20 4e 65 65 64 65 64 20 66 6f 72 20 74 68 65  * Needed for the
5170: 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 66 20 76   definition of v
5180: 61 5f 6c 69 73 74 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  a_list */../*.**
5190: 20 4d 61 6b 65 20 73 75 72 65 20 77 65 20 63 61   Make sure we ca
51a0: 6e 20 63 61 6c 6c 20 74 68 69 73 20 73 74 75 66  n call this stuf
51b0: 66 20 66 72 6f 6d 20 43 2b 2b 2e 0a 2a 2f 0a 23  f from C++..*/.#
51c0: 69 66 20 30 0a 65 78 74 65 72 6e 20 22 43 22 20  if 0.extern "C" 
51d0: 7b 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a 2a  {.#endif.../*.**
51e0: 20 41 64 64 20 74 68 65 20 61 62 69 6c 69 74 79   Add the ability
51f0: 20 74 6f 20 6f 76 65 72 72 69 64 65 20 27 65 78   to override 'ex
5200: 74 65 72 6e 27 0a 2a 2f 0a 23 69 66 6e 64 65 66  tern'.*/.#ifndef
5210: 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 0a 23   SQLITE_EXTERN.#
5220: 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45   define SQLITE_E
5230: 58 54 45 52 4e 20 65 78 74 65 72 6e 0a 23 65 6e  XTERN extern.#en
5240: 64 69 66 0a 0a 23 69 66 6e 64 65 66 20 53 51 4c  dif..#ifndef SQL
5250: 49 54 45 5f 41 50 49 0a 23 20 64 65 66 69 6e 65  ITE_API.# define
5260: 20 53 51 4c 49 54 45 5f 41 50 49 0a 23 65 6e 64   SQLITE_API.#end
5270: 69 66 0a 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 73 65  if.../*.** These
5280: 20 6e 6f 2d 6f 70 20 6d 61 63 72 6f 73 20 61 72   no-op macros ar
5290: 65 20 75 73 65 64 20 69 6e 20 66 72 6f 6e 74 20  e used in front 
52a0: 6f 66 20 69 6e 74 65 72 66 61 63 65 73 20 74 6f  of interfaces to
52b0: 20 6d 61 72 6b 20 74 68 6f 73 65 0a 2a 2a 20 69   mark those.** i
52c0: 6e 74 65 72 66 61 63 65 73 20 61 73 20 65 69 74  nterfaces as eit
52d0: 68 65 72 20 64 65 70 72 65 63 61 74 65 64 20 6f  her deprecated o
52e0: 72 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e 20  r experimental. 
52f0: 20 4e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e   New application
5300: 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74 20  s.** should not 
5310: 75 73 65 20 64 65 70 72 65 63 61 74 65 64 20 69  use deprecated i
5320: 6e 74 65 72 66 61 63 65 73 20 2d 20 74 68 65 79  nterfaces - they
5330: 20 61 72 65 20 73 75 70 70 6f 72 74 20 66 6f 72   are support for
5340: 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f   backwards.** co
5350: 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79  mpatibility only
5360: 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 20 77  .  Application w
5370: 72 69 74 65 72 73 20 73 68 6f 75 6c 64 20 62 65  riters should be
5380: 20 61 77 61 72 65 20 74 68 61 74 0a 2a 2a 20 65   aware that.** e
5390: 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65  xperimental inte
53a0: 72 66 61 63 65 73 20 61 72 65 20 73 75 62 6a 65  rfaces are subje
53b0: 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e 20  ct to change in 
53c0: 70 6f 69 6e 74 20 72 65 6c 65 61 73 65 73 2e 0a  point releases..
53d0: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 6d 61 63 72  **.** These macr
53e0: 6f 73 20 75 73 65 64 20 74 6f 20 72 65 73 6f 6c  os used to resol
53f0: 76 65 20 74 6f 20 76 61 72 69 6f 75 73 20 6b 69  ve to various ki
5400: 6e 64 73 20 6f 66 20 63 6f 6d 70 69 6c 65 72 20  nds of compiler 
5410: 6d 61 67 69 63 20 74 68 61 74 0a 2a 2a 20 77 6f  magic that.** wo
5420: 75 6c 64 20 67 65 6e 65 72 61 74 65 20 77 61 72  uld generate war
5430: 6e 69 6e 67 20 6d 65 73 73 61 67 65 73 20 77 68  ning messages wh
5440: 65 6e 20 74 68 65 79 20 77 65 72 65 20 75 73 65  en they were use
5450: 64 2e 20 20 42 75 74 20 74 68 61 74 0a 2a 2a 20  d.  But that.** 
5460: 63 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20 65  compiler magic e
5470: 6e 64 65 64 20 75 70 20 67 65 6e 65 72 61 74 69  nded up generati
5480: 6e 67 20 73 75 63 68 20 61 20 66 6c 75 72 72 79  ng such a flurry
5490: 20 6f 66 20 62 75 67 20 72 65 70 6f 72 74 73 0a   of bug reports.
54a0: 2a 2a 20 74 68 61 74 20 77 65 20 68 61 76 65 20  ** that we have 
54b0: 74 61 6b 65 6e 20 69 74 20 61 6c 6c 20 6f 75 74  taken it all out
54c0: 20 61 6e 64 20 67 6f 6e 65 20 62 61 63 6b 20 74   and gone back t
54d0: 6f 20 75 73 69 6e 67 20 73 69 6d 70 6c 65 0a 2a  o using simple.*
54e0: 2a 20 6e 6f 6f 70 20 6d 61 63 72 6f 73 2e 0a 2a  * noop macros..*
54f0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5500: 5f 44 45 50 52 45 43 41 54 45 44 0a 23 64 65 66  _DEPRECATED.#def
5510: 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 50 45 52  ine SQLITE_EXPER
5520: 49 4d 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a 2a 20 45  IMENTAL../*.** E
5530: 6e 73 75 72 65 20 74 68 65 73 65 20 73 79 6d 62  nsure these symb
5540: 6f 6c 73 20 77 65 72 65 20 6e 6f 74 20 64 65 66  ols were not def
5550: 69 6e 65 64 20 62 79 20 73 6f 6d 65 20 70 72 65  ined by some pre
5560: 76 69 6f 75 73 20 68 65 61 64 65 72 20 66 69 6c  vious header fil
5570: 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c  e..*/.#ifdef SQL
5580: 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23 20 75 6e  ITE_VERSION.# un
5590: 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49  def SQLITE_VERSI
55a0: 4f 4e 0a 23 65 6e 64 69 66 0a 23 69 66 64 65 66  ON.#endif.#ifdef
55b0: 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f   SQLITE_VERSION_
55c0: 4e 55 4d 42 45 52 0a 23 20 75 6e 64 65 66 20 53  NUMBER.# undef S
55d0: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
55e0: 4d 42 45 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a  MBER.#endif../*.
55f0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d  ** CAPI3REF: Com
5600: 70 69 6c 65 2d 54 69 6d 65 20 4c 69 62 72 61 72  pile-Time Librar
5610: 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72  y Version Number
5620: 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b 53  s.**.** ^(The [S
5630: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20 43  QLITE_VERSION] C
5640: 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61   preprocessor ma
5650: 63 72 6f 20 69 6e 20 74 68 65 20 73 71 6c 69 74  cro in the sqlit
5660: 65 33 2e 68 20 68 65 61 64 65 72 0a 2a 2a 20 65  e3.h header.** e
5670: 76 61 6c 75 61 74 65 73 20 74 6f 20 61 20 73 74  valuates to a st
5680: 72 69 6e 67 20 6c 69 74 65 72 61 6c 20 74 68 61  ring literal tha
5690: 74 20 69 73 20 74 68 65 20 53 51 4c 69 74 65 20  t is the SQLite 
56a0: 76 65 72 73 69 6f 6e 20 69 6e 20 74 68 65 0a 2a  version in the.*
56b0: 2a 20 66 6f 72 6d 61 74 20 22 58 2e 59 2e 5a 22  * format "X.Y.Z"
56c0: 20 77 68 65 72 65 20 58 20 69 73 20 74 68 65 20   where X is the 
56d0: 6d 61 6a 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75  major version nu
56e0: 6d 62 65 72 20 28 61 6c 77 61 79 73 20 33 20 66  mber (always 3 f
56f0: 6f 72 0a 2a 2a 20 53 51 4c 69 74 65 33 29 20 61  or.** SQLite3) a
5700: 6e 64 20 59 20 69 73 20 74 68 65 20 6d 69 6e 6f  nd Y is the mino
5710: 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72  r version number
5720: 20 61 6e 64 20 5a 20 69 73 20 74 68 65 20 72 65   and Z is the re
5730: 6c 65 61 73 65 20 6e 75 6d 62 65 72 2e 29 5e 0a  lease number.)^.
5740: 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c 49 54 45  ** ^(The [SQLITE
5750: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d  _VERSION_NUMBER]
5760: 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20   C preprocessor 
5770: 6d 61 63 72 6f 20 72 65 73 6f 6c 76 65 73 20 74  macro resolves t
5780: 6f 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20  o an integer.** 
5790: 77 69 74 68 20 74 68 65 20 76 61 6c 75 65 20 28  with the value (
57a0: 58 2a 31 30 30 30 30 30 30 20 2b 20 59 2a 31 30  X*1000000 + Y*10
57b0: 30 30 20 2b 20 5a 29 20 77 68 65 72 65 20 58 2c  00 + Z) where X,
57c0: 20 59 2c 20 61 6e 64 20 5a 20 61 72 65 20 74 68   Y, and Z are th
57d0: 65 20 73 61 6d 65 0a 2a 2a 20 6e 75 6d 62 65 72  e same.** number
57e0: 73 20 75 73 65 64 20 69 6e 20 5b 53 51 4c 49 54  s used in [SQLIT
57f0: 45 5f 56 45 52 53 49 4f 4e 5d 2e 29 5e 0a 2a 2a  E_VERSION].)^.**
5800: 20 54 68 65 20 53 51 4c 49 54 45 5f 56 45 52 53   The SQLITE_VERS
5810: 49 4f 4e 5f 4e 55 4d 42 45 52 20 66 6f 72 20 61  ION_NUMBER for a
5820: 6e 79 20 67 69 76 65 6e 20 72 65 6c 65 61 73 65  ny given release
5830: 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c 20   of SQLite will 
5840: 61 6c 73 6f 0a 2a 2a 20 62 65 20 6c 61 72 67 65  also.** be large
5850: 72 20 74 68 61 6e 20 74 68 65 20 72 65 6c 65 61  r than the relea
5860: 73 65 20 66 72 6f 6d 20 77 68 69 63 68 20 69 74  se from which it
5870: 20 69 73 20 64 65 72 69 76 65 64 2e 20 20 45 69   is derived.  Ei
5880: 74 68 65 72 20 59 20 77 69 6c 6c 0a 2a 2a 20 62  ther Y will.** b
5890: 65 20 68 65 6c 64 20 63 6f 6e 73 74 61 6e 74 20  e held constant 
58a0: 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65 20 69 6e  and Z will be in
58b0: 63 72 65 6d 65 6e 74 65 64 20 6f 72 20 65 6c 73  cremented or els
58c0: 65 20 59 20 77 69 6c 6c 20 62 65 20 69 6e 63 72  e Y will be incr
58d0: 65 6d 65 6e 74 65 64 0a 2a 2a 20 61 6e 64 20 5a  emented.** and Z
58e0: 20 77 69 6c 6c 20 62 65 20 72 65 73 65 74 20 74   will be reset t
58f0: 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 69  o zero..**.** Si
5900: 6e 63 65 20 76 65 72 73 69 6f 6e 20 33 2e 36 2e  nce version 3.6.
5910: 31 38 2c 20 53 51 4c 69 74 65 20 73 6f 75 72 63  18, SQLite sourc
5920: 65 20 63 6f 64 65 20 68 61 73 20 62 65 65 6e 20  e code has been 
5930: 73 74 6f 72 65 64 20 69 6e 20 74 68 65 0a 2a 2a  stored in the.**
5940: 20 3c 61 20 68 72 65 66 3d 22 68 74 74 70 3a 2f   <a href="http:/
5950: 2f 77 77 77 2e 66 6f 73 73 69 6c 2d 73 63 6d 2e  /www.fossil-scm.
5960: 6f 72 67 2f 22 3e 46 6f 73 73 69 6c 20 63 6f 6e  org/">Fossil con
5970: 66 69 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67  figuration manag
5980: 65 6d 65 6e 74 0a 2a 2a 20 73 79 73 74 65 6d 3c  ement.** system<
5990: 2f 61 3e 2e 20 20 5e 54 68 65 20 53 51 4c 49 54  /a>.  ^The SQLIT
59a0: 45 5f 53 4f 55 52 43 45 5f 49 44 20 6d 61 63 72  E_SOURCE_ID macr
59b0: 6f 20 65 76 61 6c 75 61 74 65 73 20 74 6f 0a 2a  o evaluates to.*
59c0: 2a 20 61 20 73 74 72 69 6e 67 20 77 68 69 63 68  * a string which
59d0: 20 69 64 65 6e 74 69 66 69 65 73 20 61 20 70 61   identifies a pa
59e0: 72 74 69 63 75 6c 61 72 20 63 68 65 63 6b 2d 69  rticular check-i
59f0: 6e 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 77  n of SQLite.** w
5a00: 69 74 68 69 6e 20 69 74 73 20 63 6f 6e 66 69 67  ithin its config
5a10: 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65  uration manageme
5a20: 6e 74 20 73 79 73 74 65 6d 2e 20 20 5e 54 68 65  nt system.  ^The
5a30: 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49   SQLITE_SOURCE_I
5a40: 44 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74  D.** string cont
5a50: 61 69 6e 73 20 74 68 65 20 64 61 74 65 20 61 6e  ains the date an
5a60: 64 20 74 69 6d 65 20 6f 66 20 74 68 65 20 63 68  d time of the ch
5a70: 65 63 6b 2d 69 6e 20 28 55 54 43 29 20 61 6e 64  eck-in (UTC) and
5a80: 20 61 6e 20 53 48 41 31 0a 2a 2a 20 68 61 73 68   an SHA1.** hash
5a90: 20 6f 66 20 74 68 65 20 65 6e 74 69 72 65 20 73   of the entire s
5aa0: 6f 75 72 63 65 20 74 72 65 65 2e 0a 2a 2a 0a 2a  ource tree..**.*
5ab0: 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
5ac0: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28  ite3_libversion(
5ad0: 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
5ae0: 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65  libversion_numbe
5af0: 72 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73  r()], [sqlite3_s
5b00: 6f 75 72 63 65 69 64 28 29 5d 2c 0a 2a 2a 20 5b  ourceid()],.** [
5b10: 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28 29  sqlite_version()
5b20: 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73 6f  ] and [sqlite_so
5b30: 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a 23  urce_id()]..*/.#
5b40: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 45  define SQLITE_VE
5b50: 52 53 49 4f 4e 20 20 20 20 20 20 20 20 22 33 2e  RSION        "3.
5b60: 37 2e 38 22 0a 23 64 65 66 69 6e 65 20 53 51 4c  7.8".#define SQL
5b70: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42  ITE_VERSION_NUMB
5b80: 45 52 20 33 30 30 37 30 30 38 0a 23 64 65 66 69  ER 3007008.#defi
5b90: 6e 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45  ne SQLITE_SOURCE
5ba0: 5f 49 44 20 20 20 20 20 20 22 32 30 31 31 2d 30  _ID      "2011-0
5bb0: 39 2d 31 37 20 31 35 3a 33 34 3a 35 30 20 32 39  9-17 15:34:50 29
5bc0: 63 34 64 30 64 64 34 33 64 34 31 36 35 30 65 35  c4d0dd43d41650e5
5bd0: 34 38 32 34 61 66 64 37 30 64 64 34 30 66 31 62  4824afd70dd40f1b
5be0: 39 31 63 63 38 36 22 0a 0a 2f 2a 0a 2a 2a 20 43  91cc86"../*.** C
5bf0: 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d  API3REF: Run-Tim
5c00: 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f  e Library Versio
5c10: 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b 45 59  n Numbers.** KEY
5c20: 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76  WORDS: sqlite3_v
5c30: 65 72 73 69 6f 6e 2c 20 73 71 6c 69 74 65 33 5f  ersion, sqlite3_
5c40: 73 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a 20 54  sourceid.**.** T
5c50: 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20  hese interfaces 
5c60: 70 72 6f 76 69 64 65 20 74 68 65 20 73 61 6d 65  provide the same
5c70: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20   information as 
5c80: 74 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  the [SQLITE_VERS
5c90: 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  ION],.** [SQLITE
5ca0: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d  _VERSION_NUMBER]
5cb0: 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 53 4f  , and [SQLITE_SO
5cc0: 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70 72  URCE_ID] C prepr
5cd0: 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 73 0a 2a  ocessor macros.*
5ce0: 2a 20 62 75 74 20 61 72 65 20 61 73 73 6f 63 69  * but are associ
5cf0: 61 74 65 64 20 77 69 74 68 20 74 68 65 20 6c 69  ated with the li
5d00: 62 72 61 72 79 20 69 6e 73 74 65 61 64 20 6f 66  brary instead of
5d10: 20 74 68 65 20 68 65 61 64 65 72 20 66 69 6c 65   the header file
5d20: 2e 20 20 5e 28 43 61 75 74 69 6f 75 73 0a 2a 2a  .  ^(Cautious.**
5d30: 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67   programmers mig
5d40: 68 74 20 69 6e 63 6c 75 64 65 20 61 73 73 65 72  ht include asser
5d50: 74 28 29 20 73 74 61 74 65 6d 65 6e 74 73 20 69  t() statements i
5d60: 6e 20 74 68 65 69 72 20 61 70 70 6c 69 63 61 74  n their applicat
5d70: 69 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72 69 66 79  ion to.** verify
5d80: 20 74 68 61 74 20 76 61 6c 75 65 73 20 72 65 74   that values ret
5d90: 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 69  urned by these i
5da0: 6e 74 65 72 66 61 63 65 73 20 6d 61 74 63 68 20  nterfaces match 
5db0: 74 68 65 20 6d 61 63 72 6f 73 20 69 6e 0a 2a 2a  the macros in.**
5dc0: 20 74 68 65 20 68 65 61 64 65 72 2c 20 61 6e 64   the header, and
5dd0: 20 74 68 75 73 20 69 6e 73 75 72 65 20 74 68 61   thus insure tha
5de0: 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  t the applicatio
5df0: 6e 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64  n is.** compiled
5e00: 20 77 69 74 68 20 6d 61 74 63 68 69 6e 67 20 6c   with matching l
5e10: 69 62 72 61 72 79 20 61 6e 64 20 68 65 61 64 65  ibrary and heade
5e20: 72 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c  r files..**.** <
5e30: 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
5e40: 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 71 6c 69  .** assert( sqli
5e50: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e  te3_libversion_n
5e60: 75 6d 62 65 72 28 29 3d 3d 53 51 4c 49 54 45 5f  umber()==SQLITE_
5e70: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 29  VERSION_NUMBER )
5e80: 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72  ;.** assert( str
5e90: 63 6d 70 28 73 71 6c 69 74 65 33 5f 73 6f 75 72  cmp(sqlite3_sour
5ea0: 63 65 69 64 28 29 2c 53 51 4c 49 54 45 5f 53 4f  ceid(),SQLITE_SO
5eb0: 55 52 43 45 5f 49 44 29 3d 3d 30 20 29 3b 0a 2a  URCE_ID)==0 );.*
5ec0: 2a 20 61 73 73 65 72 74 28 20 73 74 72 63 6d 70  * assert( strcmp
5ed0: 28 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73  (sqlite3_libvers
5ee0: 69 6f 6e 28 29 2c 53 51 4c 49 54 45 5f 56 45 52  ion(),SQLITE_VER
5ef0: 53 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a 2a 20 3c  SION)==0 );.** <
5f00: 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
5f10: 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  e>)^.**.** ^The 
5f20: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b  sqlite3_version[
5f30: 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e  ] string constan
5f40: 74 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 74  t contains the t
5f50: 65 78 74 20 6f 66 20 5b 53 51 4c 49 54 45 5f 56  ext of [SQLITE_V
5f60: 45 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61 63 72 6f  ERSION].** macro
5f70: 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
5f80: 6c 69 62 76 65 72 73 69 6f 6e 28 29 20 66 75 6e  libversion() fun
5f90: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 20  ction returns a 
5fa0: 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a  pointer to the.*
5fb0: 2a 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  * to the sqlite3
5fc0: 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e  _version[] strin
5fd0: 67 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54 68 65  g constant.  The
5fe0: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
5ff0: 69 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63 74 69 6f  ion().** functio
6000: 6e 20 69 73 20 70 72 6f 76 69 64 65 64 20 66 6f  n is provided fo
6010: 72 20 75 73 65 20 69 6e 20 44 4c 4c 73 20 73 69  r use in DLLs si
6020: 6e 63 65 20 44 4c 4c 20 75 73 65 72 73 20 75 73  nce DLL users us
6030: 75 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68 61 76  ually do not hav
6040: 65 0a 2a 2a 20 64 69 72 65 63 74 20 61 63 63 65  e.** direct acce
6050: 73 73 20 74 6f 20 73 74 72 69 6e 67 20 63 6f 6e  ss to string con
6060: 73 74 61 6e 74 73 20 77 69 74 68 69 6e 20 74 68  stants within th
6070: 65 20 44 4c 4c 2e 20 20 5e 54 68 65 0a 2a 2a 20  e DLL.  ^The.** 
6080: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
6090: 6f 6e 5f 6e 75 6d 62 65 72 28 29 20 66 75 6e 63  on_number() func
60a0: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 6e 20  tion returns an 
60b0: 69 6e 74 65 67 65 72 20 65 71 75 61 6c 20 74 6f  integer equal to
60c0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  .** [SQLITE_VERS
60d0: 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20 5e 54  ION_NUMBER].  ^T
60e0: 68 65 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  he sqlite3_sourc
60f0: 65 69 64 28 29 20 66 75 6e 63 74 69 6f 6e 20 72  eid() function r
6100: 65 74 75 72 6e 73 20 0a 2a 2a 20 61 20 70 6f 69  eturns .** a poi
6110: 6e 74 65 72 20 74 6f 20 61 20 73 74 72 69 6e 67  nter to a string
6120: 20 63 6f 6e 73 74 61 6e 74 20 77 68 6f 73 65 20   constant whose 
6130: 76 61 6c 75 65 20 69 73 20 74 68 65 20 73 61 6d  value is the sam
6140: 65 20 61 73 20 74 68 65 20 0a 2a 2a 20 5b 53 51  e as the .** [SQ
6150: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20  LITE_SOURCE_ID] 
6160: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
6170: 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  acro..**.** See 
6180: 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f 76 65  also: [sqlite_ve
6190: 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71  rsion()] and [sq
61a0: 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29  lite_source_id()
61b0: 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  ]..*/.SQLITE_API
61c0: 20 63 6f 6e 73 74 20 63 68 61 72 20 73 71 6c 69   const char sqli
61d0: 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 3d 20  te3_version[] = 
61e0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 3b 0a  SQLITE_VERSION;.
61f0: 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
6200: 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6c   char *sqlite3_l
6210: 69 62 76 65 72 73 69 6f 6e 28 76 6f 69 64 29 3b  ibversion(void);
6220: 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
6230: 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
6240: 73 6f 75 72 63 65 69 64 28 76 6f 69 64 29 3b 0a  sourceid(void);.
6250: 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
6260: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
6270: 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b 0a  n_number(void);.
6280: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
6290: 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72   Run-Time Librar
62a0: 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f 70  y Compilation Op
62b0: 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69 63  tions Diagnostic
62c0: 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
62d0: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
62e0: 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 74 69  on_used() functi
62f0: 6f 6e 20 72 65 74 75 72 6e 73 20 30 20 6f 72 20  on returns 0 or 
6300: 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67  1 .** indicating
6310: 20 77 68 65 74 68 65 72 20 74 68 65 20 73 70 65   whether the spe
6320: 63 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 77 61  cified option wa
6330: 73 20 64 65 66 69 6e 65 64 20 61 74 20 0a 2a 2a  s defined at .**
6340: 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 20   compile time.  
6350: 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 70 72 65  ^The SQLITE_ pre
6360: 66 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 74 74  fix may be omitt
6370: 65 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a 20  ed from the .** 
6380: 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73 73  option name pass
6390: 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ed to sqlite3_co
63a0: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64  mpileoption_used
63b0: 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ().  .**.** ^The
63c0: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65   sqlite3_compile
63d0: 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 75 6e  option_get() fun
63e0: 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 74 65  ction allows ite
63f0: 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20 74  rating.** over t
6400: 68 65 20 6c 69 73 74 20 6f 66 20 6f 70 74 69 6f  he list of optio
6410: 6e 73 20 74 68 61 74 20 77 65 72 65 20 64 65 66  ns that were def
6420: 69 6e 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 20  ined at compile 
6430: 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75 72  time by.** retur
6440: 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68 20 63 6f  ning the N-th co
6450: 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70 74 69 6f  mpile time optio
6460: 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49 66 20 4e  n string.  ^If N
6470: 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
6480: 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6d  ,.** sqlite3_com
6490: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29  pileoption_get()
64a0: 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20   returns a NULL 
64b0: 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 53  pointer.  ^The S
64c0: 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66 69  QLITE_ .** prefi
64d0: 78 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f  x is omitted fro
64e0: 6d 20 61 6e 79 20 73 74 72 69 6e 67 73 20 72 65  m any strings re
64f0: 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73 71  turned by .** sq
6500: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
6510: 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a 2a  ion_get()..**.**
6520: 20 5e 53 75 70 70 6f 72 74 20 66 6f 72 20 74 68   ^Support for th
6530: 65 20 64 69 61 67 6e 6f 73 74 69 63 20 66 75 6e  e diagnostic fun
6540: 63 74 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f 63  ctions sqlite3_c
6550: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
6560: 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74  d().** and sqlit
6570: 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e  e3_compileoption
6580: 5f 67 65 74 28 29 20 6d 61 79 20 62 65 20 6f 6d  _get() may be om
6590: 69 74 74 65 64 20 62 79 20 73 70 65 63 69 66 79  itted by specify
65a0: 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c  ing the .** [SQL
65b0: 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45  ITE_OMIT_COMPILE
65c0: 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f 70  OPTION_DIAGS] op
65d0: 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65 20  tion at compile 
65e0: 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  time..**.** See 
65f0: 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74 69  also: SQL functi
6600: 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70  ons [sqlite_comp
6610: 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29  ileoption_used()
6620: 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  ] and.** [sqlite
6630: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67  _compileoption_g
6640: 65 74 28 29 5d 20 61 6e 64 20 74 68 65 20 5b 63  et()] and the [c
6650: 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20 70  ompile_options p
6660: 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e 64  ragma]..*/.#ifnd
6670: 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43  ef SQLITE_OMIT_C
6680: 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41  OMPILEOPTION_DIA
6690: 47 53 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  GS.SQLITE_API in
66a0: 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c  t sqlite3_compil
66b0: 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 63 6f 6e  eoption_used(con
66c0: 73 74 20 63 68 61 72 20 2a 7a 4f 70 74 4e 61 6d  st char *zOptNam
66d0: 65 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  e);.SQLITE_API c
66e0: 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
66f0: 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e  e3_compileoption
6700: 5f 67 65 74 28 69 6e 74 20 4e 29 3b 0a 23 65 6e  _get(int N);.#en
6710: 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  dif../*.** CAPI3
6720: 52 45 46 3a 20 54 65 73 74 20 54 6f 20 53 65 65  REF: Test To See
6730: 20 49 66 20 54 68 65 20 4c 69 62 72 61 72 79 20   If The Library 
6740: 49 73 20 54 68 72 65 61 64 73 61 66 65 0a 2a 2a  Is Threadsafe.**
6750: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
6760: 5f 74 68 72 65 61 64 73 61 66 65 28 29 20 66 75  _threadsafe() fu
6770: 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 7a  nction returns z
6780: 65 72 6f 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20  ero if and only 
6790: 69 66 0a 2a 2a 20 53 51 4c 69 74 65 20 77 61 73  if.** SQLite was
67a0: 20 63 6f 6d 70 69 6c 65 64 20 6d 75 74 65 78 69   compiled mutexi
67b0: 6e 67 20 63 6f 64 65 20 6f 6d 69 74 74 65 64 20  ng code omitted 
67c0: 64 75 65 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 53  due to the.** [S
67d0: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
67e0: 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
67f0: 70 74 69 6f 6e 20 62 65 69 6e 67 20 73 65 74 20  ption being set 
6800: 74 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  to 0..**.** SQLi
6810: 74 65 20 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c  te can be compil
6820: 65 64 20 77 69 74 68 20 6f 72 20 77 69 74 68 6f  ed with or witho
6830: 75 74 20 6d 75 74 65 78 65 73 2e 20 20 57 68 65  ut mutexes.  Whe
6840: 6e 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  n.** the [SQLITE
6850: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 43 20 70  _THREADSAFE] C p
6860: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
6870: 6f 20 69 73 20 31 20 6f 72 20 32 2c 20 6d 75 74  o is 1 or 2, mut
6880: 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62  exes.** are enab
6890: 6c 65 64 20 61 6e 64 20 53 51 4c 69 74 65 20 69  led and SQLite i
68a0: 73 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 57  s threadsafe.  W
68b0: 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  hen the.** [SQLI
68c0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d  TE_THREADSAFE] m
68d0: 61 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a 20 74  acro is 0, .** t
68e0: 68 65 20 6d 75 74 65 78 65 73 20 61 72 65 20 6f  he mutexes are o
68f0: 6d 69 74 74 65 64 2e 20 20 57 69 74 68 6f 75 74  mitted.  Without
6900: 20 74 68 65 20 6d 75 74 65 78 65 73 2c 20 69 74   the mutexes, it
6910: 20 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20   is not safe.** 
6920: 74 6f 20 75 73 65 20 53 51 4c 69 74 65 20 63 6f  to use SQLite co
6930: 6e 63 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20  ncurrently from 
6940: 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 68  more than one th
6950: 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62  read..**.** Enab
6960: 6c 69 6e 67 20 6d 75 74 65 78 65 73 20 69 6e 63  ling mutexes inc
6970: 75 72 73 20 61 20 6d 65 61 73 75 72 61 62 6c 65  urs a measurable
6980: 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e   performance pen
6990: 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73  alty..** So if s
69a0: 70 65 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73  peed is of utmos
69b0: 74 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74  t importance, it
69c0: 20 6d 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20   makes sense to 
69d0: 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d  disable.** the m
69e0: 75 74 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72  utexes.  But for
69f0: 20 6d 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c   maximum safety,
6a00: 20 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20   mutexes should 
6a10: 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 5e  be enabled..** ^
6a20: 54 68 65 20 64 65 66 61 75 6c 74 20 62 65 68 61  The default beha
6a30: 76 69 6f 72 20 69 73 20 66 6f 72 20 6d 75 74 65  vior is for mute
6a40: 78 65 73 20 74 6f 20 62 65 20 65 6e 61 62 6c 65  xes to be enable
6a50: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e  d..**.** This in
6a60: 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75  terface can be u
6a70: 73 65 64 20 62 79 20 61 6e 20 61 70 70 6c 69 63  sed by an applic
6a80: 61 74 69 6f 6e 20 74 6f 20 6d 61 6b 65 20 73 75  ation to make su
6a90: 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 76  re that the.** v
6aa0: 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65  ersion of SQLite
6ab0: 20 74 68 61 74 20 69 74 20 69 73 20 6c 69 6e 6b   that it is link
6ac0: 69 6e 67 20 61 67 61 69 6e 73 74 20 77 61 73 20  ing against was 
6ad0: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
6ae0: 20 74 68 65 20 64 65 73 69 72 65 64 20 73 65 74   the desired set
6af0: 74 69 6e 67 20 6f 66 20 74 68 65 20 5b 53 51 4c  ting of the [SQL
6b00: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20  ITE_THREADSAFE] 
6b10: 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  macro..**.** Thi
6b20: 73 20 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79  s interface only
6b30: 20 72 65 70 6f 72 74 73 20 6f 6e 20 74 68 65 20   reports on the 
6b40: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74  compile-time mut
6b50: 65 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66  ex setting.** of
6b60: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
6b70: 45 41 44 53 41 46 45 5d 20 66 6c 61 67 2e 20 20  EADSAFE] flag.  
6b80: 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
6b90: 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53 51  piled with.** SQ
6ba0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
6bb0: 31 20 6f 72 20 3d 32 20 74 68 65 6e 20 6d 75 74  1 or =2 then mut
6bc0: 65 78 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64  exes are enabled
6bd0: 20 62 79 20 64 65 66 61 75 6c 74 20 62 75 74 0a   by default but.
6be0: 2a 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c 79 20  ** can be fully 
6bf0: 6f 72 20 70 61 72 74 69 61 6c 6c 79 20 64 69 73  or partially dis
6c00: 61 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63 61  abled using a ca
6c10: 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ll to [sqlite3_c
6c20: 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69 74 68  onfig()].** with
6c30: 20 74 68 65 20 76 65 72 62 73 20 5b 53 51 4c 49   the verbs [SQLI
6c40: 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
6c50: 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45  THREAD], [SQLITE
6c60: 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
6c70: 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c  EAD],.** or [SQL
6c80: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
6c90: 5d 2e 20 20 5e 28 54 68 65 20 72 65 74 75 72 6e  ].  ^(The return
6ca0: 20 76 61 6c 75 65 20 6f 66 20 74 68 65 0a 2a 2a   value of the.**
6cb0: 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73   sqlite3_threads
6cc0: 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 73  afe() function s
6cd0: 68 6f 77 73 20 6f 6e 6c 79 20 74 68 65 20 63 6f  hows only the co
6ce0: 6d 70 69 6c 65 2d 74 69 6d 65 20 73 65 74 74 69  mpile-time setti
6cf0: 6e 67 20 6f 66 0a 2a 2a 20 74 68 72 65 61 64 20  ng of.** thread 
6d00: 73 61 66 65 74 79 2c 20 6e 6f 74 20 61 6e 79 20  safety, not any 
6d10: 72 75 6e 2d 74 69 6d 65 20 63 68 61 6e 67 65 73  run-time changes
6d20: 20 74 6f 20 74 68 61 74 20 73 65 74 74 69 6e 67   to that setting
6d30: 20 6d 61 64 65 20 62 79 0a 2a 2a 20 73 71 6c 69   made by.** sqli
6d40: 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e 20 49 6e  te3_config(). In
6d50: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
6d60: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66  e return value f
6d70: 72 6f 6d 20 73 71 6c 69 74 65 33 5f 74 68 72 65  rom sqlite3_thre
6d80: 61 64 73 61 66 65 28 29 0a 2a 2a 20 69 73 20 75  adsafe().** is u
6d90: 6e 63 68 61 6e 67 65 64 20 62 79 20 63 61 6c 6c  nchanged by call
6da0: 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e  s to sqlite3_con
6db0: 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53  fig().)^.**.** S
6dc0: 65 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e  ee the [threadin
6dd0: 67 20 6d 6f 64 65 5d 20 64 6f 63 75 6d 65 6e 74  g mode] document
6de0: 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69  ation for additi
6df0: 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
6e00: 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
6e10: 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 68 72 65  int sqlite3_thre
6e20: 61 64 73 61 66 65 28 76 6f 69 64 29 3b 0a 0a 2f  adsafe(void);../
6e30: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
6e40: 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
6e50: 6f 6e 20 48 61 6e 64 6c 65 0a 2a 2a 20 4b 45 59  on Handle.** KEY
6e60: 57 4f 52 44 53 3a 20 7b 64 61 74 61 62 61 73 65  WORDS: {database
6e70: 20 63 6f 6e 6e 65 63 74 69 6f 6e 7d 20 7b 64 61   connection} {da
6e80: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
6e90: 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f  ns}.**.** Each o
6ea0: 70 65 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62  pen SQLite datab
6eb0: 61 73 65 20 69 73 20 72 65 70 72 65 73 65 6e 74  ase is represent
6ec0: 65 64 20 62 79 20 61 20 70 6f 69 6e 74 65 72 20  ed by a pointer 
6ed0: 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
6ee0: 66 0a 2a 2a 20 74 68 65 20 6f 70 61 71 75 65 20  f.** the opaque 
6ef0: 73 74 72 75 63 74 75 72 65 20 6e 61 6d 65 64 20  structure named 
6f00: 22 73 71 6c 69 74 65 33 22 2e 20 20 49 74 20 69  "sqlite3".  It i
6f10: 73 20 75 73 65 66 75 6c 20 74 6f 20 74 68 69 6e  s useful to thin
6f20: 6b 20 6f 66 20 61 6e 20 73 71 6c 69 74 65 33 0a  k of an sqlite3.
6f30: 2a 2a 20 70 6f 69 6e 74 65 72 20 61 73 20 61 6e  ** pointer as an
6f40: 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 5b 73   object.  The [s
6f50: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20  qlite3_open()], 
6f60: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
6f70: 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
6f80: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69  te3_open_v2()] i
6f90: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 69 74  nterfaces are it
6fa0: 73 20 63 6f 6e 73 74 72 75 63 74 6f 72 73 2c 20  s constructors, 
6fb0: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f  and [sqlite3_clo
6fc0: 73 65 28 29 5d 0a 2a 2a 20 69 73 20 69 74 73 20  se()].** is its 
6fd0: 64 65 73 74 72 75 63 74 6f 72 2e 20 20 54 68 65  destructor.  The
6fe0: 72 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65  re are many othe
6ff0: 72 20 69 6e 74 65 72 66 61 63 65 73 20 28 73 75  r interfaces (su
7000: 63 68 20 61 73 0a 2a 2a 20 5b 73 71 6c 69 74 65  ch as.** [sqlite
7010: 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c  3_prepare_v2()],
7020: 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
7030: 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 61 6e  _function()], an
7040: 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75  d.** [sqlite3_bu
7050: 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 74 6f  sy_timeout()] to
7060: 20 6e 61 6d 65 20 62 75 74 20 74 68 72 65 65 29   name but three)
7070: 20 74 68 61 74 20 61 72 65 20 6d 65 74 68 6f 64   that are method
7080: 73 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74  s on an.** sqlit
7090: 65 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79  e3 object..*/.ty
70a0: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
70b0: 69 74 65 33 20 73 71 6c 69 74 65 33 3b 0a 0a 2f  ite3 sqlite3;../
70c0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 36  *.** CAPI3REF: 6
70d0: 34 2d 42 69 74 20 49 6e 74 65 67 65 72 20 54 79  4-Bit Integer Ty
70e0: 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  pes.** KEYWORDS:
70f0: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71   sqlite_int64 sq
7100: 6c 69 74 65 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a  lite_uint64.**.*
7110: 2a 20 42 65 63 61 75 73 65 20 74 68 65 72 65 20  * Because there 
7120: 69 73 20 6e 6f 20 63 72 6f 73 73 2d 70 6c 61 74  is no cross-plat
7130: 66 6f 72 6d 20 77 61 79 20 74 6f 20 73 70 65 63  form way to spec
7140: 69 66 79 20 36 34 2d 62 69 74 20 69 6e 74 65 67  ify 64-bit integ
7150: 65 72 20 74 79 70 65 73 0a 2a 2a 20 53 51 4c 69  er types.** SQLi
7160: 74 65 20 69 6e 63 6c 75 64 65 73 20 74 79 70 65  te includes type
7170: 64 65 66 73 20 66 6f 72 20 36 34 2d 62 69 74 20  defs for 64-bit 
7180: 73 69 67 6e 65 64 20 61 6e 64 20 75 6e 73 69 67  signed and unsig
7190: 6e 65 64 20 69 6e 74 65 67 65 72 73 2e 0a 2a 2a  ned integers..**
71a0: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
71b0: 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65  int64 and sqlite
71c0: 33 5f 75 69 6e 74 36 34 20 61 72 65 20 74 68 65  3_uint64 are the
71d0: 20 70 72 65 66 65 72 72 65 64 20 74 79 70 65 20   preferred type 
71e0: 64 65 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20  definitions..** 
71f0: 54 68 65 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  The sqlite_int64
7200: 20 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74   and sqlite_uint
7210: 36 34 20 74 79 70 65 73 20 61 72 65 20 73 75 70  64 types are sup
7220: 70 6f 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77  ported for backw
7230: 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62  ards.** compatib
7240: 69 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a  ility only..**.*
7250: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69  * ^The sqlite3_i
7260: 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f  nt64 and sqlite_
7270: 69 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e 20  int64 types can 
7280: 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61  store integer va
7290: 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20  lues.** between 
72a0: 2d 39 32 32 33 33 37 32 30 33 36 38 35 34 37 37  -922337203685477
72b0: 35 38 30 38 20 61 6e 64 20 2b 39 32 32 33 33 37  5808 and +922337
72c0: 32 30 33 36 38 35 34 37 37 35 38 30 37 20 69 6e  2036854775807 in
72d0: 63 6c 75 73 69 76 65 2e 20 20 5e 54 68 65 0a 2a  clusive.  ^The.*
72e0: 2a 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  * sqlite3_uint64
72f0: 20 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74   and sqlite_uint
7300: 36 34 20 74 79 70 65 73 20 63 61 6e 20 73 74 6f  64 types can sto
7310: 72 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65  re integer value
7320: 73 20 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 20  s .** between 0 
7330: 61 6e 64 20 2b 31 38 34 34 36 37 34 34 30 37 33  and +18446744073
7340: 37 30 39 35 35 31 36 31 35 20 69 6e 63 6c 75 73  709551615 inclus
7350: 69 76 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53  ive..*/.#ifdef S
7360: 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45  QLITE_INT64_TYPE
7370: 0a 20 20 74 79 70 65 64 65 66 20 53 51 4c 49 54  .  typedef SQLIT
7380: 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c  E_INT64_TYPE sql
7390: 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70  ite_int64;.  typ
73a0: 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 53 51  edef unsigned SQ
73b0: 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20  LITE_INT64_TYPE 
73c0: 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23  sqlite_uint64;.#
73d0: 65 6c 69 66 20 64 65 66 69 6e 65 64 28 5f 4d 53  elif defined(_MS
73e0: 43 5f 56 45 52 29 20 7c 7c 20 64 65 66 69 6e 65  C_VER) || define
73f0: 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29 0a  d(__BORLANDC__).
7400: 20 20 74 79 70 65 64 65 66 20 5f 5f 69 6e 74 36    typedef __int6
7410: 34 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a  4 sqlite_int64;.
7420: 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e    typedef unsign
7430: 65 64 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74  ed __int64 sqlit
7440: 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 73 65 0a  e_uint64;.#else.
7450: 20 20 74 79 70 65 64 65 66 20 6c 6f 6e 67 20 6c    typedef long l
7460: 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 69  ong int sqlite_i
7470: 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20  nt64;.  typedef 
7480: 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67 20 6c 6f  unsigned long lo
7490: 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 75 69  ng int sqlite_ui
74a0: 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a 74 79 70  nt64;.#endif.typ
74b0: 65 64 65 66 20 73 71 6c 69 74 65 5f 69 6e 74 36  edef sqlite_int6
74c0: 34 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 3b  4 sqlite3_int64;
74d0: 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f  .typedef sqlite_
74e0: 75 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75  uint64 sqlite3_u
74f0: 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49 66  int64;../*.** If
7500: 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f 72 20 61   compiling for a
7510: 20 70 72 6f 63 65 73 73 6f 72 20 74 68 61 74 20   processor that 
7520: 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e 67 20 70  lacks floating p
7530: 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c 0a 2a 2a  oint support,.**
7540: 20 73 75 62 73 74 69 74 75 74 65 20 69 6e 74 65   substitute inte
7550: 67 65 72 20 66 6f 72 20 66 6c 6f 61 74 69 6e 67  ger for floating
7560: 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69 66 64 65  -point..*/.#ifde
7570: 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c  f SQLITE_OMIT_FL
7580: 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 20 64  OATING_POINT.# d
7590: 65 66 69 6e 65 20 64 6f 75 62 6c 65 20 73 71 6c  efine double sql
75a0: 69 74 65 33 5f 69 6e 74 36 34 0a 23 65 6e 64 69  ite3_int64.#endi
75b0: 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  f../*.** CAPI3RE
75c0: 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20 44 61 74  F: Closing A Dat
75d0: 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e  abase Connection
75e0: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
75f0: 74 65 33 5f 63 6c 6f 73 65 28 29 20 72 6f 75 74  te3_close() rout
7600: 69 6e 65 20 69 73 20 74 68 65 20 64 65 73 74 72  ine is the destr
7610: 75 63 74 6f 72 20 66 6f 72 20 74 68 65 20 5b 73  uctor for the [s
7620: 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2e 0a  qlite3] object..
7630: 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c  ** ^Calls to sql
7640: 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 72 65 74  ite3_close() ret
7650: 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66  urn SQLITE_OK if
7660: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f   the [sqlite3] o
7670: 62 6a 65 63 74 20 69 73 0a 2a 2a 20 73 75 63 63  bject is.** succ
7680: 65 73 73 66 75 6c 6c 79 20 64 65 73 74 72 6f 79  essfully destroy
7690: 65 64 20 61 6e 64 20 61 6c 6c 20 61 73 73 6f 63  ed and all assoc
76a0: 69 61 74 65 64 20 72 65 73 6f 75 72 63 65 73 20  iated resources 
76b0: 61 72 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 2e  are deallocated.
76c0: 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  .**.** Applicati
76d0: 6f 6e 73 20 6d 75 73 74 20 5b 73 71 6c 69 74 65  ons must [sqlite
76e0: 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e  3_finalize | fin
76f0: 61 6c 69 7a 65 5d 20 61 6c 6c 20 5b 70 72 65 70  alize] all [prep
7700: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d  ared statements]
7710: 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
7720: 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20 63 6c  _blob_close | cl
7730: 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f 42 20 68  ose] all [BLOB h
7740: 61 6e 64 6c 65 73 5d 20 61 73 73 6f 63 69 61 74  andles] associat
7750: 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
7760: 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20  sqlite3] object 
7770: 70 72 69 6f 72 20 74 6f 20 61 74 74 65 6d 70 74  prior to attempt
7780: 69 6e 67 20 74 6f 20 63 6c 6f 73 65 20 74 68 65  ing to close the
7790: 20 6f 62 6a 65 63 74 2e 20 20 5e 49 66 0a 2a 2a   object.  ^If.**
77a0: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29   sqlite3_close()
77b0: 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20   is called on a 
77c0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
77d0: 74 69 6f 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c  tion] that still
77e0: 20 68 61 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64   has.** outstand
77f0: 69 6e 67 20 5b 70 72 65 70 61 72 65 64 20 73 74  ing [prepared st
7800: 61 74 65 6d 65 6e 74 73 5d 20 6f 72 20 5b 42 4c  atements] or [BL
7810: 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20 74 68 65  OB handles], the
7820: 6e 20 69 74 20 72 65 74 75 72 6e 73 0a 2a 2a 20  n it returns.** 
7830: 53 51 4c 49 54 45 5f 42 55 53 59 2e 0a 2a 2a 0a  SQLITE_BUSY..**.
7840: 2a 2a 20 5e 49 66 20 5b 73 71 6c 69 74 65 33 5f  ** ^If [sqlite3_
7850: 63 6c 6f 73 65 28 29 5d 20 69 73 20 69 6e 76 6f  close()] is invo
7860: 6b 65 64 20 77 68 69 6c 65 20 61 20 74 72 61 6e  ked while a tran
7870: 73 61 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 2c  saction is open,
7880: 0a 2a 2a 20 74 68 65 20 74 72 61 6e 73 61 63 74  .** the transact
7890: 69 6f 6e 20 69 73 20 61 75 74 6f 6d 61 74 69 63  ion is automatic
78a0: 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b  ally rolled back
78b0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 20 70 61  ..**.** The C pa
78c0: 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
78d0: 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 6d 75  te3_close(C)] mu
78e0: 73 74 20 62 65 20 65 69 74 68 65 72 20 61 20 4e  st be either a N
78f0: 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 6f  ULL.** pointer o
7900: 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f  r an [sqlite3] o
7910: 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 6f 62  bject pointer ob
7920: 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b  tained.** from [
7930: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
7940: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
7950: 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  ()], or.** [sqli
7960: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20  te3_open_v2()], 
7970: 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f 75 73  and not previous
7980: 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e 43  ly closed..** ^C
7990: 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 63  alling sqlite3_c
79a0: 6c 6f 73 65 28 29 20 77 69 74 68 20 61 20 4e 55  lose() with a NU
79b0: 4c 4c 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d  LL pointer argum
79c0: 65 6e 74 20 69 73 20 61 20 0a 2a 2a 20 68 61 72  ent is a .** har
79d0: 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a  mless no-op..*/.
79e0: 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
79f0: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 73 71 6c  qlite3_close(sql
7a00: 69 74 65 33 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ite3 *);../*.** 
7a10: 54 68 65 20 74 79 70 65 20 66 6f 72 20 61 20 63  The type for a c
7a20: 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
7a30: 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 6c 65 67  ..** This is leg
7a40: 61 63 79 20 61 6e 64 20 64 65 70 72 65 63 61 74  acy and deprecat
7a50: 65 64 2e 20 20 49 74 20 69 73 20 69 6e 63 6c 75  ed.  It is inclu
7a60: 64 65 64 20 66 6f 72 20 68 69 73 74 6f 72 69 63  ded for historic
7a70: 61 6c 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c  al.** compatibil
7a80: 69 74 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 64  ity and is not d
7a90: 6f 63 75 6d 65 6e 74 65 64 2e 0a 2a 2f 0a 74 79  ocumented..*/.ty
7aa0: 70 65 64 65 66 20 69 6e 74 20 28 2a 73 71 6c 69  pedef int (*sqli
7ab0: 74 65 33 5f 63 61 6c 6c 62 61 63 6b 29 28 76 6f  te3_callback)(vo
7ac0: 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 20  id*,int,char**, 
7ad0: 63 68 61 72 2a 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  char**);../*.** 
7ae0: 43 41 50 49 33 52 45 46 3a 20 4f 6e 65 2d 53 74  CAPI3REF: One-St
7af0: 65 70 20 51 75 65 72 79 20 45 78 65 63 75 74 69  ep Query Executi
7b00: 6f 6e 20 49 6e 74 65 72 66 61 63 65 0a 2a 2a 0a  on Interface.**.
7b10: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65  ** The sqlite3_e
7b20: 78 65 63 28 29 20 69 6e 74 65 72 66 61 63 65 20  xec() interface 
7b30: 69 73 20 61 20 63 6f 6e 76 65 6e 69 65 6e 63 65  is a convenience
7b40: 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a   wrapper around.
7b50: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
7b60: 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69  are_v2()], [sqli
7b70: 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 61 6e 64  te3_step()], and
7b80: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
7b90: 7a 65 28 29 5d 2c 0a 2a 2a 20 74 68 61 74 20 61  ze()],.** that a
7ba0: 6c 6c 6f 77 73 20 61 6e 20 61 70 70 6c 69 63 61  llows an applica
7bb0: 74 69 6f 6e 20 74 6f 20 72 75 6e 20 6d 75 6c 74  tion to run mult
7bc0: 69 70 6c 65 20 73 74 61 74 65 6d 65 6e 74 73 20  iple statements 
7bd0: 6f 66 20 53 51 4c 0a 2a 2a 20 77 69 74 68 6f 75  of SQL.** withou
7be0: 74 20 68 61 76 69 6e 67 20 74 6f 20 75 73 65 20  t having to use 
7bf0: 61 20 6c 6f 74 20 6f 66 20 43 20 63 6f 64 65 2e  a lot of C code.
7c00: 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c   .**.** ^The sql
7c10: 69 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65  ite3_exec() inte
7c20: 72 66 61 63 65 20 72 75 6e 73 20 7a 65 72 6f 20  rface runs zero 
7c30: 6f 72 20 6d 6f 72 65 20 55 54 46 2d 38 20 65 6e  or more UTF-8 en
7c40: 63 6f 64 65 64 2c 0a 2a 2a 20 73 65 6d 69 63 6f  coded,.** semico
7c50: 6c 6f 6e 2d 73 65 70 61 72 61 74 65 20 53 51 4c  lon-separate SQL
7c60: 20 73 74 61 74 65 6d 65 6e 74 73 20 70 61 73 73   statements pass
7c70: 65 64 20 69 6e 74 6f 20 69 74 73 20 32 6e 64 20  ed into its 2nd 
7c80: 61 72 67 75 6d 65 6e 74 2c 0a 2a 2a 20 69 6e 20  argument,.** in 
7c90: 74 68 65 20 63 6f 6e 74 65 78 74 20 6f 66 20 74  the context of t
7ca0: 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
7cb0: 6e 65 63 74 69 6f 6e 5d 20 70 61 73 73 65 64 20  nection] passed 
7cc0: 69 6e 20 61 73 20 69 74 73 20 31 73 74 0a 2a 2a  in as its 1st.**
7cd0: 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 49 66 20   argument.  ^If 
7ce0: 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  the callback fun
7cf0: 63 74 69 6f 6e 20 6f 66 20 74 68 65 20 33 72 64  ction of the 3rd
7d00: 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
7d10: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
7d20: 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e  s not NULL, then
7d30: 20 69 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 66   it is invoked f
7d40: 6f 72 20 65 61 63 68 20 72 65 73 75 6c 74 20 72  or each result r
7d50: 6f 77 0a 2a 2a 20 63 6f 6d 69 6e 67 20 6f 75 74  ow.** coming out
7d60: 20 6f 66 20 74 68 65 20 65 76 61 6c 75 61 74 65   of the evaluate
7d70: 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  d SQL statements
7d80: 2e 20 20 5e 54 68 65 20 34 74 68 20 61 72 67 75  .  ^The 4th argu
7d90: 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  ment to.** sqlit
7da0: 65 33 5f 65 78 65 63 28 29 20 69 73 20 72 65 6c  e3_exec() is rel
7db0: 61 79 65 64 20 74 68 72 6f 75 67 68 20 74 6f 20  ayed through to 
7dc0: 74 68 65 20 31 73 74 20 61 72 67 75 6d 65 6e 74  the 1st argument
7dd0: 20 6f 66 20 65 61 63 68 0a 2a 2a 20 63 61 6c 6c   of each.** call
7de0: 62 61 63 6b 20 69 6e 76 6f 63 61 74 69 6f 6e 2e  back invocation.
7df0: 20 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61    ^If the callba
7e00: 63 6b 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71  ck pointer to sq
7e10: 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20  lite3_exec().** 
7e20: 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 6e 6f  is NULL, then no
7e30: 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 65 76 65   callback is eve
7e40: 72 20 69 6e 76 6f 6b 65 64 20 61 6e 64 20 72 65  r invoked and re
7e50: 73 75 6c 74 20 72 6f 77 73 20 61 72 65 0a 2a 2a  sult rows are.**
7e60: 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20   ignored..**.** 
7e70: 5e 49 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63  ^If an error occ
7e80: 75 72 73 20 77 68 69 6c 65 20 65 76 61 6c 75 61  urs while evalua
7e90: 74 69 6e 67 20 74 68 65 20 53 51 4c 20 73 74 61  ting the SQL sta
7ea0: 74 65 6d 65 6e 74 73 20 70 61 73 73 65 64 20 69  tements passed i
7eb0: 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65  nto.** sqlite3_e
7ec0: 78 65 63 28 29 2c 20 74 68 65 6e 20 65 78 65 63  xec(), then exec
7ed0: 75 74 69 6f 6e 20 6f 66 20 74 68 65 20 63 75 72  ution of the cur
7ee0: 72 65 6e 74 20 73 74 61 74 65 6d 65 6e 74 20 73  rent statement s
7ef0: 74 6f 70 73 20 61 6e 64 0a 2a 2a 20 73 75 62 73  tops and.** subs
7f00: 65 71 75 65 6e 74 20 73 74 61 74 65 6d 65 6e 74  equent statement
7f10: 73 20 61 72 65 20 73 6b 69 70 70 65 64 2e 20 20  s are skipped.  
7f20: 5e 49 66 20 74 68 65 20 35 74 68 20 70 61 72 61  ^If the 5th para
7f30: 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
7f40: 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73 20 6e 6f  _exec().** is no
7f50: 74 20 4e 55 4c 4c 20 74 68 65 6e 20 61 6e 79 20  t NULL then any 
7f60: 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 69 73  error message is
7f70: 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65   written into me
7f80: 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 0a 2a 2a  mory obtained.**
7f90: 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
7fa0: 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 70 61 73  alloc()] and pas
7fb0: 73 65 64 20 62 61 63 6b 20 74 68 72 6f 75 67 68  sed back through
7fc0: 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74   the 5th paramet
7fd0: 65 72 2e 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20  er..** To avoid 
7fe0: 6d 65 6d 6f 72 79 20 6c 65 61 6b 73 2c 20 74 68  memory leaks, th
7ff0: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
8000: 6f 75 6c 64 20 69 6e 76 6f 6b 65 20 5b 73 71 6c  ould invoke [sql
8010: 69 74 65 33 5f 66 72 65 65 28 29 5d 0a 2a 2a 20  ite3_free()].** 
8020: 6f 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  on error message
8030: 20 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65   strings returne
8040: 64 20 74 68 72 6f 75 67 68 20 74 68 65 20 35 74  d through the 5t
8050: 68 20 70 61 72 61 6d 65 74 65 72 20 6f 66 0a 2a  h parameter of.*
8060: 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 65 78 65  * of sqlite3_exe
8070: 63 28 29 20 61 66 74 65 72 20 74 68 65 20 65 72  c() after the er
8080: 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69  ror message stri
8090: 6e 67 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20  ng is no longer 
80a0: 6e 65 65 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 74  needed..** ^If t
80b0: 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
80c0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63   to sqlite3_exec
80d0: 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61  () is not NULL a
80e0: 6e 64 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20  nd no errors.** 
80f0: 6f 63 63 75 72 2c 20 74 68 65 6e 20 73 71 6c 69  occur, then sqli
8100: 74 65 33 5f 65 78 65 63 28 29 20 73 65 74 73 20  te3_exec() sets 
8110: 74 68 65 20 70 6f 69 6e 74 65 72 20 69 6e 20 69  the pointer in i
8120: 74 73 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  ts 5th parameter
8130: 20 74 6f 0a 2a 2a 20 4e 55 4c 4c 20 62 65 66 6f   to.** NULL befo
8140: 72 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a  re returning..**
8150: 0a 2a 2a 20 5e 49 66 20 61 6e 20 73 71 6c 69 74  .** ^If an sqlit
8160: 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61  e3_exec() callba
8170: 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a  ck returns non-z
8180: 65 72 6f 2c 20 74 68 65 20 73 71 6c 69 74 65 33  ero, the sqlite3
8190: 5f 65 78 65 63 28 29 0a 2a 2a 20 72 6f 75 74 69  _exec().** routi
81a0: 6e 65 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54  ne returns SQLIT
81b0: 45 5f 41 42 4f 52 54 20 77 69 74 68 6f 75 74 20  E_ABORT without 
81c0: 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 63 61 6c  invoking the cal
81d0: 6c 62 61 63 6b 20 61 67 61 69 6e 20 61 6e 64 0a  lback again and.
81e0: 2a 2a 20 77 69 74 68 6f 75 74 20 72 75 6e 6e 69  ** without runni
81f0: 6e 67 20 61 6e 79 20 73 75 62 73 65 71 75 65 6e  ng any subsequen
8200: 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  t SQL statements
8210: 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 32 6e 64  ..**.** ^The 2nd
8220: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
8230: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
8240: 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
8250: 6e 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62  n is the.** numb
8260: 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
8270: 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20 5e 54   the result.  ^T
8280: 68 65 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20  he 3rd argument 
8290: 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65  to the sqlite3_e
82a0: 78 65 63 28 29 0a 2a 2a 20 63 61 6c 6c 62 61 63  xec().** callbac
82b0: 6b 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66  k is an array of
82c0: 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72   pointers to str
82d0: 69 6e 67 73 20 6f 62 74 61 69 6e 65 64 20 61 73  ings obtained as
82e0: 20 69 66 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c   if from.** [sql
82f0: 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
8300: 28 29 5d 2c 20 6f 6e 65 20 66 6f 72 20 65 61 63  ()], one for eac
8310: 68 20 63 6f 6c 75 6d 6e 2e 20 20 5e 49 66 20 61  h column.  ^If a
8320: 6e 20 65 6c 65 6d 65 6e 74 20 6f 66 20 61 0a 2a  n element of a.*
8330: 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 69 73 20  * result row is 
8340: 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 63 6f  NULL then the co
8350: 72 72 65 73 70 6f 6e 64 69 6e 67 20 73 74 72 69  rresponding stri
8360: 6e 67 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74  ng pointer for t
8370: 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78  he.** sqlite3_ex
8380: 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73  ec() callback is
8390: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
83a0: 20 20 5e 54 68 65 20 34 74 68 20 61 72 67 75 6d    ^The 4th argum
83b0: 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20 73 71  ent to the.** sq
83c0: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c  lite3_exec() cal
83d0: 6c 62 61 63 6b 20 69 73 20 61 6e 20 61 72 72 61  lback is an arra
83e0: 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f  y of pointers to
83f0: 20 73 74 72 69 6e 67 73 20 77 68 65 72 65 20 65   strings where e
8400: 61 63 68 0a 2a 2a 20 65 6e 74 72 79 20 72 65 70  ach.** entry rep
8410: 72 65 73 65 6e 74 73 20 74 68 65 20 6e 61 6d 65  resents the name
8420: 20 6f 66 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e   of correspondin
8430: 67 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  g result column 
8440: 61 73 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66  as obtained.** f
8450: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  rom [sqlite3_col
8460: 75 6d 6e 5f 6e 61 6d 65 28 29 5d 2e 0a 2a 2a 0a  umn_name()]..**.
8470: 2a 2a 20 5e 49 66 20 74 68 65 20 32 6e 64 20 70  ** ^If the 2nd p
8480: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
8490: 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 61 20  te3_exec() is a 
84a0: 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 61 20  NULL pointer, a 
84b0: 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 61 6e  pointer.** to an
84c0: 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 6f   empty string, o
84d0: 72 20 61 20 70 6f 69 6e 74 65 72 20 74 68 61 74  r a pointer that
84e0: 20 63 6f 6e 74 61 69 6e 73 20 6f 6e 6c 79 20 77   contains only w
84f0: 68 69 74 65 73 70 61 63 65 20 61 6e 64 2f 6f 72  hitespace and/or
8500: 20 0a 2a 2a 20 53 51 4c 20 63 6f 6d 6d 65 6e 74   .** SQL comment
8510: 73 2c 20 74 68 65 6e 20 6e 6f 20 53 51 4c 20 73  s, then no SQL s
8520: 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 65 76  tatements are ev
8530: 61 6c 75 61 74 65 64 20 61 6e 64 20 74 68 65 20  aluated and the 
8540: 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 6e  database.** is n
8550: 6f 74 20 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a  ot changed..**.*
8560: 2a 20 52 65 73 74 72 69 63 74 69 6f 6e 73 3a 0a  * Restrictions:.
8570: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
8580: 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  i> The applicati
8590: 6f 6e 20 6d 75 73 74 20 69 6e 73 75 72 65 20 74  on must insure t
85a0: 68 61 74 20 74 68 65 20 31 73 74 20 70 61 72 61  hat the 1st para
85b0: 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
85c0: 5f 65 78 65 63 28 29 0a 2a 2a 20 20 20 20 20 20  _exec().**      
85d0: 69 73 20 61 20 76 61 6c 69 64 20 61 6e 64 20 6f  is a valid and o
85e0: 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f  pen [database co
85f0: 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 3c 6c  nnection]..** <l
8600: 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  i> The applicati
8610: 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73  on must not clos
8620: 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
8630: 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65  ection] specifie
8640: 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 74 68 65  d by.**      the
8650: 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 20 74   1st parameter t
8660: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  o sqlite3_exec()
8670: 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65   while sqlite3_e
8680: 78 65 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67  xec() is running
8690: 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70  ..** <li> The ap
86a0: 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e  plication must n
86b0: 6f 74 20 6d 6f 64 69 66 79 20 74 68 65 20 53 51  ot modify the SQ
86c0: 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74  L statement text
86d0: 20 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20   passed into.** 
86e0: 20 20 20 20 20 74 68 65 20 32 6e 64 20 70 61 72       the 2nd par
86f0: 61 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65  ameter of sqlite
8700: 33 5f 65 78 65 63 28 29 20 77 68 69 6c 65 20 73  3_exec() while s
8710: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73  qlite3_exec() is
8720: 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75   running..** </u
8730: 6c 3e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  l>.*/.SQLITE_API
8740: 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 65   int sqlite3_exe
8750: 63 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 20  c(.  sqlite3*,  
8760: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
8770: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
8780: 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62  /* An open datab
8790: 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  ase */.  const c
87a0: 68 61 72 20 2a 73 71 6c 2c 20 20 20 20 20 20 20  har *sql,       
87b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
87c0: 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65      /* SQL to be
87d0: 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20   evaluated */.  
87e0: 69 6e 74 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28  int (*callback)(
87f0: 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a  void*,int,char**
8800: 2c 63 68 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61  ,char**),  /* Ca
8810: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
8820: 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20 20 20 20  */.  void *,    
8830: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
8840: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
8850: 2f 2a 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20  /* 1st argument 
8860: 74 6f 20 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20  to callback */. 
8870: 20 63 68 61 72 20 2a 2a 65 72 72 6d 73 67 20 20   char **errmsg  
8880: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
8890: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 45              /* E
88a0: 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e  rror msg written
88b0: 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a   here */.);../*.
88c0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73  ** CAPI3REF: Res
88d0: 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59  ult Codes.** KEY
88e0: 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 4f 4b  WORDS: SQLITE_OK
88f0: 20 7b 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65   {error code} {e
8900: 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b  rror codes}.** K
8910: 45 59 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74  EYWORDS: {result
8920: 20 63 6f 64 65 7d 20 7b 72 65 73 75 6c 74 20 63   code} {result c
8930: 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79  odes}.**.** Many
8940: 20 53 51 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e   SQLite function
8950: 73 20 72 65 74 75 72 6e 20 61 6e 20 69 6e 74 65  s return an inte
8960: 67 65 72 20 72 65 73 75 6c 74 20 63 6f 64 65 20  ger result code 
8970: 66 72 6f 6d 20 74 68 65 20 73 65 74 20 73 68 6f  from the set sho
8980: 77 6e 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72  wn.** here in or
8990: 64 65 72 20 74 6f 20 69 6e 64 69 63 61 74 65 73  der to indicates
89a0: 20 73 75 63 63 65 73 73 20 6f 72 20 66 61 69 6c   success or fail
89b0: 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65  ure..**.** New e
89c0: 72 72 6f 72 20 63 6f 64 65 73 20 6d 61 79 20 62  rror codes may b
89d0: 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
89e0: 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
89f0: 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  Lite..**.** See 
8a00: 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f  also: [SQLITE_IO
8a10: 45 52 52 5f 52 45 41 44 20 7c 20 65 78 74 65 6e  ERR_READ | exten
8a20: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
8a30: 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  ],.** [sqlite3_v
8a40: 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28  tab_on_conflict(
8a50: 29 5d 20 5b 53 51 4c 49 54 45 5f 52 4f 4c 4c 42  )] [SQLITE_ROLLB
8a60: 41 43 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64  ACK | result cod
8a70: 65 73 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  es]..*/.#define 
8a80: 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20 20  SQLITE_OK       
8a90: 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63 63 65      0   /* Succe
8aa0: 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a  ssful result */.
8ab0: 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d  /* beginning-of-
8ac0: 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 23  error-codes */.#
8ad0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 52  define SQLITE_ER
8ae0: 52 4f 52 20 20 20 20 20 20 20 20 31 20 20 20 2f  ROR        1   /
8af0: 2a 20 53 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d  * SQL error or m
8b00: 69 73 73 69 6e 67 20 64 61 74 61 62 61 73 65 20  issing database 
8b10: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
8b20: 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20 20 32  E_INTERNAL     2
8b30: 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 6c     /* Internal l
8b40: 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20 53 51  ogic error in SQ
8b50: 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  Lite */.#define 
8b60: 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20 20 20  SQLITE_PERM     
8b70: 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63 65 73      3   /* Acces
8b80: 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e  s permission den
8b90: 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ied */.#define S
8ba0: 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20 20 20  QLITE_ABORT     
8bb0: 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61     4   /* Callba
8bc0: 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71 75 65  ck routine reque
8bd0: 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f  sted an abort */
8be0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
8bf0: 42 55 53 59 20 20 20 20 20 20 20 20 20 35 20 20  BUSY         5  
8c00: 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65   /* The database
8c10: 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20   file is locked 
8c20: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
8c30: 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 36  E_LOCKED       6
8c40: 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e     /* A table in
8c50: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
8c60: 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69   locked */.#defi
8c70: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20  ne SQLITE_NOMEM 
8c80: 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 41 20         7   /* A 
8c90: 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64 20  malloc() failed 
8ca0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
8cb0: 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 38  E_READONLY     8
8cc0: 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f     /* Attempt to
8cd0: 20 77 72 69 74 65 20 61 20 72 65 61 64 6f 6e 6c   write a readonl
8ce0: 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64  y database */.#d
8cf0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54  efine SQLITE_INT
8d00: 45 52 52 55 50 54 20 20 20 20 39 20 20 20 2f 2a  ERRUPT    9   /*
8d10: 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72 6d 69   Operation termi
8d20: 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33  nated by sqlite3
8d30: 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a 23  _interrupt()*/.#
8d40: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
8d50: 45 52 52 20 20 20 20 20 20 20 31 30 20 20 20 2f  ERR       10   /
8d60: 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64  * Some kind of d
8d70: 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63  isk I/O error oc
8d80: 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e  curred */.#defin
8d90: 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54  e SQLITE_CORRUPT
8da0: 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 68 65       11   /* The
8db0: 20 64 61 74 61 62 61 73 65 20 64 69 73 6b 20 69   database disk i
8dc0: 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65  mage is malforme
8dd0: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
8de0: 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20  ITE_NOTFOUND    
8df0: 31 32 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e 20  12   /* Unknown 
8e00: 6f 70 63 6f 64 65 20 69 6e 20 73 71 6c 69 74 65  opcode in sqlite
8e10: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
8e20: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
8e30: 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 31  TE_FULL        1
8e40: 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e  3   /* Insertion
8e50: 20 66 61 69 6c 65 64 20 62 65 63 61 75 73 65 20   failed because 
8e60: 64 61 74 61 62 61 73 65 20 69 73 20 66 75 6c 6c  database is full
8e70: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
8e80: 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20 31  TE_CANTOPEN    1
8e90: 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f  4   /* Unable to
8ea0: 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61   open the databa
8eb0: 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69  se file */.#defi
8ec0: 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43  ne SQLITE_PROTOC
8ed0: 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20 44 61  OL    15   /* Da
8ee0: 74 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74  tabase lock prot
8ef0: 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64  ocol error */.#d
8f00: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50  efine SQLITE_EMP
8f10: 54 59 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a  TY       16   /*
8f20: 20 44 61 74 61 62 61 73 65 20 69 73 20 65 6d 70   Database is emp
8f30: 74 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ty */.#define SQ
8f40: 4c 49 54 45 5f 53 43 48 45 4d 41 20 20 20 20 20  LITE_SCHEMA     
8f50: 20 31 37 20 20 20 2f 2a 20 54 68 65 20 64 61 74   17   /* The dat
8f60: 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61  abase schema cha
8f70: 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nged */.#define 
8f80: 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20 20  SQLITE_TOOBIG   
8f90: 20 20 20 31 38 20 20 20 2f 2a 20 53 74 72 69 6e     18   /* Strin
8fa0: 67 20 6f 72 20 42 4c 4f 42 20 65 78 63 65 65 64  g or BLOB exceed
8fb0: 73 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a  s size limit */.
8fc0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
8fd0: 4f 4e 53 54 52 41 49 4e 54 20 20 31 39 20 20 20  ONSTRAINT  19   
8fe0: 2f 2a 20 41 62 6f 72 74 20 64 75 65 20 74 6f 20  /* Abort due to 
8ff0: 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61  constraint viola
9000: 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20  tion */.#define 
9010: 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48 20  SQLITE_MISMATCH 
9020: 20 20 20 32 30 20 20 20 2f 2a 20 44 61 74 61 20     20   /* Data 
9030: 74 79 70 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f  type mismatch */
9040: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
9050: 4d 49 53 55 53 45 20 20 20 20 20 20 32 31 20 20  MISUSE      21  
9060: 20 2f 2a 20 4c 69 62 72 61 72 79 20 75 73 65 64   /* Library used
9070: 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a   incorrectly */.
9080: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
9090: 4f 4c 46 53 20 20 20 20 20 20 20 32 32 20 20 20  OLFS       22   
90a0: 2f 2a 20 55 73 65 73 20 4f 53 20 66 65 61 74 75  /* Uses OS featu
90b0: 72 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 65  res not supporte
90c0: 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65  d on host */.#de
90d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48  fine SQLITE_AUTH
90e0: 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20          23   /* 
90f0: 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65  Authorization de
9100: 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nied */.#define 
9110: 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20 20  SQLITE_FORMAT   
9120: 20 20 20 32 34 20 20 20 2f 2a 20 41 75 78 69 6c     24   /* Auxil
9130: 69 61 72 79 20 64 61 74 61 62 61 73 65 20 66 6f  iary database fo
9140: 72 6d 61 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64  rmat error */.#d
9150: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e  efine SQLITE_RAN
9160: 47 45 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a  GE       25   /*
9170: 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74   2nd parameter t
9180: 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f  o sqlite3_bind o
9190: 75 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23  ut of range */.#
91a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
91b0: 54 41 44 42 20 20 20 20 20 20 32 36 20 20 20 2f  TADB      26   /
91c0: 2a 20 46 69 6c 65 20 6f 70 65 6e 65 64 20 74 68  * File opened th
91d0: 61 74 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61  at is not a data
91e0: 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65  base file */.#de
91f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 4f 57 20  fine SQLITE_ROW 
9200: 20 20 20 20 20 20 20 20 31 30 30 20 20 2f 2a 20          100  /* 
9210: 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68  sqlite3_step() h
9220: 61 73 20 61 6e 6f 74 68 65 72 20 72 6f 77 20 72  as another row r
9230: 65 61 64 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  eady */.#define 
9240: 53 51 4c 49 54 45 5f 44 4f 4e 45 20 20 20 20 20  SQLITE_DONE     
9250: 20 20 20 31 30 31 20 20 2f 2a 20 73 71 6c 69 74     101  /* sqlit
9260: 65 33 5f 73 74 65 70 28 29 20 68 61 73 20 66 69  e3_step() has fi
9270: 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67  nished executing
9280: 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72   */./* end-of-er
9290: 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a  ror-codes */../*
92a0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 78  .** CAPI3REF: Ex
92b0: 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f  tended Result Co
92c0: 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  des.** KEYWORDS:
92d0: 20 7b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72   {extended error
92e0: 20 63 6f 64 65 7d 20 7b 65 78 74 65 6e 64 65 64   code} {extended
92f0: 20 65 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a   error codes}.**
9300: 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65   KEYWORDS: {exte
9310: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
9320: 7d 20 7b 65 78 74 65 6e 64 65 64 20 72 65 73 75  } {extended resu
9330: 6c 74 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20  lt codes}.**.** 
9340: 49 6e 20 69 74 73 20 64 65 66 61 75 6c 74 20 63  In its default c
9350: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 53 51  onfiguration, SQ
9360: 4c 69 74 65 20 41 50 49 20 72 6f 75 74 69 6e 65  Lite API routine
9370: 73 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20  s return one of 
9380: 32 36 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53  26 integer.** [S
9390: 51 4c 49 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c  QLITE_OK | resul
93a0: 74 20 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65 76  t codes].  Howev
93b0: 65 72 2c 20 65 78 70 65 72 69 65 6e 63 65 20 68  er, experience h
93c0: 61 73 20 73 68 6f 77 6e 20 74 68 61 74 20 6d 61  as shown that ma
93d0: 6e 79 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 72  ny of.** these r
93e0: 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20  esult codes are 
93f0: 74 6f 6f 20 63 6f 61 72 73 65 2d 67 72 61 69 6e  too coarse-grain
9400: 65 64 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f 74  ed.  They do not
9410: 20 70 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d   provide as.** m
9420: 75 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  uch information 
9430: 61 62 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20 61  about problems a
9440: 73 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69  s programmers mi
9450: 67 68 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61 6e  ght like.  In an
9460: 20 65 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 64   effort to.** ad
9470: 64 72 65 73 73 20 74 68 69 73 2c 20 6e 65 77 65  dress this, newe
9480: 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  r versions of SQ
9490: 4c 69 74 65 20 28 76 65 72 73 69 6f 6e 20 33 2e  Lite (version 3.
94a0: 33 2e 38 20 61 6e 64 20 6c 61 74 65 72 29 20 69  3.8 and later) i
94b0: 6e 63 6c 75 64 65 0a 2a 2a 20 73 75 70 70 6f 72  nclude.** suppor
94c0: 74 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  t for additional
94d0: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 74 68   result codes th
94e0: 61 74 20 70 72 6f 76 69 64 65 20 6d 6f 72 65 20  at provide more 
94f0: 64 65 74 61 69 6c 65 64 20 69 6e 66 6f 72 6d 61  detailed informa
9500: 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 65 72  tion.** about er
9510: 72 6f 72 73 2e 20 54 68 65 20 65 78 74 65 6e 64  rors. The extend
9520: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ed result codes 
9530: 61 72 65 20 65 6e 61 62 6c 65 64 20 6f 72 20 64  are enabled or d
9540: 69 73 61 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20  isabled.** on a 
9550: 70 65 72 20 64 61 74 61 62 61 73 65 20 63 6f 6e  per database con
9560: 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 20 75 73  nection basis us
9570: 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  ing the.** [sqli
9580: 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73  te3_extended_res
9590: 75 6c 74 5f 63 6f 64 65 73 28 29 5d 20 41 50 49  ult_codes()] API
95a0: 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20  ..**.** Some of 
95b0: 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 65 78  the available ex
95c0: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
95d0: 64 65 73 20 61 72 65 20 6c 69 73 74 65 64 20 68  des are listed h
95e0: 65 72 65 2e 0a 2a 2a 20 4f 6e 65 20 6d 61 79 20  ere..** One may 
95f0: 65 78 70 65 63 74 20 74 68 65 20 6e 75 6d 62 65  expect the numbe
9600: 72 20 6f 66 20 65 78 74 65 6e 64 65 64 20 72 65  r of extended re
9610: 73 75 6c 74 20 63 6f 64 65 73 20 77 69 6c 6c 20  sult codes will 
9620: 62 65 20 65 78 70 61 6e 64 0a 2a 2a 20 6f 76 65  be expand.** ove
9630: 72 20 74 69 6d 65 2e 20 20 53 6f 66 74 77 61 72  r time.  Softwar
9640: 65 20 74 68 61 74 20 75 73 65 73 20 65 78 74 65  e that uses exte
9650: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
9660: 73 20 73 68 6f 75 6c 64 20 65 78 70 65 63 74 0a  s should expect.
9670: 2a 2a 20 74 6f 20 73 65 65 20 6e 65 77 20 72 65  ** to see new re
9680: 73 75 6c 74 20 63 6f 64 65 73 20 69 6e 20 66 75  sult codes in fu
9690: 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66  ture releases of
96a0: 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54   SQLite..**.** T
96b0: 68 65 20 53 51 4c 49 54 45 5f 4f 4b 20 72 65 73  he SQLITE_OK res
96c0: 75 6c 74 20 63 6f 64 65 20 77 69 6c 6c 20 6e 65  ult code will ne
96d0: 76 65 72 20 62 65 20 65 78 74 65 6e 64 65 64 2e  ver be extended.
96e0: 20 20 49 74 20 77 69 6c 6c 20 61 6c 77 61 79 73    It will always
96f0: 0a 2a 2a 20 62 65 20 65 78 61 63 74 6c 79 20 7a  .** be exactly z
9700: 65 72 6f 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ero..*/.#define 
9710: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41  SQLITE_IOERR_REA
9720: 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28  D              (
9730: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
9740: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
9750: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52  QLITE_IOERR_SHOR
9760: 54 5f 52 45 41 44 20 20 20 20 20 20 20 20 28 53  T_READ        (S
9770: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32  QLITE_IOERR | (2
9780: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
9790: 4c 49 54 45 5f 49 4f 45 52 52 5f 57 52 49 54 45  LITE_IOERR_WRITE
97a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
97b0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c  LITE_IOERR | (3<
97c0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
97d0: 49 54 45 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20  ITE_IOERR_FSYNC 
97e0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
97f0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c  ITE_IOERR | (4<<
9800: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
9810: 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f 46 53 59  TE_IOERR_DIR_FSY
9820: 4e 43 20 20 20 20 20 20 20 20 20 28 53 51 4c 49  NC         (SQLI
9830: 54 45 5f 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38  TE_IOERR | (5<<8
9840: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
9850: 45 5f 49 4f 45 52 52 5f 54 52 55 4e 43 41 54 45  E_IOERR_TRUNCATE
9860: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
9870: 45 5f 49 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29  E_IOERR | (6<<8)
9880: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
9890: 5f 49 4f 45 52 52 5f 46 53 54 41 54 20 20 20 20  _IOERR_FSTAT    
98a0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
98b0: 5f 49 4f 45 52 52 20 7c 20 28 37 3c 3c 38 29 29  _IOERR | (7<<8))
98c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
98d0: 49 4f 45 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20  IOERR_UNLOCK    
98e0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
98f0: 49 4f 45 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a  IOERR | (8<<8)).
9900: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
9910: 4f 45 52 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20  OERR_RDLOCK     
9920: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
9930: 4f 45 52 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23  OERR | (9<<8)).#
9940: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
9950: 45 52 52 5f 44 45 4c 45 54 45 20 20 20 20 20 20  ERR_DELETE      
9960: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
9970: 45 52 52 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23  ERR | (10<<8)).#
9980: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
9990: 45 52 52 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20  ERR_BLOCKED     
99a0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
99b0: 45 52 52 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23  ERR | (11<<8)).#
99c0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
99d0: 45 52 52 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20  ERR_NOMEM       
99e0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
99f0: 45 52 52 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23  ERR | (12<<8)).#
9a00: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
9a10: 45 52 52 5f 41 43 43 45 53 53 20 20 20 20 20 20  ERR_ACCESS      
9a20: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
9a30: 45 52 52 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23  ERR | (13<<8)).#
9a40: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
9a50: 45 52 52 5f 43 48 45 43 4b 52 45 53 45 52 56 45  ERR_CHECKRESERVE
9a60: 44 4c 4f 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f  DLOCK (SQLITE_IO
9a70: 45 52 52 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23  ERR | (14<<8)).#
9a80: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
9a90: 45 52 52 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20  ERR_LOCK        
9aa0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
9ab0: 45 52 52 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23  ERR | (15<<8)).#
9ac0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
9ad0: 45 52 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20  ERR_CLOSE       
9ae0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
9af0: 45 52 52 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23  ERR | (16<<8)).#
9b00: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
9b10: 45 52 52 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20  ERR_DIR_CLOSE   
9b20: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
9b30: 45 52 52 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23  ERR | (17<<8)).#
9b40: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
9b50: 45 52 52 5f 53 48 4d 4f 50 45 4e 20 20 20 20 20  ERR_SHMOPEN     
9b60: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
9b70: 45 52 52 20 7c 20 28 31 38 3c 3c 38 29 29 0a 23  ERR | (18<<8)).#
9b80: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
9b90: 45 52 52 5f 53 48 4d 53 49 5a 45 20 20 20 20 20  ERR_SHMSIZE     
9ba0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
9bb0: 45 52 52 20 7c 20 28 31 39 3c 3c 38 29 29 0a 23  ERR | (19<<8)).#
9bc0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
9bd0: 45 52 52 5f 53 48 4d 4c 4f 43 4b 20 20 20 20 20  ERR_SHMLOCK     
9be0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
9bf0: 45 52 52 20 7c 20 28 32 30 3c 3c 38 29 29 0a 23  ERR | (20<<8)).#
9c00: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
9c10: 45 52 52 5f 53 48 4d 4d 41 50 20 20 20 20 20 20  ERR_SHMMAP      
9c20: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
9c30: 45 52 52 20 7c 20 28 32 31 3c 3c 38 29 29 0a 23  ERR | (21<<8)).#
9c40: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
9c50: 45 52 52 5f 53 45 45 4b 20 20 20 20 20 20 20 20  ERR_SEEK        
9c60: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
9c70: 45 52 52 20 7c 20 28 32 32 3c 3c 38 29 29 0a 23  ERR | (22<<8)).#
9c80: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
9c90: 43 4b 45 44 5f 53 48 41 52 45 44 43 41 43 48 45  CKED_SHAREDCACHE
9ca0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f        (SQLITE_LO
9cb0: 43 4b 45 44 20 7c 20 20 28 31 3c 3c 38 29 29 0a  CKED |  (1<<8)).
9cc0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42  #define SQLITE_B
9cd0: 55 53 59 5f 52 45 43 4f 56 45 52 59 20 20 20 20  USY_RECOVERY    
9ce0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42         (SQLITE_B
9cf0: 55 53 59 20 20 20 7c 20 20 28 31 3c 3c 38 29 29  USY   |  (1<<8))
9d00: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
9d10: 43 41 4e 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44  CANTOPEN_NOTEMPD
9d20: 49 52 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  IR      (SQLITE_
9d30: 43 41 4e 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38  CANTOPEN | (1<<8
9d40: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
9d50: 45 5f 43 4f 52 52 55 50 54 5f 56 54 41 42 20 20  E_CORRUPT_VTAB  
9d60: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
9d70: 45 5f 43 4f 52 52 55 50 54 20 7c 20 28 31 3c 3c  E_CORRUPT | (1<<
9d80: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
9d90: 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 52 45 43 4f  TE_READONLY_RECO
9da0: 56 45 52 59 20 20 20 20 20 20 20 28 53 51 4c 49  VERY       (SQLI
9db0: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 31  TE_READONLY | (1
9dc0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
9dd0: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 43 41  LITE_READONLY_CA
9de0: 4e 54 4c 4f 43 4b 20 20 20 20 20 20 20 28 53 51  NTLOCK       (SQ
9df0: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20  LITE_READONLY | 
9e00: 28 32 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43  (2<<8))../*.** C
9e10: 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46  API3REF: Flags F
9e20: 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65  or File Open Ope
9e30: 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68  rations.**.** Th
9e40: 65 73 65 20 62 69 74 20 76 61 6c 75 65 73 20 61  ese bit values a
9e50: 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  re intended for 
9e60: 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72  use in the.** 3r
9e70: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
9e80: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  he [sqlite3_open
9e90: 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65  _v2()] interface
9ea0: 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34   and.** in the 4
9eb0: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
9ec0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
9ed0: 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 2e 0a  .xOpen] method..
9ee0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
9ef0: 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20  E_OPEN_READONLY 
9f00: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
9f10: 30 31 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  01  /* Ok for sq
9f20: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
9f30: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
9f40: 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
9f50: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
9f60: 30 32 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  02  /* Ok for sq
9f70: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
9f80: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
9f90: 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20 20 20  E_OPEN_CREATE   
9fa0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
9fb0: 30 34 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  04  /* Ok for sq
9fc0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
9fd0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
9fe0: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
9ff0: 4c 4f 53 45 20 20 20 20 30 78 30 30 30 30 30 30  LOSE    0x000000
a000: 30 38 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  08  /* VFS only 
a010: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
a020: 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45  E_OPEN_EXCLUSIVE
a030: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
a040: 31 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  10  /* VFS only 
a050: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
a060: 45 5f 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58 59  E_OPEN_AUTOPROXY
a070: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
a080: 32 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  20  /* VFS only 
a090: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
a0a0: 45 5f 4f 50 45 4e 5f 55 52 49 20 20 20 20 20 20  E_OPEN_URI      
a0b0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
a0c0: 34 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  40  /* Ok for sq
a0d0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
a0e0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
a0f0: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20  E_OPEN_MAIN_DB  
a100: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 31          0x000001
a110: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
a120: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
a130: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20  E_OPEN_TEMP_DB  
a140: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 32          0x000002
a150: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
a160: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
a170: 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54  E_OPEN_TRANSIENT
a180: 5f 44 42 20 20 20 20 20 30 78 30 30 30 30 30 34  _DB     0x000004
a190: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
a1a0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
a1b0: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52  E_OPEN_MAIN_JOUR
a1c0: 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 30 38  NAL     0x000008
a1d0: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
a1e0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
a1f0: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52  E_OPEN_TEMP_JOUR
a200: 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 31 30  NAL     0x000010
a210: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
a220: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
a230: 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41  E_OPEN_SUBJOURNA
a240: 4c 20 20 20 20 20 20 20 30 78 30 30 30 30 32 30  L       0x000020
a250: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
a260: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
a270: 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f  E_OPEN_MASTER_JO
a280: 55 52 4e 41 4c 20 20 20 30 78 30 30 30 30 34 30  URNAL   0x000040
a290: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
a2a0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
a2b0: 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20 20  E_OPEN_NOMUTEX  
a2c0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 38 30          0x000080
a2d0: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  00  /* Ok for sq
a2e0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
a2f0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
a300: 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58  E_OPEN_FULLMUTEX
a310: 20 20 20 20 20 20 20 20 30 78 30 30 30 31 30 30          0x000100
a320: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  00  /* Ok for sq
a330: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
a340: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
a350: 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43  E_OPEN_SHAREDCAC
a360: 48 45 20 20 20 20 20 20 30 78 30 30 30 32 30 30  HE      0x000200
a370: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  00  /* Ok for sq
a380: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
a390: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
a3a0: 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41  E_OPEN_PRIVATECA
a3b0: 43 48 45 20 20 20 20 20 30 78 30 30 30 34 30 30  CHE     0x000400
a3c0: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  00  /* Ok for sq
a3d0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
a3e0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
a3f0: 45 5f 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20 20  E_OPEN_WAL      
a400: 20 20 20 20 20 20 20 20 30 78 30 30 30 38 30 30          0x000800
a410: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
a420: 2a 2f 0a 0a 2f 2a 20 52 65 73 65 72 76 65 64 3a  */../* Reserved:
a430: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
a440: 20 20 20 20 20 20 20 20 20 30 78 30 30 46 30 30           0x00F00
a450: 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  000 */../*.** CA
a460: 50 49 33 52 45 46 3a 20 44 65 76 69 63 65 20 43  PI3REF: Device C
a470: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 0a 2a  haracteristics.*
a480: 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76 69 63 65  *.** The xDevice
a490: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20  Characteristics 
a4a0: 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 73  method of the [s
a4b0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
a4c0: 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74  s].** object ret
a4d0: 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20  urns an integer 
a4e0: 77 68 69 63 68 20 69 73 20 61 20 76 65 63 74 6f  which is a vecto
a4f0: 72 20 6f 66 20 74 68 65 20 74 68 65 73 65 0a 2a  r of the these.*
a500: 2a 20 62 69 74 20 76 61 6c 75 65 73 20 65 78 70  * bit values exp
a510: 72 65 73 73 69 6e 67 20 49 2f 4f 20 63 68 61 72  ressing I/O char
a520: 61 63 74 65 72 69 73 74 69 63 73 20 6f 66 20 74  acteristics of t
a530: 68 65 20 6d 61 73 73 20 73 74 6f 72 61 67 65 0a  he mass storage.
a540: 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 68  ** device that h
a550: 6f 6c 64 73 20 74 68 65 20 66 69 6c 65 20 74 68  olds the file th
a560: 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  at the [sqlite3_
a570: 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72  io_methods].** r
a580: 65 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20  efers to..**.** 
a590: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
a5a0: 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79  _ATOMIC property
a5b0: 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20   means that all 
a5c0: 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79  writes of.** any
a5d0: 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63   size are atomic
a5e0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
a5f0: 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61  CAP_ATOMICnnn va
a600: 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61  lues.** mean tha
a610: 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63  t writes of bloc
a620: 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20  ks that are nnn 
a630: 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e  bytes in size an
a640: 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64  d.** are aligned
a650: 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77   to an address w
a660: 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67  hich is an integ
a670: 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a  er multiple of.*
a680: 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63  * nnn are atomic
a690: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
a6a0: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20  CAP_SAFE_APPEND 
a6b0: 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74  value means.** t
a6c0: 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73  hat when data is
a6d0: 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66   appended to a f
a6e0: 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73  ile, the data is
a6f0: 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72   appended.** fir
a700: 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65  st then the size
a710: 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20   of the file is 
a720: 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20  extended, never 
a730: 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79  the other.** way
a740: 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51   around.  The SQ
a750: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45  LITE_IOCAP_SEQUE
a760: 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d  NTIAL property m
a770: 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66  eans that.** inf
a780: 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74  ormation is writ
a790: 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74  ten to disk in t
a7a0: 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73  he same order as
a7b0: 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72   calls.** to xWr
a7c0: 69 74 65 28 29 2e 0a 2a 2f 0a 23 64 65 66 69 6e  ite()..*/.#defin
a7d0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
a7e0: 54 4f 4d 49 43 20 20 20 20 20 20 20 20 20 20 20  TOMIC           
a7f0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 31        0x00000001
a800: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
a810: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 20  IOCAP_ATOMIC512 
a820: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
a830: 30 30 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20  0000002.#define 
a840: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
a850: 4d 49 43 31 4b 20 20 20 20 20 20 20 20 20 20 20  MIC1K           
a860: 20 20 20 20 30 78 30 30 30 30 30 30 30 34 0a 23      0x00000004.#
a870: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
a880: 43 41 50 5f 41 54 4f 4d 49 43 32 4b 20 20 20 20  CAP_ATOMIC2K    
a890: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
a8a0: 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20 53 51  00008.#define SQ
a8b0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
a8c0: 43 34 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  C4K             
a8d0: 20 20 30 78 30 30 30 30 30 30 31 30 0a 23 64 65    0x00000010.#de
a8e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
a8f0: 50 5f 41 54 4f 4d 49 43 38 4b 20 20 20 20 20 20  P_ATOMIC8K      
a900: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
a910: 30 32 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  020.#define SQLI
a920: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31  TE_IOCAP_ATOMIC1
a930: 36 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  6K              
a940: 30 78 30 30 30 30 30 30 34 30 0a 23 64 65 66 69  0x00000040.#defi
a950: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
a960: 41 54 4f 4d 49 43 33 32 4b 20 20 20 20 20 20 20  ATOMIC32K       
a970: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 38         0x0000008
a980: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
a990: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b  _IOCAP_ATOMIC64K
a9a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
a9b0: 30 30 30 30 30 31 30 30 0a 23 64 65 66 69 6e 65  00000100.#define
a9c0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41   SQLITE_IOCAP_SA
a9d0: 46 45 5f 41 50 50 45 4e 44 20 20 20 20 20 20 20  FE_APPEND       
a9e0: 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30 0a       0x00000200.
a9f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
aa00: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20  OCAP_SEQUENTIAL 
aa10: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
aa20: 30 30 30 34 30 30 0a 23 64 65 66 69 6e 65 20 53  000400.#define S
aa30: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45  QLITE_IOCAP_UNDE
aa40: 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45  LETABLE_WHEN_OPE
aa50: 4e 20 20 30 78 30 30 30 30 30 38 30 30 0a 0a 2f  N  0x00000800../
aa60: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
aa70: 69 6c 65 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65  ile Locking Leve
aa80: 6c 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  ls.**.** SQLite 
aa90: 75 73 65 73 20 6f 6e 65 20 6f 66 20 74 68 65 73  uses one of thes
aaa0: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73  e integer values
aab0: 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a   as the second.*
aac0: 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61  * argument to ca
aad0: 6c 6c 73 20 69 74 20 6d 61 6b 65 73 20 74 6f 20  lls it makes to 
aae0: 74 68 65 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20  the xLock() and 
aaf0: 78 55 6e 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64  xUnlock() method
ab00: 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69  s.** of an [sqli
ab10: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
ab20: 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69  object..*/.#defi
ab30: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e  ne SQLITE_LOCK_N
ab40: 4f 4e 45 20 20 20 20 20 20 20 20 20 20 30 0a 23  ONE          0.#
ab50: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
ab60: 43 4b 5f 53 48 41 52 45 44 20 20 20 20 20 20 20  CK_SHARED       
ab70: 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
ab80: 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 20  E_LOCK_RESERVED 
ab90: 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
aba0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49  QLITE_LOCK_PENDI
abb0: 4e 47 20 20 20 20 20 20 20 33 0a 23 64 65 66 69  NG       3.#defi
abc0: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45  ne SQLITE_LOCK_E
abd0: 58 43 4c 55 53 49 56 45 20 20 20 20 20 34 0a 0a  XCLUSIVE     4..
abe0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
abf0: 53 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20  Synchronization 
ac00: 54 79 70 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a  Type Flags.**.**
ac10: 20 57 68 65 6e 20 53 51 4c 69 74 65 20 69 6e 76   When SQLite inv
ac20: 6f 6b 65 73 20 74 68 65 20 78 53 79 6e 63 28 29  okes the xSync()
ac30: 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a   method of an.**
ac40: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
ac50: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 69 74 20  hods] object it 
ac60: 75 73 65 73 20 61 20 63 6f 6d 62 69 6e 61 74 69  uses a combinati
ac70: 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69  on of.** these i
ac80: 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73  nteger values as
ac90: 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
aca0: 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  ment..**.** When
acb0: 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43   the SQLITE_SYNC
acc0: 5f 44 41 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69  _DATAONLY flag i
acd0: 73 20 75 73 65 64 2c 20 69 74 20 6d 65 61 6e 73  s used, it means
ace0: 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e   that the.** syn
acf0: 63 20 6f 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79  c operation only
ad00: 20 6e 65 65 64 73 20 74 6f 20 66 6c 75 73 68 20   needs to flush 
ad10: 64 61 74 61 20 74 6f 20 6d 61 73 73 20 73 74 6f  data to mass sto
ad20: 72 61 67 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20  rage.  Inode.** 
ad30: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64  information need
ad40: 20 6e 6f 74 20 62 65 20 66 6c 75 73 68 65 64 2e   not be flushed.
ad50: 20 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f   If the lower fo
ad60: 75 72 20 62 69 74 73 20 6f 66 20 74 68 65 20 66  ur bits of the f
ad70: 6c 61 67 0a 2a 2a 20 65 71 75 61 6c 20 53 51 4c  lag.** equal SQL
ad80: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c  ITE_SYNC_NORMAL,
ad90: 20 74 68 61 74 20 6d 65 61 6e 73 20 74 6f 20 75   that means to u
ada0: 73 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28  se normal fsync(
adb0: 29 20 73 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20  ) semantics..** 
adc0: 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75  If the lower fou
add0: 72 20 62 69 74 73 20 65 71 75 61 6c 20 53 51 4c  r bits equal SQL
ade0: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 74  ITE_SYNC_FULL, t
adf0: 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20  hat means.** to 
ae00: 75 73 65 20 4d 61 63 20 4f 53 20 58 20 73 74 79  use Mac OS X sty
ae10: 6c 65 20 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74  le fullsync inst
ae20: 65 61 64 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a  ead of fsync()..
ae30: 2a 2a 0a 2a 2a 20 44 6f 20 6e 6f 74 20 63 6f 6e  **.** Do not con
ae40: 66 75 73 65 20 74 68 65 20 53 51 4c 49 54 45 5f  fuse the SQLITE_
ae50: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20  SYNC_NORMAL and 
ae60: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
ae70: 20 66 6c 61 67 73 0a 2a 2a 20 77 69 74 68 20 74   flags.** with t
ae80: 68 65 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68  he [PRAGMA synch
ae90: 72 6f 6e 6f 75 73 5d 3d 4e 4f 52 4d 41 4c 20 61  ronous]=NORMAL a
aea0: 6e 64 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68  nd [PRAGMA synch
aeb0: 72 6f 6e 6f 75 73 5d 3d 46 55 4c 4c 0a 2a 2a 20  ronous]=FULL.** 
aec0: 73 65 74 74 69 6e 67 73 2e 20 20 54 68 65 20 5b  settings.  The [
aed0: 73 79 6e 63 68 72 6f 6e 6f 75 73 20 70 72 61 67  synchronous prag
aee0: 6d 61 5d 20 64 65 74 65 72 6d 69 6e 65 73 20 77  ma] determines w
aef0: 68 65 6e 20 63 61 6c 6c 73 20 74 6f 20 74 68 65  hen calls to the
af00: 0a 2a 2a 20 78 53 79 6e 63 20 56 46 53 20 6d 65  .** xSync VFS me
af10: 74 68 6f 64 20 6f 63 63 75 72 20 61 6e 64 20 61  thod occur and a
af20: 70 70 6c 69 65 73 20 75 6e 69 66 6f 72 6d 6c 79  pplies uniformly
af30: 20 61 63 72 6f 73 73 20 61 6c 6c 20 70 6c 61 74   across all plat
af40: 66 6f 72 6d 73 2e 0a 2a 2a 20 54 68 65 20 53 51  forms..** The SQ
af50: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
af60: 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43   and SQLITE_SYNC
af70: 5f 46 55 4c 4c 20 66 6c 61 67 73 20 64 65 74 65  _FULL flags dete
af80: 72 6d 69 6e 65 20 68 6f 77 0a 2a 2a 20 65 6e 65  rmine how.** ene
af90: 72 67 65 74 69 63 20 6f 72 20 72 69 67 6f 72 6f  rgetic or rigoro
afa0: 75 73 20 6f 72 20 66 6f 72 63 65 66 75 6c 20 74  us or forceful t
afb0: 68 65 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f  he sync operatio
afc0: 6e 73 20 61 72 65 20 61 6e 64 0a 2a 2a 20 6f 6e  ns are and.** on
afd0: 6c 79 20 6d 61 6b 65 20 61 20 64 69 66 66 65 72  ly make a differ
afe0: 65 6e 63 65 20 6f 6e 20 4d 61 63 20 4f 53 58 20  ence on Mac OSX 
aff0: 66 6f 72 20 74 68 65 20 64 65 66 61 75 6c 74 20  for the default 
b000: 53 51 4c 69 74 65 20 63 6f 64 65 2e 0a 2a 2a 20  SQLite code..** 
b010: 28 54 68 69 72 64 2d 70 61 72 74 79 20 56 46 53  (Third-party VFS
b020: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
b030: 20 6d 69 67 68 74 20 61 6c 73 6f 20 6d 61 6b 65   might also make
b040: 20 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e   the distinction
b050: 0a 2a 2a 20 62 65 74 77 65 65 6e 20 53 51 4c 49  .** between SQLI
b060: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61  TE_SYNC_NORMAL a
b070: 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  nd SQLITE_SYNC_F
b080: 55 4c 4c 2c 20 62 75 74 20 61 6d 6f 6e 67 20 74  ULL, but among t
b090: 68 65 0a 2a 2a 20 6f 70 65 72 61 74 69 6e 67 20  he.** operating 
b0a0: 73 79 73 74 65 6d 73 20 6e 61 74 69 76 65 6c 79  systems natively
b0b0: 20 73 75 70 70 6f 72 74 65 64 20 62 79 20 53 51   supported by SQ
b0c0: 4c 69 74 65 2c 20 6f 6e 6c 79 20 4d 61 63 20 4f  Lite, only Mac O
b0d0: 53 58 0a 2a 2a 20 63 61 72 65 73 20 61 62 6f 75  SX.** cares abou
b0e0: 74 20 74 68 65 20 64 69 66 66 65 72 65 6e 63 65  t the difference
b0f0: 2e 29 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  .).*/.#define SQ
b100: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
b110: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 32 0a          0x00002.
b120: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
b130: 59 4e 43 5f 46 55 4c 4c 20 20 20 20 20 20 20 20  YNC_FULL        
b140: 20 20 30 78 30 30 30 30 33 0a 23 64 65 66 69 6e    0x00003.#defin
b150: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41  e SQLITE_SYNC_DA
b160: 54 41 4f 4e 4c 59 20 20 20 20 20 20 30 78 30 30  TAONLY      0x00
b170: 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  010../*.** CAPI3
b180: 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63  REF: OS Interfac
b190: 65 20 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e 64  e Open File Hand
b1a0: 6c 65 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c  le.**.** An [sql
b1b0: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63  ite3_file] objec
b1c0: 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20  t represents an 
b1d0: 6f 70 65 6e 20 66 69 6c 65 20 69 6e 20 74 68 65  open file in the
b1e0: 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66   .** [sqlite3_vf
b1f0: 73 20 7c 20 4f 53 20 69 6e 74 65 72 66 61 63 65  s | OS interface
b200: 20 6c 61 79 65 72 5d 2e 20 20 49 6e 64 69 76 69   layer].  Indivi
b210: 64 75 61 6c 20 4f 53 20 69 6e 74 65 72 66 61 63  dual OS interfac
b220: 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  e.** implementat
b230: 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e  ions will.** wan
b240: 74 20 74 6f 20 73 75 62 63 6c 61 73 73 20 74 68  t to subclass th
b250: 69 73 20 6f 62 6a 65 63 74 20 62 79 20 61 70 70  is object by app
b260: 65 6e 64 69 6e 67 20 61 64 64 69 74 69 6f 6e 61  ending additiona
b270: 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20  l fields.** for 
b280: 74 68 65 69 72 20 6f 77 6e 20 75 73 65 2e 20 20  their own use.  
b290: 54 68 65 20 70 4d 65 74 68 6f 64 73 20 65 6e 74  The pMethods ent
b2a0: 72 79 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ry is a pointer 
b2b0: 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65  to an.** [sqlite
b2c0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  3_io_methods] ob
b2d0: 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65  ject that define
b2e0: 73 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 70 65  s methods for pe
b2f0: 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20  rforming.** I/O 
b300: 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68  operations on th
b310: 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a  e open file..*/.
b320: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
b330: 71 6c 69 74 65 33 5f 66 69 6c 65 20 73 71 6c 69  qlite3_file sqli
b340: 74 65 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74  te3_file;.struct
b350: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a   sqlite3_file {.
b360: 20 20 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73    const struct s
b370: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
b380: 73 20 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a  s *pMethods;  /*
b390: 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 61 6e 20   Methods for an 
b3a0: 6f 70 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a  open file */.};.
b3b0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
b3c0: 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 46 69   OS Interface Fi
b3d0: 6c 65 20 56 69 72 74 75 61 6c 20 4d 65 74 68 6f  le Virtual Metho
b3e0: 64 73 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20  ds Object.**.** 
b3f0: 45 76 65 72 79 20 66 69 6c 65 20 6f 70 65 6e 65  Every file opene
b400: 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65  d by the [sqlite
b410: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74  3_vfs.xOpen] met
b420: 68 6f 64 20 70 6f 70 75 6c 61 74 65 73 20 61 6e  hod populates an
b430: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
b440: 65 5d 20 6f 62 6a 65 63 74 20 28 6f 72 2c 20 6d  e] object (or, m
b450: 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20  ore commonly, a 
b460: 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65 0a  subclass of the.
b470: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
b480: 5d 20 6f 62 6a 65 63 74 29 20 77 69 74 68 20 61  ] object) with a
b490: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
b4a0: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
b4b0: 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 69 73 20  object..** This 
b4c0: 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74  object defines t
b4d0: 68 65 20 6d 65 74 68 6f 64 73 20 75 73 65 64 20  he methods used 
b4e0: 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f  to perform vario
b4f0: 75 73 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a  us operations.**
b500: 20 61 67 61 69 6e 73 74 20 74 68 65 20 6f 70 65   against the ope
b510: 6e 20 66 69 6c 65 20 72 65 70 72 65 73 65 6e 74  n file represent
b520: 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74  ed by the [sqlit
b530: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 2e  e3_file] object.
b540: 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 5b 73  .**.** If the [s
b550: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
b560: 5d 20 6d 65 74 68 6f 64 20 73 65 74 73 20 74 68  ] method sets th
b570: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70  e sqlite3_file.p
b580: 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 20  Methods element 
b590: 0a 2a 2a 20 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c  .** to a non-NUL
b5a0: 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20  L pointer, then 
b5b0: 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  the sqlite3_io_m
b5c0: 65 74 68 6f 64 73 2e 78 43 6c 6f 73 65 20 6d 65  ethods.xClose me
b5d0: 74 68 6f 64 0a 2a 2a 20 6d 61 79 20 62 65 20 69  thod.** may be i
b5e0: 6e 76 6f 6b 65 64 20 65 76 65 6e 20 69 66 20 74  nvoked even if t
b5f0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  he [sqlite3_vfs.
b600: 78 4f 70 65 6e 5d 20 72 65 70 6f 72 74 65 64 20  xOpen] reported 
b610: 74 68 61 74 20 69 74 20 66 61 69 6c 65 64 2e 20  that it failed. 
b620: 20 54 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79   The.** only way
b630: 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 63 61   to prevent a ca
b640: 6c 6c 20 74 6f 20 78 43 6c 6f 73 65 20 66 6f 6c  ll to xClose fol
b650: 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 65 64 20  lowing a failed 
b660: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70  [sqlite3_vfs.xOp
b670: 65 6e 5d 0a 2a 2a 20 69 73 20 66 6f 72 20 74 68  en].** is for th
b680: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78  e [sqlite3_vfs.x
b690: 4f 70 65 6e 5d 20 74 6f 20 73 65 74 20 74 68 65  Open] to set the
b6a0: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d   sqlite3_file.pM
b6b0: 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 0a 2a  ethods element.*
b6c0: 2a 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  * to NULL..**.**
b6d0: 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d   The flags argum
b6e0: 65 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d 61 79  ent to xSync may
b6f0: 20 62 65 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49   be one of [SQLI
b700: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20  TE_SYNC_NORMAL] 
b710: 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 59  or.** [SQLITE_SY
b720: 4e 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 20 66  NC_FULL].  The f
b730: 69 72 73 74 20 63 68 6f 69 63 65 20 69 73 20 74  irst choice is t
b740: 68 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28  he normal fsync(
b750: 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  )..** The second
b760: 20 63 68 6f 69 63 65 20 69 73 20 61 20 4d 61 63   choice is a Mac
b770: 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c   OS X style full
b780: 73 79 6e 63 2e 20 20 54 68 65 20 5b 53 51 4c 49  sync.  The [SQLI
b790: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59  TE_SYNC_DATAONLY
b7a0: 5d 0a 2a 2a 20 66 6c 61 67 20 6d 61 79 20 62 65  ].** flag may be
b7b0: 20 4f 52 65 64 20 69 6e 20 74 6f 20 69 6e 64 69   ORed in to indi
b7c0: 63 61 74 65 20 74 68 61 74 20 6f 6e 6c 79 20 74  cate that only t
b7d0: 68 65 20 64 61 74 61 20 6f 66 20 74 68 65 20 66  he data of the f
b7e0: 69 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20 69  ile.** and not i
b7f0: 74 73 20 69 6e 6f 64 65 20 6e 65 65 64 73 20 74  ts inode needs t
b800: 6f 20 62 65 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a  o be synced..**.
b810: 2a 2a 20 54 68 65 20 69 6e 74 65 67 65 72 20 76  ** The integer v
b820: 61 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29  alues to xLock()
b830: 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61   and xUnlock() a
b840: 72 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c  re one of.** <ul
b850: 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  >.** <li> [SQLIT
b860: 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a  E_LOCK_NONE],.**
b870: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f   <li> [SQLITE_LO
b880: 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c  CK_SHARED],.** <
b890: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
b8a0: 5f 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c  _RESERVED],.** <
b8b0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
b8c0: 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a  _PENDING], or.**
b8d0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f   <li> [SQLITE_LO
b8e0: 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a  CK_EXCLUSIVE]..*
b8f0: 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b  * </ul>.** xLock
b900: 28 29 20 69 6e 63 72 65 61 73 65 73 20 74 68 65  () increases the
b910: 20 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29   lock. xUnlock()
b920: 20 64 65 63 72 65 61 73 65 73 20 74 68 65 20 6c   decreases the l
b930: 6f 63 6b 2e 0a 2a 2a 20 54 68 65 20 78 43 68 65  ock..** The xChe
b940: 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 28 29  ckReservedLock()
b950: 20 6d 65 74 68 6f 64 20 63 68 65 63 6b 73 20 77   method checks w
b960: 68 65 74 68 65 72 20 61 6e 79 20 64 61 74 61 62  hether any datab
b970: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a  ase connection,.
b980: 2a 2a 20 65 69 74 68 65 72 20 69 6e 20 74 68 69  ** either in thi
b990: 73 20 70 72 6f 63 65 73 73 20 6f 72 20 69 6e 20  s process or in 
b9a0: 73 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f 63 65  some other proce
b9b0: 73 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20 61  ss, is holding a
b9c0: 20 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45   RESERVED,.** PE
b9d0: 4e 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53  NDING, or EXCLUS
b9e0: 49 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20  IVE lock on the 
b9f0: 66 69 6c 65 2e 20 20 49 74 20 72 65 74 75 72 6e  file.  It return
ba00: 73 20 74 72 75 65 0a 2a 2a 20 69 66 20 73 75 63  s true.** if suc
ba10: 68 20 61 20 6c 6f 63 6b 20 65 78 69 73 74 73 20  h a lock exists 
ba20: 61 6e 64 20 66 61 6c 73 65 20 6f 74 68 65 72 77  and false otherw
ba30: 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ise..**.** The x
ba40: 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 65  FileControl() me
ba50: 74 68 6f 64 20 69 73 20 61 20 67 65 6e 65 72 69  thod is a generi
ba60: 63 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74  c interface that
ba70: 20 61 6c 6c 6f 77 73 20 63 75 73 74 6f 6d 0a 2a   allows custom.*
ba80: 2a 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  * VFS implementa
ba90: 74 69 6f 6e 73 20 74 6f 20 64 69 72 65 63 74 6c  tions to directl
baa0: 79 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70 65  y control an ope
bab0: 6e 20 66 69 6c 65 20 75 73 69 6e 67 20 74 68 65  n file using the
bac0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
bad0: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74  e_control()] int
bae0: 65 72 66 61 63 65 2e 20 20 54 68 65 20 73 65 63  erface.  The sec
baf0: 6f 6e 64 20 22 6f 70 22 20 61 72 67 75 6d 65 6e  ond "op" argumen
bb00: 74 20 69 73 20 61 6e 0a 2a 2a 20 69 6e 74 65 67  t is an.** integ
bb10: 65 72 20 6f 70 63 6f 64 65 2e 20 20 54 68 65 20  er opcode.  The 
bb20: 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69  third argument i
bb30: 73 20 61 20 67 65 6e 65 72 69 63 20 70 6f 69 6e  s a generic poin
bb40: 74 65 72 20 69 6e 74 65 6e 64 65 64 20 74 6f 0a  ter intended to.
bb50: 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74  ** point to a st
bb60: 72 75 63 74 75 72 65 20 74 68 61 74 20 6d 61 79  ructure that may
bb70: 20 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e   contain argumen
bb80: 74 73 20 6f 72 20 73 70 61 63 65 20 69 6e 20 77  ts or space in w
bb90: 68 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65  hich to.** write
bba0: 20 72 65 74 75 72 6e 20 76 61 6c 75 65 73 2e 20   return values. 
bbb0: 20 50 6f 74 65 6e 74 69 61 6c 20 75 73 65 73 20   Potential uses 
bbc0: 66 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  for xFileControl
bbd0: 28 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66  () might be.** f
bbe0: 75 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62  unctions to enab
bbf0: 6c 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b  le blocking lock
bc00: 73 20 77 69 74 68 20 74 69 6d 65 6f 75 74 73 2c  s with timeouts,
bc10: 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 0a 2a   to change the.*
bc20: 2a 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74 65  * locking strate
bc30: 67 79 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20  gy (for example 
bc40: 74 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c 65 20  to use dot-file 
bc50: 6c 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69  locks), to inqui
bc60: 72 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65 20  re.** about the 
bc70: 73 74 61 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b  status of a lock
bc80: 2c 20 6f 72 20 74 6f 20 62 72 65 61 6b 20 73 74  , or to break st
bc90: 61 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20  ale locks.  The 
bca0: 53 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72  SQLite.** core r
bcb0: 65 73 65 72 76 65 73 20 61 6c 6c 20 6f 70 63 6f  eserves all opco
bcc0: 64 65 73 20 6c 65 73 73 20 74 68 61 6e 20 31 30  des less than 10
bcd0: 30 20 66 6f 72 20 69 74 73 20 6f 77 6e 20 75 73  0 for its own us
bce0: 65 2e 0a 2a 2a 20 41 20 5b 53 51 4c 49 54 45 5f  e..** A [SQLITE_
bcf0: 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20  FCNTL_LOCKSTATE 
bd00: 7c 20 6c 69 73 74 20 6f 66 20 6f 70 63 6f 64 65  | list of opcode
bd10: 73 5d 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30  s] less than 100
bd20: 20 69 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a   is available..*
bd30: 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74  * Applications t
bd40: 68 61 74 20 64 65 66 69 6e 65 20 61 20 63 75 73  hat define a cus
bd50: 74 6f 6d 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  tom xFileControl
bd60: 20 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64 20 75   method should u
bd70: 73 65 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 67 72  se opcodes.** gr
bd80: 65 61 74 65 72 20 74 68 61 6e 20 31 30 30 20 74  eater than 100 t
bd90: 6f 20 61 76 6f 69 64 20 63 6f 6e 66 6c 69 63 74  o avoid conflict
bda0: 73 2e 20 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e  s.  VFS implemen
bdb0: 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 0a 2a  tations should.*
bdc0: 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  * return [SQLITE
bdd0: 5f 4e 4f 54 46 4f 55 4e 44 5d 20 66 6f 72 20 66  _NOTFOUND] for f
bde0: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f  ile control opco
bdf0: 64 65 73 20 74 68 61 74 20 74 68 65 79 20 64 6f  des that they do
be00: 20 6e 6f 74 0a 2a 2a 20 72 65 63 6f 67 6e 69 7a   not.** recogniz
be10: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65  e..**.** The xSe
be20: 63 74 6f 72 53 69 7a 65 28 29 20 6d 65 74 68 6f  ctorSize() metho
be30: 64 20 72 65 74 75 72 6e 73 20 74 68 65 20 73 65  d returns the se
be40: 63 74 6f 72 20 73 69 7a 65 20 6f 66 20 74 68 65  ctor size of the
be50: 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20  .** device that 
be60: 75 6e 64 65 72 6c 69 65 73 20 74 68 65 20 66 69  underlies the fi
be70: 6c 65 2e 20 20 54 68 65 20 73 65 63 74 6f 72 20  le.  The sector 
be80: 73 69 7a 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d  size is the.** m
be90: 69 6e 69 6d 75 6d 20 77 72 69 74 65 20 74 68 61  inimum write tha
bea0: 74 20 63 61 6e 20 62 65 20 70 65 72 66 6f 72 6d  t can be perform
beb0: 65 64 20 77 69 74 68 6f 75 74 20 64 69 73 74 75  ed without distu
bec0: 72 62 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62  rbing.** other b
bed0: 79 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65  ytes in the file
bee0: 2e 20 20 54 68 65 20 78 44 65 76 69 63 65 43 68  .  The xDeviceCh
bef0: 61 72 61 63 74 65 72 69 73 74 69 63 73 28 29 0a  aracteristics().
bf00: 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e  ** method return
bf10: 73 20 61 20 62 69 74 20 76 65 63 74 6f 72 20 64  s a bit vector d
bf20: 65 73 63 72 69 62 69 6e 67 20 62 65 68 61 76 69  escribing behavi
bf30: 6f 72 73 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e  ors of the.** un
bf40: 64 65 72 6c 79 69 6e 67 20 64 65 76 69 63 65 3a  derlying device:
bf50: 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
bf60: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
bf70: 50 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69  P_ATOMIC].** <li
bf80: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
bf90: 41 54 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c  ATOMIC512].** <l
bfa0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
bfb0: 5f 41 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c  _ATOMIC1K].** <l
bfc0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
bfd0: 5f 41 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c  _ATOMIC2K].** <l
bfe0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
bff0: 5f 41 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c  _ATOMIC4K].** <l
c000: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
c010: 5f 41 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c  _ATOMIC8K].** <l
c020: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
c030: 5f 41 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c  _ATOMIC16K].** <
c040: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
c050: 50 5f 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20  P_ATOMIC32K].** 
c060: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
c070: 41 50 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a  AP_ATOMIC64K].**
c080: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
c090: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 5d  CAP_SAFE_APPEND]
c0a0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
c0b0: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41  _IOCAP_SEQUENTIA
c0c0: 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  L].** </ul>.**.*
c0d0: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43  * The SQLITE_IOC
c0e0: 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72  AP_ATOMIC proper
c0f0: 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c  ty means that al
c100: 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61  l writes of.** a
c110: 6e 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d  ny size are atom
c120: 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  ic.  The SQLITE_
c130: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20  IOCAP_ATOMICnnn 
c140: 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74  values.** mean t
c150: 68 61 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c  hat writes of bl
c160: 6f 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e  ocks that are nn
c170: 6e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20  n bytes in size 
c180: 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e  and.** are align
c190: 65 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73  ed to an address
c1a0: 20 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74   which is an int
c1b0: 65 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66  eger multiple of
c1c0: 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d  .** nnn are atom
c1d0: 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  ic.  The SQLITE_
c1e0: 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e  IOCAP_SAFE_APPEN
c1f0: 44 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a  D value means.**
c200: 20 74 68 61 74 20 77 68 65 6e 20 64 61 74 61 20   that when data 
c210: 69 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61  is appended to a
c220: 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20   file, the data 
c230: 69 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66  is appended.** f
c240: 69 72 73 74 20 74 68 65 6e 20 74 68 65 20 73 69  irst then the si
c250: 7a 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69  ze of the file i
c260: 73 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65  s extended, neve
c270: 72 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77  r the other.** w
c280: 61 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20  ay around.  The 
c290: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51  SQLITE_IOCAP_SEQ
c2a0: 55 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79  UENTIAL property
c2b0: 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69   means that.** i
c2c0: 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72  nformation is wr
c2d0: 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e  itten to disk in
c2e0: 20 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20   the same order 
c2f0: 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78  as calls.** to x
c300: 57 72 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49  Write()..**.** I
c310: 66 20 78 52 65 61 64 28 29 20 72 65 74 75 72 6e  f xRead() return
c320: 73 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53  s SQLITE_IOERR_S
c330: 48 4f 52 54 5f 52 45 41 44 20 69 74 20 6d 75 73  HORT_READ it mus
c340: 74 20 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69  t also fill.** i
c350: 6e 20 74 68 65 20 75 6e 72 65 61 64 20 70 6f 72  n the unread por
c360: 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 62 75 66  tions of the buf
c370: 66 65 72 20 77 69 74 68 20 7a 65 72 6f 73 2e 20  fer with zeros. 
c380: 20 41 20 56 46 53 20 74 68 61 74 0a 2a 2a 20 66   A VFS that.** f
c390: 61 69 6c 73 20 74 6f 20 7a 65 72 6f 2d 66 69 6c  ails to zero-fil
c3a0: 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20 6d 69  l short reads mi
c3b0: 67 68 74 20 73 65 65 6d 20 74 6f 20 77 6f 72 6b  ght seem to work
c3c0: 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66  .  However,.** f
c3d0: 61 69 6c 75 72 65 20 74 6f 20 7a 65 72 6f 2d 66  ailure to zero-f
c3e0: 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20  ill short reads 
c3f0: 77 69 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79 20  will eventually 
c400: 6c 65 61 64 20 74 6f 0a 2a 2a 20 64 61 74 61 62  lead to.** datab
c410: 61 73 65 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a  ase corruption..
c420: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
c430: 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74  t sqlite3_io_met
c440: 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f  hods sqlite3_io_
c450: 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20  methods;.struct 
c460: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
c470: 64 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73  ds {.  int iVers
c480: 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c  ion;.  int (*xCl
c490: 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ose)(sqlite3_fil
c4a0: 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65  e*);.  int (*xRe
c4b0: 61 64 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ad)(sqlite3_file
c4c0: 2a 2c 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41  *, void*, int iA
c4d0: 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  mt, sqlite3_int6
c4e0: 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20  4 iOfst);.  int 
c4f0: 28 2a 78 57 72 69 74 65 29 28 73 71 6c 69 74 65  (*xWrite)(sqlite
c500: 33 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76  3_file*, const v
c510: 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20  oid*, int iAmt, 
c520: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f  sqlite3_int64 iO
c530: 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54  fst);.  int (*xT
c540: 72 75 6e 63 61 74 65 29 28 73 71 6c 69 74 65 33  runcate)(sqlite3
c550: 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f  _file*, sqlite3_
c560: 69 6e 74 36 34 20 73 69 7a 65 29 3b 0a 20 20 69  int64 size);.  i
c570: 6e 74 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69  nt (*xSync)(sqli
c580: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66  te3_file*, int f
c590: 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78  lags);.  int (*x
c5a0: 46 69 6c 65 53 69 7a 65 29 28 73 71 6c 69 74 65  FileSize)(sqlite
c5b0: 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33  3_file*, sqlite3
c5c0: 5f 69 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a  _int64 *pSize);.
c5d0: 20 20 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73    int (*xLock)(s
c5e0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
c5f0: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c  t);.  int (*xUnl
c600: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ock)(sqlite3_fil
c610: 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20  e*, int);.  int 
c620: 28 2a 78 43 68 65 63 6b 52 65 73 65 72 76 65 64  (*xCheckReserved
c630: 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69  Lock)(sqlite3_fi
c640: 6c 65 2a 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75  le*, int *pResOu
c650: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c  t);.  int (*xFil
c660: 65 43 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65  eControl)(sqlite
c670: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c  3_file*, int op,
c680: 20 76 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20 20   void *pArg);.  
c690: 69 6e 74 20 28 2a 78 53 65 63 74 6f 72 53 69 7a  int (*xSectorSiz
c6a0: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
c6b0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 76 69  );.  int (*xDevi
c6c0: 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63  ceCharacteristic
c6d0: 73 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  s)(sqlite3_file*
c6e0: 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20  );.  /* Methods 
c6f0: 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20  above are valid 
c700: 66 6f 72 20 76 65 72 73 69 6f 6e 20 31 20 2a 2f  for version 1 */
c710: 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 4d 61 70  .  int (*xShmMap
c720: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
c730: 20 69 6e 74 20 69 50 67 2c 20 69 6e 74 20 70 67   int iPg, int pg
c740: 73 7a 2c 20 69 6e 74 2c 20 76 6f 69 64 20 76 6f  sz, int, void vo
c750: 6c 61 74 69 6c 65 2a 2a 29 3b 0a 20 20 69 6e 74  latile**);.  int
c760: 20 28 2a 78 53 68 6d 4c 6f 63 6b 29 28 73 71 6c   (*xShmLock)(sql
c770: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20  ite3_file*, int 
c780: 6f 66 66 73 65 74 2c 20 69 6e 74 20 6e 2c 20 69  offset, int n, i
c790: 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 76 6f 69  nt flags);.  voi
c7a0: 64 20 28 2a 78 53 68 6d 42 61 72 72 69 65 72 29  d (*xShmBarrier)
c7b0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b  (sqlite3_file*);
c7c0: 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 55 6e 6d  .  int (*xShmUnm
c7d0: 61 70 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ap)(sqlite3_file
c7e0: 2a 2c 20 69 6e 74 20 64 65 6c 65 74 65 46 6c 61  *, int deleteFla
c7f0: 67 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73  g);.  /* Methods
c800: 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64   above are valid
c810: 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 32 20 2a   for version 2 *
c820: 2f 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61  /.  /* Additiona
c830: 6c 20 6d 65 74 68 6f 64 73 20 6d 61 79 20 62 65  l methods may be
c840: 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
c850: 20 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a   releases */.};.
c860: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
c870: 20 53 74 61 6e 64 61 72 64 20 46 69 6c 65 20 43   Standard File C
c880: 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a  ontrol Opcodes.*
c890: 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67  *.** These integ
c8a0: 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65  er constants are
c8b0: 20 6f 70 63 6f 64 65 73 20 66 6f 72 20 74 68 65   opcodes for the
c8c0: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65   xFileControl me
c8d0: 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  thod.** of the [
c8e0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
c8f0: 64 73 5d 20 6f 62 6a 65 63 74 20 61 6e 64 20 66  ds] object and f
c900: 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  or the [sqlite3_
c910: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a  file_control()].
c920: 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  ** interface..**
c930: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
c940: 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d  FCNTL_LOCKSTATE]
c950: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
c960: 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20 20  for debugging.  
c970: 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63  This.** opcode c
c980: 61 75 73 65 73 20 74 68 65 20 78 46 69 6c 65 43  auses the xFileC
c990: 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f  ontrol method to
c9a0: 20 77 72 69 74 65 20 74 68 65 20 63 75 72 72 65   write the curre
c9b0: 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a 20 74  nt state of.** t
c9c0: 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66 20  he lock (one of 
c9d0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e  [SQLITE_LOCK_NON
c9e0: 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  E], [SQLITE_LOCK
c9f0: 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51  _SHARED],.** [SQ
ca00: 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56  LITE_LOCK_RESERV
ca10: 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  ED], [SQLITE_LOC
ca20: 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b  K_PENDING], or [
ca30: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c  SQLITE_LOCK_EXCL
ca40: 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20  USIVE]).** into 
ca50: 61 6e 20 69 6e 74 65 67 65 72 20 74 68 61 74 20  an integer that 
ca60: 74 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e  the pArg argumen
ca70: 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54 68 69  t points to. Thi
ca80: 73 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20  s capability.** 
ca90: 69 73 20 75 73 65 64 20 64 75 72 69 6e 67 20 74  is used during t
caa0: 65 73 74 69 6e 67 20 61 6e 64 20 6f 6e 6c 79 20  esting and only 
cab0: 6e 65 65 64 73 20 74 6f 20 62 65 20 73 75 70 70  needs to be supp
cac0: 6f 72 74 65 64 20 77 68 65 6e 20 53 51 4c 49 54  orted when SQLIT
cad0: 45 5f 54 45 53 54 0a 2a 2a 20 69 73 20 64 65 66  E_TEST.** is def
cae0: 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ined..**.** The 
caf0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49  [SQLITE_FCNTL_SI
cb00: 5a 45 5f 48 49 4e 54 5d 20 6f 70 63 6f 64 65 20  ZE_HINT] opcode 
cb10: 69 73 20 75 73 65 64 20 62 79 20 53 51 4c 69 74  is used by SQLit
cb20: 65 20 74 6f 20 67 69 76 65 20 74 68 65 20 56 46  e to give the VF
cb30: 53 0a 2a 2a 20 6c 61 79 65 72 20 61 20 68 69 6e  S.** layer a hin
cb40: 74 20 6f 66 20 68 6f 77 20 6c 61 72 67 65 20 74  t of how large t
cb50: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
cb60: 20 77 69 6c 6c 20 67 72 6f 77 20 74 6f 20 62 65   will grow to be
cb70: 20 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20 63   during the.** c
cb80: 75 72 72 65 6e 74 20 74 72 61 6e 73 61 63 74 69  urrent transacti
cb90: 6f 6e 2e 20 20 54 68 69 73 20 68 69 6e 74 20 69  on.  This hint i
cba0: 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 64  s not guaranteed
cbb0: 20 74 6f 20 62 65 20 61 63 63 75 72 61 74 65 20   to be accurate 
cbc0: 62 75 74 20 69 74 0a 2a 2a 20 69 73 20 6f 66 74  but it.** is oft
cbd0: 65 6e 20 63 6c 6f 73 65 2e 20 20 54 68 65 20 75  en close.  The u
cbe0: 6e 64 65 72 6c 79 69 6e 67 20 56 46 53 20 6d 69  nderlying VFS mi
cbf0: 67 68 74 20 63 68 6f 6f 73 65 20 74 6f 20 70 72  ght choose to pr
cc00: 65 61 6c 6c 6f 63 61 74 65 20 64 61 74 61 62 61  eallocate databa
cc10: 73 65 0a 2a 2a 20 66 69 6c 65 20 73 70 61 63 65  se.** file space
cc20: 20 62 61 73 65 64 20 6f 6e 20 74 68 69 73 20 68   based on this h
cc30: 69 6e 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  int in order to 
cc40: 68 65 6c 70 20 77 72 69 74 65 73 20 74 6f 20 74  help writes to t
cc50: 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66  he database.** f
cc60: 69 6c 65 20 72 75 6e 20 66 61 73 74 65 72 2e 0a  ile run faster..
cc70: 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  **.** The [SQLIT
cc80: 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49  E_FCNTL_CHUNK_SI
cc90: 5a 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  ZE] opcode is us
cca0: 65 64 20 74 6f 20 72 65 71 75 65 73 74 20 74 68  ed to request th
ccb0: 61 74 20 74 68 65 20 56 46 53 0a 2a 2a 20 65 78  at the VFS.** ex
ccc0: 74 65 6e 64 73 20 61 6e 64 20 74 72 75 6e 63 61  tends and trunca
ccd0: 74 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65  tes the database
cce0: 20 66 69 6c 65 20 69 6e 20 63 68 75 6e 6b 73 20   file in chunks 
ccf0: 6f 66 20 61 20 73 69 7a 65 20 73 70 65 63 69 66  of a size specif
cd00: 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 75 73  ied.** by the us
cd10: 65 72 2e 20 54 68 65 20 66 6f 75 72 74 68 20 61  er. The fourth a
cd20: 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69  rgument to [sqli
cd30: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
cd40: 28 29 5d 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 70  ()] should .** p
cd50: 6f 69 6e 74 20 74 6f 20 61 6e 20 69 6e 74 65 67  oint to an integ
cd60: 65 72 20 28 74 79 70 65 20 69 6e 74 29 20 63 6f  er (type int) co
cd70: 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e 65 77  ntaining the new
cd80: 20 63 68 75 6e 6b 2d 73 69 7a 65 20 74 6f 20 75   chunk-size to u
cd90: 73 65 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6e 6f  se.** for the no
cda0: 6d 69 6e 61 74 65 64 20 64 61 74 61 62 61 73 65  minated database
cdb0: 2e 20 41 6c 6c 6f 63 61 74 69 6e 67 20 64 61 74  . Allocating dat
cdc0: 61 62 61 73 65 20 66 69 6c 65 20 73 70 61 63 65  abase file space
cdd0: 20 69 6e 20 6c 61 72 67 65 0a 2a 2a 20 63 68 75   in large.** chu
cde0: 6e 6b 73 20 28 73 61 79 20 31 4d 42 20 61 74 20  nks (say 1MB at 
cdf0: 61 20 74 69 6d 65 29 2c 20 6d 61 79 20 72 65 64  a time), may red
ce00: 75 63 65 20 66 69 6c 65 2d 73 79 73 74 65 6d 20  uce file-system 
ce10: 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20 61 6e  fragmentation an
ce20: 64 0a 2a 2a 20 69 6d 70 72 6f 76 65 20 70 65 72  d.** improve per
ce30: 66 6f 72 6d 61 6e 63 65 20 6f 6e 20 73 6f 6d 65  formance on some
ce40: 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20   systems..**.** 
ce50: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
ce60: 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 20  L_FILE_POINTER] 
ce70: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74  opcode is used t
ce80: 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f 69 6e 74  o obtain a point
ce90: 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71  er.** to the [sq
cea0: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
ceb0: 63 74 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ct associated wi
cec0: 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  th a particular 
ced0: 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
cee0: 65 63 74 69 6f 6e 2e 20 20 53 65 65 20 74 68 65  ection.  See the
cef0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
cf00: 6f 6e 74 72 6f 6c 28 29 5d 20 64 6f 63 75 6d 65  ontrol()] docume
cf10: 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 61  ntation for.** a
cf20: 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
cf30: 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  ation..**.** ^(T
cf40: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
cf50: 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 5d 20 6f  _SYNC_OMITTED] o
cf60: 70 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61 74  pcode is generat
cf70: 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79  ed internally by
cf80: 0a 2a 2a 20 53 51 4c 69 74 65 20 61 6e 64 20 73  .** SQLite and s
cf90: 65 6e 74 20 74 6f 20 61 6c 6c 20 56 46 53 65 73  ent to all VFSes
cfa0: 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 61 20 63   in place of a c
cfb0: 61 6c 6c 20 74 6f 20 74 68 65 20 78 53 79 6e 63  all to the xSync
cfc0: 20 6d 65 74 68 6f 64 0a 2a 2a 20 77 68 65 6e 20   method.** when 
cfd0: 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
cfe0: 6e 65 63 74 69 6f 6e 20 68 61 73 20 5b 50 52 41  nection has [PRA
cff0: 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d  GMA synchronous]
d000: 20 73 65 74 20 74 6f 20 4f 46 46 2e 29 5e 0a 2a   set to OFF.)^.*
d010: 2a 20 53 6f 6d 65 20 73 70 65 63 69 61 6c 69 7a  * Some specializ
d020: 65 64 20 56 46 53 65 73 20 6e 65 65 64 20 74 68  ed VFSes need th
d030: 69 73 20 73 69 67 6e 61 6c 20 69 6e 20 6f 72 64  is signal in ord
d040: 65 72 20 74 6f 20 6f 70 65 72 61 74 65 20 63 6f  er to operate co
d050: 72 72 65 63 74 6c 79 0a 2a 2a 20 77 68 65 6e 20  rrectly.** when 
d060: 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e  [PRAGMA synchron
d070: 6f 75 73 20 7c 20 50 52 41 47 4d 41 20 73 79 6e  ous | PRAGMA syn
d080: 63 68 72 6f 6e 6f 75 73 3d 4f 46 46 5d 20 69 73  chronous=OFF] is
d090: 20 73 65 74 2c 20 62 75 74 20 6d 6f 73 74 20 0a   set, but most .
d0a0: 2a 2a 20 56 46 53 65 73 20 64 6f 20 6e 6f 74 20  ** VFSes do not 
d0b0: 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e 61 6c  need this signal
d0c0: 20 61 6e 64 20 73 68 6f 75 6c 64 20 73 69 6c 65   and should sile
d0d0: 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 68 69 73  ntly ignore this
d0e0: 20 6f 70 63 6f 64 65 2e 0a 2a 2a 20 41 70 70 6c   opcode..** Appl
d0f0: 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20  ications should 
d100: 6e 6f 74 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65  not call [sqlite
d110: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
d120: 5d 20 77 69 74 68 20 74 68 69 73 0a 2a 2a 20 6f  ] with this.** o
d130: 70 63 6f 64 65 20 61 73 20 64 6f 69 6e 67 20 73  pcode as doing s
d140: 6f 20 6d 61 79 20 64 69 73 72 75 70 74 20 74 68  o may disrupt th
d150: 65 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20 74  e operation of t
d160: 68 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20 56  he specialized V
d170: 46 53 65 73 0a 2a 2a 20 74 68 61 74 20 64 6f 20  FSes.** that do 
d180: 72 65 71 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a  require it.  .**
d190: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
d1a0: 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f  _FCNTL_WIN32_AV_
d1b0: 52 45 54 52 59 5d 20 6f 70 63 6f 64 65 20 69 73  RETRY] opcode is
d1c0: 20 75 73 65 64 20 74 6f 20 63 6f 6e 66 69 67 75   used to configu
d1d0: 72 65 20 61 75 74 6f 6d 61 74 69 63 0a 2a 2a 20  re automatic.** 
d1e0: 72 65 74 72 79 20 63 6f 75 6e 74 73 20 61 6e 64  retry counts and
d1f0: 20 69 6e 74 65 72 76 61 6c 73 20 66 6f 72 20 63   intervals for c
d200: 65 72 74 61 69 6e 20 64 69 73 6b 20 49 2f 4f 20  ertain disk I/O 
d210: 6f 70 65 72 61 74 69 6f 6e 73 20 66 6f 72 20 74  operations for t
d220: 68 65 0a 2a 2a 20 77 69 6e 64 6f 77 73 20 5b 56  he.** windows [V
d230: 46 53 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  FS] in order to 
d240: 77 6f 72 6b 20 74 6f 20 70 72 6f 76 69 64 65 20  work to provide 
d250: 72 6f 62 75 73 74 6e 65 73 73 20 61 67 61 69 6e  robustness again
d260: 73 74 0a 2a 2a 20 61 6e 74 69 2d 76 69 72 75 73  st.** anti-virus
d270: 20 70 72 6f 67 72 61 6d 73 2e 20 20 42 79 20 64   programs.  By d
d280: 65 66 61 75 6c 74 2c 20 74 68 65 20 77 69 6e 64  efault, the wind
d290: 6f 77 73 20 56 46 53 20 77 69 6c 6c 20 72 65 74  ows VFS will ret
d2a0: 72 79 20 66 69 6c 65 20 72 65 61 64 2c 0a 2a 2a  ry file read,.**
d2b0: 20 66 69 6c 65 20 77 72 69 74 65 2c 20 61 6e 64   file write, and
d2c0: 20 66 69 6c 65 20 64 65 6c 65 74 65 20 6f 70 65   file delete ope
d2d0: 72 74 69 6f 6e 73 20 75 70 20 74 6f 20 31 30 20  rtions up to 10 
d2e0: 74 69 6d 65 73 2c 20 77 69 74 68 20 61 20 64 65  times, with a de
d2f0: 6c 61 79 0a 2a 2a 20 6f 66 20 32 35 20 6d 69 6c  lay.** of 25 mil
d300: 6c 69 73 65 63 6f 6e 64 73 20 62 65 66 6f 72 65  liseconds before
d310: 20 74 68 65 20 66 69 72 73 74 20 72 65 74 72 79   the first retry
d320: 20 61 6e 64 20 77 69 74 68 20 74 68 65 20 64 65   and with the de
d330: 6c 61 79 20 69 6e 63 72 65 61 73 69 6e 67 0a 2a  lay increasing.*
d340: 2a 20 62 79 20 61 6e 20 61 64 64 69 74 69 6f 6e  * by an addition
d350: 61 6c 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e  al 25 millisecon
d360: 64 73 20 77 69 74 68 20 65 61 63 68 20 73 75 62  ds with each sub
d370: 73 65 71 75 65 6e 74 20 72 65 74 72 79 2e 20 20  sequent retry.  
d380: 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 61  This.** opcode a
d390: 6c 6c 6f 77 73 20 74 68 6f 73 65 20 74 6f 20 76  llows those to v
d3a0: 61 6c 75 65 73 20 28 31 30 20 72 65 74 72 69 65  alues (10 retrie
d3b0: 73 20 61 6e 64 20 32 35 20 6d 69 6c 6c 69 73 65  s and 25 millise
d3c0: 63 6f 6e 64 73 20 6f 66 20 64 65 6c 61 79 29 0a  conds of delay).
d3d0: 2a 2a 20 74 6f 20 62 65 20 61 64 6a 75 73 74 65  ** to be adjuste
d3e0: 64 2e 20 20 54 68 65 20 76 61 6c 75 65 73 20 61  d.  The values a
d3f0: 72 65 20 63 68 61 6e 67 65 64 20 66 6f 72 20 61  re changed for a
d400: 6c 6c 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ll database conn
d410: 65 63 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 69  ections.** withi
d420: 6e 20 74 68 65 20 73 61 6d 65 20 70 72 6f 63 65  n the same proce
d430: 73 73 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e  ss.  The argumen
d440: 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  t is a pointer t
d450: 6f 20 61 6e 20 61 72 72 61 79 20 6f 66 20 74 77  o an array of tw
d460: 6f 0a 2a 2a 20 69 6e 74 65 67 65 72 73 20 77 68  o.** integers wh
d470: 65 72 65 20 74 68 65 20 66 69 72 73 74 20 69 6e  ere the first in
d480: 74 65 67 65 72 20 69 20 74 68 65 20 6e 65 77 20  teger i the new 
d490: 72 65 74 72 79 20 63 6f 75 6e 74 20 61 6e 64 20  retry count and 
d4a0: 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 69 6e  the second.** in
d4b0: 74 65 67 65 72 20 69 73 20 74 68 65 20 64 65 6c  teger is the del
d4c0: 61 79 2e 20 20 49 66 20 65 69 74 68 65 72 20 69  ay.  If either i
d4d0: 6e 74 65 67 65 72 20 69 73 20 6e 65 67 61 74 69  nteger is negati
d4e0: 76 65 2c 20 74 68 65 6e 20 74 68 65 20 73 65 74  ve, then the set
d4f0: 74 69 6e 67 0a 2a 2a 20 69 73 20 6e 6f 74 20 63  ting.** is not c
d500: 68 61 6e 67 65 64 20 62 75 74 20 69 6e 73 74 65  hanged but inste
d510: 61 64 20 74 68 65 20 70 72 69 6f 72 20 76 61 6c  ad the prior val
d520: 75 65 20 6f 66 20 74 68 61 74 20 73 65 74 74 69  ue of that setti
d530: 6e 67 20 69 73 20 77 72 69 74 74 65 6e 0a 2a 2a  ng is written.**
d540: 20 69 6e 74 6f 20 74 68 65 20 61 72 72 61 79 20   into the array 
d550: 65 6e 74 72 79 2c 20 61 6c 6c 6f 77 69 6e 67 20  entry, allowing 
d560: 74 68 65 20 63 75 72 72 65 6e 74 20 72 65 74 72  the current retr
d570: 79 20 73 65 74 74 69 6e 67 73 20 74 6f 20 62 65  y settings to be
d580: 0a 2a 2a 20 69 6e 74 65 72 72 6f 67 61 74 65 64  .** interrogated
d590: 2e 20 20 54 68 65 20 7a 44 62 4e 61 6d 65 20 70  .  The zDbName p
d5a0: 61 72 61 6d 65 74 65 72 20 69 73 20 69 67 6e 6f  arameter is igno
d5b0: 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  red..**.** ^The 
d5c0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45  [SQLITE_FCNTL_PE
d5d0: 52 53 49 53 54 5f 57 41 4c 5d 20 6f 70 63 6f 64  RSIST_WAL] opcod
d5e0: 65 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 74  e is used to set
d5f0: 20 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a   or query the.**
d600: 20 70 65 72 73 69 73 74 65 6e 74 20 5b 57 41 4c   persistent [WAL
d610: 20 7c 20 57 72 69 74 65 20 41 48 65 61 64 20 4c   | Write AHead L
d620: 6f 67 5d 20 73 65 74 74 69 6e 67 2e 20 20 42 79  og] setting.  By
d630: 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20 61 75   default, the au
d640: 78 69 6c 69 61 72 79 0a 2a 2a 20 77 72 69 74 65  xiliary.** write
d650: 20 61 68 65 61 64 20 6c 6f 67 20 61 6e 64 20 73   ahead log and s
d660: 68 61 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c  hared memory fil
d670: 65 73 20 75 73 65 64 20 66 6f 72 20 74 72 61 6e  es used for tran
d680: 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 0a  saction control.
d690: 2a 2a 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63  ** are automatic
d6a0: 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 77 68 65  ally deleted whe
d6b0: 6e 20 74 68 65 20 6c 61 74 65 73 74 20 63 6f 6e  n the latest con
d6c0: 6e 65 63 74 69 6f 6e 20 74 6f 20 74 68 65 20 64  nection to the d
d6d0: 61 74 61 62 61 73 65 0a 2a 2a 20 63 6c 6f 73 65  atabase.** close
d6e0: 73 2e 20 20 53 65 74 74 69 6e 67 20 70 65 72 73  s.  Setting pers
d6f0: 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20  istent WAL mode 
d700: 63 61 75 73 65 73 20 74 68 6f 73 65 20 66 69 6c  causes those fil
d710: 65 73 20 74 6f 20 70 65 72 73 69 73 74 20 61 66  es to persist af
d720: 74 65 72 0a 2a 2a 20 63 6c 6f 73 65 2e 20 20 50  ter.** close.  P
d730: 65 72 73 69 73 74 69 6e 67 20 74 68 65 20 66 69  ersisting the fi
d740: 6c 65 73 20 69 73 20 75 73 65 66 75 6c 20 77 68  les is useful wh
d750: 65 6e 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73  en other process
d760: 65 73 20 74 68 61 74 20 64 6f 20 6e 6f 74 0a 2a  es that do not.*
d770: 2a 20 68 61 76 65 20 77 72 69 74 65 20 70 65 72  * have write per
d780: 6d 69 73 73 69 6f 6e 20 6f 6e 20 74 68 65 20 64  mission on the d
d790: 69 72 65 63 74 6f 72 79 20 63 6f 6e 74 61 69 6e  irectory contain
d7a0: 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65  ing the database
d7b0: 20 66 69 6c 65 20 77 61 6e 74 0a 2a 2a 20 74 6f   file want.** to
d7c0: 20 72 65 61 64 20 74 68 65 20 64 61 74 61 62 61   read the databa
d7d0: 73 65 20 66 69 6c 65 2c 20 61 73 20 74 68 65 20  se file, as the 
d7e0: 57 41 4c 20 61 6e 64 20 73 68 61 72 65 64 20 6d  WAL and shared m
d7f0: 65 6d 6f 72 79 20 66 69 6c 65 73 20 6d 75 73 74  emory files must
d800: 20 65 78 69 73 74 0a 2a 2a 20 69 6e 20 6f 72 64   exist.** in ord
d810: 65 72 20 66 6f 72 20 74 68 65 20 64 61 74 61 62  er for the datab
d820: 61 73 65 20 74 6f 20 62 65 20 72 65 61 64 61 62  ase to be readab
d830: 6c 65 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20  le.  The fourth 
d840: 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
d850: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
d860: 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69  ntrol()] for thi
d870: 73 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20  s opcode should 
d880: 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  be a pointer to 
d890: 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54  an integer..** T
d8a0: 68 61 74 20 69 6e 74 65 67 65 72 20 69 73 20 30  hat integer is 0
d8b0: 20 74 6f 20 64 69 73 61 62 6c 65 20 70 65 72 73   to disable pers
d8c0: 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20  istent WAL mode 
d8d0: 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 70  or 1 to enable p
d8e0: 65 72 73 69 73 74 65 6e 74 0a 2a 2a 20 57 41 4c  ersistent.** WAL
d8f0: 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69   mode.  If the i
d900: 6e 74 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68  nteger is -1, th
d910: 65 6e 20 69 74 20 69 73 20 6f 76 65 72 77 72 69  en it is overwri
d920: 74 74 65 6e 20 77 69 74 68 20 74 68 65 20 63 75  tten with the cu
d930: 72 72 65 6e 74 0a 2a 2a 20 57 41 4c 20 70 65 72  rrent.** WAL per
d940: 73 69 73 74 65 6e 63 65 20 73 65 74 74 69 6e 67  sistence setting
d950: 2e 0a 2a 2a 20 0a 2a 2f 0a 23 64 65 66 69 6e 65  ..** .*/.#define
d960: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f   SQLITE_FCNTL_LO
d970: 43 4b 53 54 41 54 45 20 20 20 20 20 20 20 20 31  CKSTATE        1
d980: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
d990: 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c  GET_LOCKPROXYFIL
d9a0: 45 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65  E      2.#define
d9b0: 20 53 51 4c 49 54 45 5f 53 45 54 5f 4c 4f 43 4b   SQLITE_SET_LOCK
d9c0: 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 33  PROXYFILE      3
d9d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
d9e0: 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 20 20  LAST_ERRNO      
d9f0: 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65         4.#define
da00: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49   SQLITE_FCNTL_SI
da10: 5a 45 5f 48 49 4e 54 20 20 20 20 20 20 20 20 35  ZE_HINT        5
da20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
da30: 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45  FCNTL_CHUNK_SIZE
da40: 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65         6.#define
da50: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49   SQLITE_FCNTL_FI
da60: 4c 45 5f 50 4f 49 4e 54 45 52 20 20 20 20 20 37  LE_POINTER     7
da70: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
da80: 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54  FCNTL_SYNC_OMITT
da90: 45 44 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65  ED     8.#define
daa0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49   SQLITE_FCNTL_WI
dab0: 4e 33 32 5f 41 56 5f 52 45 54 52 59 20 20 20 39  N32_AV_RETRY   9
dac0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
dad0: 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41  FCNTL_PERSIST_WA
dae0: 4c 20 20 20 20 20 31 30 0a 0a 2f 2a 0a 2a 2a 20  L     10../*.** 
daf0: 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20  CAPI3REF: Mutex 
db00: 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65  Handle.**.** The
db10: 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20 77 69   mutex module wi
db20: 74 68 69 6e 20 53 51 4c 69 74 65 20 64 65 66 69  thin SQLite defi
db30: 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  nes [sqlite3_mut
db40: 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20  ex] to be an.** 
db50: 61 62 73 74 72 61 63 74 20 74 79 70 65 20 66 6f  abstract type fo
db60: 72 20 61 20 6d 75 74 65 78 20 6f 62 6a 65 63 74  r a mutex object
db70: 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f  .  The SQLite co
db80: 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a  re never looks.*
db90: 2a 20 61 74 20 74 68 65 20 69 6e 74 65 72 6e 61  * at the interna
dba0: 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e  l representation
dbb0: 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   of an [sqlite3_
dbc0: 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79  mutex].  It only
dbd0: 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74 68 20 70  .** deals with p
dbe0: 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65 20 5b  ointers to the [
dbf0: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f  sqlite3_mutex] o
dc00: 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74  bject..**.** Mut
dc10: 65 78 65 73 20 61 72 65 20 63 72 65 61 74 65 64  exes are created
dc20: 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
dc30: 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a  mutex_alloc()]..
dc40: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
dc50: 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20  t sqlite3_mutex 
dc60: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a  sqlite3_mutex;..
dc70: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
dc80: 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 62 6a  OS Interface Obj
dc90: 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73  ect.**.** An ins
dca0: 74 61 6e 63 65 20 6f 66 20 74 68 65 20 73 71 6c  tance of the sql
dcb0: 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20  ite3_vfs object 
dcc0: 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65  defines the inte
dcd0: 72 66 61 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a  rface between.**
dce0: 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   the SQLite core
dcf0: 20 61 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79   and the underly
dd00: 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79  ing operating sy
dd10: 73 74 65 6d 2e 20 20 54 68 65 20 22 76 66 73 22  stem.  The "vfs"
dd20: 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65 20  .** in the name 
dd30: 6f 66 20 74 68 65 20 6f 62 6a 65 63 74 20 73 74  of the object st
dd40: 61 6e 64 73 20 66 6f 72 20 22 76 69 72 74 75 61  ands for "virtua
dd50: 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 22 2e 20  l file system". 
dd60: 20 53 65 65 0a 2a 2a 20 74 68 65 20 5b 56 46 53   See.** the [VFS
dd70: 20 7c 20 56 46 53 20 64 6f 63 75 6d 65 6e 74 61   | VFS documenta
dd80: 74 69 6f 6e 5d 20 66 6f 72 20 66 75 72 74 68 65  tion] for furthe
dd90: 72 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  r information..*
dda0: 2a 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 6f  *.** The value o
ddb0: 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66  f the iVersion f
ddc0: 69 65 6c 64 20 69 73 20 69 6e 69 74 69 61 6c 6c  ield is initiall
ddd0: 79 20 31 20 62 75 74 20 6d 61 79 20 62 65 20 6c  y 1 but may be l
dde0: 61 72 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74 75  arger in.** futu
ddf0: 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  re versions of S
de00: 51 4c 69 74 65 2e 20 20 41 64 64 69 74 69 6f 6e  QLite.  Addition
de10: 61 6c 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65  al fields may be
de20: 20 61 70 70 65 6e 64 65 64 20 74 6f 20 74 68 69   appended to thi
de30: 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65 6e  s.** object when
de40: 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 76 61   the iVersion va
de50: 6c 75 65 20 69 73 20 69 6e 63 72 65 61 73 65 64  lue is increased
de60: 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65  .  Note that the
de70: 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f 66   structure.** of
de80: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73   the sqlite3_vfs
de90: 20 6f 62 6a 65 63 74 20 63 68 61 6e 67 65 73 20   object changes 
dea0: 69 6e 20 74 68 65 20 74 72 61 6e 73 61 63 74 69  in the transacti
deb0: 6f 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53 51  on between.** SQ
dec0: 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35  Lite version 3.5
ded0: 2e 39 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e 64  .9 and 3.6.0 and
dee0: 20 79 65 74 20 74 68 65 20 69 56 65 72 73 69 6f   yet the iVersio
def0: 6e 20 66 69 65 6c 64 20 77 61 73 20 6e 6f 74 0a  n field was not.
df00: 2a 2a 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a  ** modified..**.
df10: 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c 65 20  ** The szOsFile 
df20: 66 69 65 6c 64 20 69 73 20 74 68 65 20 73 69 7a  field is the siz
df30: 65 20 6f 66 20 74 68 65 20 73 75 62 63 6c 61 73  e of the subclas
df40: 73 65 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  sed [sqlite3_fil
df50: 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20  e].** structure 
df60: 75 73 65 64 20 62 79 20 74 68 69 73 20 56 46 53  used by this VFS
df70: 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65 20 69 73  .  mxPathname is
df80: 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e   the maximum len
df90: 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68  gth of.** a path
dfa0: 6e 61 6d 65 20 69 6e 20 74 68 69 73 20 56 46 53  name in this VFS
dfb0: 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72  ..**.** Register
dfc0: 65 64 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f  ed sqlite3_vfs o
dfd0: 62 6a 65 63 74 73 20 61 72 65 20 6b 65 70 74 20  bjects are kept 
dfe0: 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74  on a linked list
dff0: 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68   formed by.** th
e000: 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e  e pNext pointer.
e010: 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76    The [sqlite3_v
e020: 66 73 5f 72 65 67 69 73 74 65 72 28 29 5d 0a 2a  fs_register()].*
e030: 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76  * and [sqlite3_v
e040: 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29 5d  fs_unregister()]
e050: 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6e 61   interfaces mana
e060: 67 65 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20  ge this list.** 
e070: 69 6e 20 61 20 74 68 72 65 61 64 2d 73 61 66 65  in a thread-safe
e080: 20 77 61 79 2e 20 20 54 68 65 20 5b 73 71 6c 69   way.  The [sqli
e090: 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20  te3_vfs_find()] 
e0a0: 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 65 61  interface.** sea
e0b0: 72 63 68 65 73 20 74 68 65 20 6c 69 73 74 2e 20  rches the list. 
e0c0: 20 4e 65 69 74 68 65 72 20 74 68 65 20 61 70 70   Neither the app
e0d0: 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f  lication code no
e0e0: 72 20 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70  r the VFS.** imp
e0f0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75  lementation shou
e100: 6c 64 20 75 73 65 20 74 68 65 20 70 4e 65 78 74  ld use the pNext
e110: 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
e120: 54 68 65 20 70 4e 65 78 74 20 66 69 65 6c 64 20  The pNext field 
e130: 69 73 20 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c  is the only fiel
e140: 64 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33  d in the sqlite3
e150: 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63 74 75 72  _vfs.** structur
e160: 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69  e that SQLite wi
e170: 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66 79 2e 20  ll ever modify. 
e180: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c   SQLite will onl
e190: 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d  y access.** or m
e1a0: 6f 64 69 66 79 20 74 68 69 73 20 66 69 65 6c 64  odify this field
e1b0: 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61   while holding a
e1c0: 20 70 61 72 74 69 63 75 6c 61 72 20 73 74 61 74   particular stat
e1d0: 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65  ic mutex..** The
e1e0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f   application sho
e1f0: 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69 66 79  uld never modify
e200: 20 61 6e 79 74 68 69 6e 67 20 77 69 74 68 69 6e   anything within
e210: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73   the sqlite3_vfs
e220: 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20  .** object once 
e230: 74 68 65 20 6f 62 6a 65 63 74 20 68 61 73 20 62  the object has b
e240: 65 65 6e 20 72 65 67 69 73 74 65 72 65 64 2e 0a  een registered..
e250: 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20  **.** The zName 
e260: 66 69 65 6c 64 20 68 6f 6c 64 73 20 74 68 65 20  field holds the 
e270: 6e 61 6d 65 20 6f 66 20 74 68 65 20 56 46 53 20  name of the VFS 
e280: 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d  module.  The nam
e290: 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69  e must.** be uni
e2a0: 71 75 65 20 61 63 72 6f 73 73 20 61 6c 6c 20 56  que across all V
e2b0: 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a  FS modules..**.*
e2c0: 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  * [[sqlite3_vfs.
e2d0: 78 4f 70 65 6e 5d 5d 0a 2a 2a 20 5e 53 51 4c 69  xOpen]].** ^SQLi
e2e0: 74 65 20 67 75 61 72 61 6e 74 65 65 73 20 74 68  te guarantees th
e2f0: 61 74 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65  at the zFilename
e300: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f   parameter to xO
e310: 70 65 6e 0a 2a 2a 20 69 73 20 65 69 74 68 65 72  pen.** is either
e320: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
e330: 6f 72 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e  or string obtain
e340: 65 64 0a 2a 2a 20 66 72 6f 6d 20 78 46 75 6c 6c  ed.** from xFull
e350: 50 61 74 68 6e 61 6d 65 28 29 20 77 69 74 68 20  Pathname() with 
e360: 61 6e 20 6f 70 74 69 6f 6e 61 6c 20 73 75 66 66  an optional suff
e370: 69 78 20 61 64 64 65 64 2e 0a 2a 2a 20 5e 49 66  ix added..** ^If
e380: 20 61 20 73 75 66 66 69 78 20 69 73 20 61 64 64   a suffix is add
e390: 65 64 20 74 6f 20 74 68 65 20 7a 46 69 6c 65 6e  ed to the zFilen
e3a0: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 2c 20 69  ame parameter, i
e3b0: 74 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 73 69 73  t will.** consis
e3c0: 74 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 22 2d  t of a single "-
e3d0: 22 20 63 68 61 72 61 63 74 65 72 20 66 6f 6c 6c  " character foll
e3e0: 6f 77 65 64 20 62 79 20 6e 6f 20 6d 6f 72 65 20  owed by no more 
e3f0: 74 68 61 6e 0a 2a 2a 20 31 30 20 61 6c 70 68 61  than.** 10 alpha
e400: 6e 75 6d 65 72 69 63 20 61 6e 64 2f 6f 72 20 22  numeric and/or "
e410: 2d 22 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a  -" characters..*
e420: 2a 20 5e 53 51 4c 69 74 65 20 66 75 72 74 68 65  * ^SQLite furthe
e430: 72 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61  r guarantees tha
e440: 74 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20  t.** the string 
e450: 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 6e  will be valid an
e460: 64 20 75 6e 63 68 61 6e 67 65 64 20 75 6e 74 69  d unchanged unti
e470: 6c 20 78 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a  l xClose() is.**
e480: 20 63 61 6c 6c 65 64 2e 20 42 65 63 61 75 73 65   called. Because
e490: 20 6f 66 20 74 68 65 20 70 72 65 76 69 6f 75 73   of the previous
e4a0: 20 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20 74 68   sentence,.** th
e4b0: 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  e [sqlite3_file]
e4c0: 20 63 61 6e 20 73 61 66 65 6c 79 20 73 74 6f 72   can safely stor
e4d0: 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  e a pointer to t
e4e0: 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69  he.** filename i
e4f0: 66 20 69 74 20 6e 65 65 64 73 20 74 6f 20 72 65  f it needs to re
e500: 6d 65 6d 62 65 72 20 74 68 65 20 66 69 6c 65 6e  member the filen
e510: 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20 72 65 61  ame for some rea
e520: 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 20 7a  son..** If the z
e530: 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74  Filename paramet
e540: 65 72 20 74 6f 20 78 4f 70 65 6e 20 69 73 20 61  er to xOpen is a
e550: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68   NULL pointer th
e560: 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74  en xOpen.** must
e570: 20 69 6e 76 65 6e 74 20 69 74 73 20 6f 77 6e 20   invent its own 
e580: 74 65 6d 70 6f 72 61 72 79 20 6e 61 6d 65 20 66  temporary name f
e590: 6f 72 20 74 68 65 20 66 69 6c 65 2e 20 20 5e 57  or the file.  ^W
e5a0: 68 65 6e 65 76 65 72 20 74 68 65 20 0a 2a 2a 20  henever the .** 
e5b0: 78 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65  xFilename parame
e5c0: 74 65 72 20 69 73 20 4e 55 4c 4c 20 69 74 20 77  ter is NULL it w
e5d0: 69 6c 6c 20 61 6c 73 6f 20 62 65 20 74 68 65 20  ill also be the 
e5e0: 63 61 73 65 20 74 68 61 74 20 74 68 65 0a 2a 2a  case that the.**
e5f0: 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72   flags parameter
e600: 20 77 69 6c 6c 20 69 6e 63 6c 75 64 65 20 5b 53   will include [S
e610: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
e620: 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a  EONCLOSE]..**.**
e630: 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d   The flags argum
e640: 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28 29 20 69  ent to xOpen() i
e650: 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62 69 74 73  ncludes all bits
e660: 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68 65 20 66   set in.** the f
e670: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f  lags argument to
e680: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
e690: 32 28 29 5d 2e 20 20 4f 72 20 69 66 20 5b 73 71  2()].  Or if [sq
e6a0: 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a  lite3_open()].**
e6b0: 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   or [sqlite3_ope
e6c0: 6e 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20  n16()] is used, 
e6d0: 74 68 65 6e 20 66 6c 61 67 73 20 69 6e 63 6c 75  then flags inclu
e6e0: 64 65 73 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20  des at least.** 
e6f0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
e700: 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54  DWRITE] | [SQLIT
e710: 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e 20  E_OPEN_CREATE]. 
e720: 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29 20 6f  .** If xOpen() o
e730: 70 65 6e 73 20 61 20 66 69 6c 65 20 72 65 61 64  pens a file read
e740: 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20 73 65  -only then it se
e750: 74 73 20 2a 70 4f 75 74 46 6c 61 67 73 20 74 6f  ts *pOutFlags to
e760: 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c  .** include [SQL
e770: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
e780: 59 5d 2e 20 20 4f 74 68 65 72 20 62 69 74 73 20  Y].  Other bits 
e790: 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d 61  in *pOutFlags ma
e7a0: 79 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20  y be set..**.** 
e7b0: 5e 28 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c  ^(SQLite will al
e7c0: 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68  so add one of th
e7d0: 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67  e following flag
e7e0: 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29  s to the xOpen()
e7f0: 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e 64  .** call, depend
e800: 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65 63  ing on the objec
e810: 74 20 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a 0a  t being opened:.
e820: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
e830: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
e840: 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69  _MAIN_DB].** <li
e850: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
e860: 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a  MAIN_JOURNAL].**
e870: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
e880: 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20  PEN_TEMP_DB].** 
e890: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
e8a0: 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d  EN_TEMP_JOURNAL]
e8b0: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
e8c0: 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54  E_OPEN_TRANSIENT
e8d0: 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  _DB].** <li>  [S
e8e0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f  QLITE_OPEN_SUBJO
e8f0: 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  URNAL].** <li>  
e900: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53  [SQLITE_OPEN_MAS
e910: 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20  TER_JOURNAL].** 
e920: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
e930: 45 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e  EN_WAL].** </ul>
e940: 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c  )^.**.** The fil
e950: 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61  e I/O implementa
e960: 74 69 6f 6e 20 63 61 6e 20 75 73 65 20 74 68 65  tion can use the
e970: 20 6f 62 6a 65 63 74 20 74 79 70 65 20 66 6c 61   object type fla
e980: 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 20  gs to.** change 
e990: 74 68 65 20 77 61 79 20 69 74 20 64 65 61 6c 73  the way it deals
e9a0: 20 77 69 74 68 20 66 69 6c 65 73 2e 20 20 46 6f   with files.  Fo
e9b0: 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70  r example, an ap
e9c0: 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61  plication.** tha
e9d0: 74 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20  t does not care 
e9e0: 61 62 6f 75 74 20 63 72 61 73 68 20 72 65 63 6f  about crash reco
e9f0: 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b  very or rollback
ea00: 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74   might make.** t
ea10: 68 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75  he open of a jou
ea20: 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f  rnal file a no-o
ea30: 70 2e 20 20 57 72 69 74 65 73 20 74 6f 20 74 68  p.  Writes to th
ea40: 69 73 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64  is journal would
ea50: 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f  .** also be no-o
ea60: 70 73 2c 20 61 6e 64 20 61 6e 79 20 61 74 74 65  ps, and any atte
ea70: 6d 70 74 20 74 6f 20 72 65 61 64 20 74 68 65 20  mpt to read the 
ea80: 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 20 72 65  journal would re
ea90: 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 49  turn.** SQLITE_I
eaa0: 4f 45 52 52 2e 20 20 4f 72 20 74 68 65 20 69 6d  OERR.  Or the im
eab0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67  plementation mig
eac0: 68 74 20 72 65 63 6f 67 6e 69 7a 65 20 74 68 61  ht recognize tha
ead0: 74 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  t a database.** 
eae0: 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 64 6f 69  file will be doi
eaf0: 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e 65 64 20  ng page-aligned 
eb00: 73 65 63 74 6f 72 20 72 65 61 64 73 20 61 6e 64  sector reads and
eb10: 20 77 72 69 74 65 73 20 69 6e 20 61 20 72 61 6e   writes in a ran
eb20: 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20 61 6e 64  dom.** order and
eb30: 20 73 65 74 20 75 70 20 69 74 73 20 49 2f 4f 20   set up its I/O 
eb40: 73 75 62 73 79 73 74 65 6d 20 61 63 63 6f 72 64  subsystem accord
eb50: 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c  ingly..**.** SQL
eb60: 69 74 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 61  ite might also a
eb70: 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f  dd one of the fo
eb80: 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f  llowing flags to
eb90: 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f   the xOpen metho
eba0: 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  d:.**.** <ul>.**
ebb0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50   <li> [SQLITE_OP
ebc0: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45  EN_DELETEONCLOSE
ebd0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
ebe0: 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45  E_OPEN_EXCLUSIVE
ebf0: 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  ].** </ul>.**.**
ec00: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   The [SQLITE_OPE
ec10: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d  N_DELETEONCLOSE]
ec20: 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 65 20   flag means the 
ec30: 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a  file should be.*
ec40: 2a 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 69  * deleted when i
ec50: 74 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 5e 54  t is closed.  ^T
ec60: 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
ec70: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a  DELETEONCLOSE].*
ec80: 2a 20 77 69 6c 6c 20 62 65 20 73 65 74 20 66 6f  * will be set fo
ec90: 72 20 54 45 4d 50 20 64 61 74 61 62 61 73 65 73  r TEMP databases
eca0: 20 61 6e 64 20 74 68 65 69 72 20 6a 6f 75 72 6e   and their journ
ecb0: 61 6c 73 2c 20 74 72 61 6e 73 69 65 6e 74 0a 2a  als, transient.*
ecc0: 2a 20 64 61 74 61 62 61 73 65 73 2c 20 61 6e 64  * databases, and
ecd0: 20 73 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a   subjournals..**
ece0: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
ecf0: 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d  _OPEN_EXCLUSIVE]
ed00: 20 66 6c 61 67 20 69 73 20 61 6c 77 61 79 73 20   flag is always 
ed10: 75 73 65 64 20 69 6e 20 63 6f 6e 6a 75 6e 63 74  used in conjunct
ed20: 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ion.** with the 
ed30: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45  [SQLITE_OPEN_CRE
ed40: 41 54 45 5d 20 66 6c 61 67 2c 20 77 68 69 63 68  ATE] flag, which
ed50: 20 61 72 65 20 62 6f 74 68 20 64 69 72 65 63 74   are both direct
ed60: 6c 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75 73 20  ly.** analogous 
ed70: 74 6f 20 74 68 65 20 4f 5f 45 58 43 4c 20 61 6e  to the O_EXCL an
ed80: 64 20 4f 5f 43 52 45 41 54 20 66 6c 61 67 73 20  d O_CREAT flags 
ed90: 6f 66 20 74 68 65 20 50 4f 53 49 58 20 6f 70 65  of the POSIX ope
eda0: 6e 28 29 0a 2a 2a 20 41 50 49 2e 20 20 54 68 65  n().** API.  The
edb0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43   SQLITE_OPEN_EXC
edc0: 4c 55 53 49 56 45 20 66 6c 61 67 2c 20 77 68 65  LUSIVE flag, whe
edd0: 6e 20 70 61 69 72 65 64 20 77 69 74 68 20 74 68  n paired with th
ede0: 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 50 45  e .** SQLITE_OPE
edf0: 4e 5f 43 52 45 41 54 45 2c 20 69 73 20 75 73 65  N_CREATE, is use
ee00: 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68  d to indicate th
ee10: 61 74 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 61  at file should a
ee20: 6c 77 61 79 73 0a 2a 2a 20 62 65 20 63 72 65 61  lways.** be crea
ee30: 74 65 64 2c 20 61 6e 64 20 74 68 61 74 20 69 74  ted, and that it
ee40: 20 69 73 20 61 6e 20 65 72 72 6f 72 20 69 66 20   is an error if 
ee50: 69 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74  it already exist
ee60: 73 2e 0a 2a 2a 20 49 74 20 69 73 20 3c 69 3e 6e  s..** It is <i>n
ee70: 6f 74 3c 2f 69 3e 20 75 73 65 64 20 74 6f 20 69  ot</i> used to i
ee80: 6e 64 69 63 61 74 65 20 74 68 65 20 66 69 6c 65  ndicate the file
ee90: 20 73 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65   should be opene
eea0: 64 20 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73  d .** for exclus
eeb0: 69 76 65 20 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a  ive access..**.*
eec0: 2a 20 5e 41 74 20 6c 65 61 73 74 20 73 7a 4f 73  * ^At least szOs
eed0: 46 69 6c 65 20 62 79 74 65 73 20 6f 66 20 6d 65  File bytes of me
eee0: 6d 6f 72 79 20 61 72 65 20 61 6c 6c 6f 63 61 74  mory are allocat
eef0: 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20  ed by SQLite.** 
ef00: 74 6f 20 68 6f 6c 64 20 74 68 65 20 20 5b 73 71  to hold the  [sq
ef10: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73 74 72 75  lite3_file] stru
ef20: 63 74 75 72 65 20 70 61 73 73 65 64 20 61 73 20  cture passed as 
ef30: 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 61 72 67  the third.** arg
ef40: 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 2e 20  ument to xOpen. 
ef50: 20 54 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f   The xOpen metho
ef60: 64 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20  d does not have 
ef70: 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 74  to.** allocate t
ef80: 68 65 20 73 74 72 75 63 74 75 72 65 3b 20 69 74  he structure; it
ef90: 20 73 68 6f 75 6c 64 20 6a 75 73 74 20 66 69 6c   should just fil
efa0: 6c 20 69 74 20 69 6e 2e 20 20 4e 6f 74 65 20 74  l it in.  Note t
efb0: 68 61 74 0a 2a 2a 20 74 68 65 20 78 4f 70 65 6e  hat.** the xOpen
efc0: 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 73 65 74   method must set
efd0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c   the sqlite3_fil
efe0: 65 2e 70 4d 65 74 68 6f 64 73 20 74 6f 20 65 69  e.pMethods to ei
eff0: 74 68 65 72 0a 2a 2a 20 61 20 76 61 6c 69 64 20  ther.** a valid 
f000: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
f010: 6f 64 73 5d 20 6f 62 6a 65 63 74 20 6f 72 20 74  ods] object or t
f020: 6f 20 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e 20 6d  o NULL.  xOpen m
f030: 75 73 74 20 64 6f 0a 2a 2a 20 74 68 69 73 20 65  ust do.** this e
f040: 76 65 6e 20 69 66 20 74 68 65 20 6f 70 65 6e 20  ven if the open 
f050: 66 61 69 6c 73 2e 20 20 53 51 4c 69 74 65 20 65  fails.  SQLite e
f060: 78 70 65 63 74 73 20 74 68 61 74 20 74 68 65 20  xpects that the 
f070: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65  sqlite3_file.pMe
f080: 74 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65 6e 74  thods.** element
f090: 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61   will be valid a
f0a0: 66 74 65 72 20 78 4f 70 65 6e 20 72 65 74 75 72  fter xOpen retur
f0b0: 6e 73 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66  ns regardless of
f0c0: 20 74 68 65 20 73 75 63 63 65 73 73 0a 2a 2a 20   the success.** 
f0d0: 6f 72 20 66 61 69 6c 75 72 65 20 6f 66 20 74 68  or failure of th
f0e0: 65 20 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a 2a 2a  e xOpen call..**
f0f0: 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66  .** [[sqlite3_vf
f100: 73 2e 78 41 63 63 65 73 73 5d 5d 0a 2a 2a 20 5e  s.xAccess]].** ^
f110: 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  The flags argume
f120: 6e 74 20 74 6f 20 78 41 63 63 65 73 73 28 29 20  nt to xAccess() 
f130: 6d 61 79 20 62 65 20 5b 53 51 4c 49 54 45 5f 41  may be [SQLITE_A
f140: 43 43 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a  CCESS_EXISTS].**
f150: 20 74 6f 20 74 65 73 74 20 66 6f 72 20 74 68 65   to test for the
f160: 20 65 78 69 73 74 65 6e 63 65 20 6f 66 20 61 20   existence of a 
f170: 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45  file, or [SQLITE
f180: 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54  _ACCESS_READWRIT
f190: 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68  E] to.** test wh
f1a0: 65 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20  ether a file is 
f1b0: 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69  readable and wri
f1c0: 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54  table, or [SQLIT
f1d0: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a  E_ACCESS_READ].*
f1e0: 2a 20 74 6f 20 74 65 73 74 20 77 68 65 74 68 65  * to test whethe
f1f0: 72 20 61 20 66 69 6c 65 20 69 73 20 61 74 20 6c  r a file is at l
f200: 65 61 73 74 20 72 65 61 64 61 62 6c 65 2e 20 20  east readable.  
f210: 20 54 68 65 20 66 69 6c 65 20 63 61 6e 20 62 65   The file can be
f220: 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e   a.** directory.
f230: 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77  .**.** ^SQLite w
f240: 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63  ill always alloc
f250: 61 74 65 20 61 74 20 6c 65 61 73 74 20 6d 78 50  ate at least mxP
f260: 61 74 68 6e 61 6d 65 2b 31 20 62 79 74 65 73 20  athname+1 bytes 
f270: 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75  for the.** outpu
f280: 74 20 62 75 66 66 65 72 20 78 46 75 6c 6c 50 61  t buffer xFullPa
f290: 74 68 6e 61 6d 65 2e 20 20 54 68 65 20 65 78 61  thname.  The exa
f2a0: 63 74 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6f  ct size of the o
f2b0: 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20  utput buffer.** 
f2c0: 69 73 20 61 6c 73 6f 20 70 61 73 73 65 64 20 61  is also passed a
f2d0: 73 20 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f  s a parameter to
f2e0: 20 62 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e 20   both  methods. 
f2f0: 49 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75  If the output bu
f300: 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c  ffer.** is not l
f310: 61 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51  arge enough, [SQ
f320: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73  LITE_CANTOPEN] s
f330: 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65  hould be returne
f340: 64 2e 20 53 69 6e 63 65 20 74 68 69 73 20 69 73  d. Since this is
f350: 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73 20 61  .** handled as a
f360: 20 66 61 74 61 6c 20 65 72 72 6f 72 20 62 79 20   fatal error by 
f370: 53 51 4c 69 74 65 2c 20 76 66 73 20 69 6d 70 6c  SQLite, vfs impl
f380: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75  ementations shou
f390: 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74  ld endeavor.** t
f3a0: 6f 20 70 72 65 76 65 6e 74 20 74 68 69 73 20 62  o prevent this b
f3b0: 79 20 73 65 74 74 69 6e 67 20 6d 78 50 61 74 68  y setting mxPath
f3c0: 6e 61 6d 65 20 74 6f 20 61 20 73 75 66 66 69 63  name to a suffic
f3d0: 69 65 6e 74 6c 79 20 6c 61 72 67 65 20 76 61 6c  iently large val
f3e0: 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52  ue..**.** The xR
f3f0: 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c  andomness(), xSl
f400: 65 65 70 28 29 2c 20 78 43 75 72 72 65 6e 74 54  eep(), xCurrentT
f410: 69 6d 65 28 29 2c 20 61 6e 64 20 78 43 75 72 72  ime(), and xCurr
f420: 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 0a 2a  entTimeInt64().*
f430: 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  * interfaces are
f440: 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 61 20   not strictly a 
f450: 70 61 72 74 20 6f 66 20 74 68 65 20 66 69 6c 65  part of the file
f460: 73 79 73 74 65 6d 2c 20 62 75 74 20 74 68 65 79  system, but they
f470: 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64   are.** included
f480: 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 72 75   in the VFS stru
f490: 63 74 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65  cture for comple
f4a0: 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78  teness..** The x
f4b0: 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e  Randomness() fun
f4c0: 63 74 69 6f 6e 20 61 74 74 65 6d 70 74 73 20 74  ction attempts t
f4d0: 6f 20 72 65 74 75 72 6e 20 6e 42 79 74 65 73 20  o return nBytes 
f4e0: 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64  bytes.** of good
f4f0: 2d 71 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e  -quality randomn
f500: 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20  ess into zOut.  
f510: 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  The return value
f520: 20 69 73 0a 2a 2a 20 74 68 65 20 61 63 74 75 61   is.** the actua
f530: 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  l number of byte
f540: 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20  s of randomness 
f550: 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 65  obtained..** The
f560: 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64   xSleep() method
f570: 20 63 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c   causes the call
f580: 69 6e 67 20 74 68 72 65 61 64 20 74 6f 20 73 6c  ing thread to sl
f590: 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65  eep for at.** le
f5a0: 61 73 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ast the number o
f5b0: 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20 67  f microseconds g
f5c0: 69 76 65 6e 2e 20 20 5e 54 68 65 20 78 43 75 72  iven.  ^The xCur
f5d0: 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65  rentTime().** me
f5e0: 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 4a  thod returns a J
f5f0: 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62 65 72  ulian Day Number
f600: 20 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74   for the current
f610: 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20 61   date and time a
f620: 73 0a 2a 2a 20 61 20 66 6c 6f 61 74 69 6e 67 20  s.** a floating 
f630: 70 6f 69 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a 20  point value..** 
f640: 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d  ^The xCurrentTim
f650: 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20  eInt64() method 
f660: 72 65 74 75 72 6e 73 2c 20 61 73 20 61 6e 20 69  returns, as an i
f670: 6e 74 65 67 65 72 2c 20 74 68 65 20 4a 75 6c 69  nteger, the Juli
f680: 61 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d 62 65 72  an.** Day Number
f690: 20 6d 75 6c 74 69 70 6c 69 65 64 20 62 79 20 38   multiplied by 8
f6a0: 36 34 30 30 30 30 30 20 28 74 68 65 20 6e 75 6d  6400000 (the num
f6b0: 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f  ber of milliseco
f6c0: 6e 64 73 20 69 6e 20 0a 2a 2a 20 61 20 32 34 2d  nds in .** a 24-
f6d0: 68 6f 75 72 20 64 61 79 29 2e 20 20 0a 2a 2a 20  hour day).  .** 
f6e0: 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65  ^SQLite will use
f6f0: 20 74 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d   the xCurrentTim
f700: 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20  eInt64() method 
f710: 74 6f 20 67 65 74 20 74 68 65 20 63 75 72 72 65  to get the curre
f720: 6e 74 0a 2a 2a 20 64 61 74 65 20 61 6e 64 20 74  nt.** date and t
f730: 69 6d 65 20 69 66 20 74 68 61 74 20 6d 65 74 68  ime if that meth
f740: 6f 64 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20  od is available 
f750: 28 69 66 20 69 56 65 72 73 69 6f 6e 20 69 73 20  (if iVersion is 
f760: 32 20 6f 72 20 0a 2a 2a 20 67 72 65 61 74 65 72  2 or .** greater
f770: 20 61 6e 64 20 74 68 65 20 66 75 6e 63 74 69 6f   and the functio
f780: 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74  n pointer is not
f790: 20 4e 55 4c 4c 29 20 61 6e 64 20 77 69 6c 6c 20   NULL) and will 
f7a0: 66 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f 20  fall back.** to 
f7b0: 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 20 69  xCurrentTime() i
f7c0: 66 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e  f xCurrentTimeIn
f7d0: 74 36 34 28 29 20 69 73 20 75 6e 61 76 61 69 6c  t64() is unavail
f7e0: 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  able..**.** ^The
f7f0: 20 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 28   xSetSystemCall(
f800: 29 2c 20 78 47 65 74 53 79 73 74 65 6d 43 61 6c  ), xGetSystemCal
f810: 6c 28 29 2c 20 61 6e 64 20 78 4e 65 73 74 53 79  l(), and xNestSy
f820: 73 74 65 6d 43 61 6c 6c 28 29 20 69 6e 74 65 72  stemCall() inter
f830: 66 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74  faces.** are not
f840: 20 75 73 65 64 20 62 79 20 74 68 65 20 53 51 4c   used by the SQL
f850: 69 74 65 20 63 6f 72 65 2e 20 20 54 68 65 73 65  ite core.  These
f860: 20 6f 70 74 69 6f 6e 61 6c 20 69 6e 74 65 72 66   optional interf
f870: 61 63 65 73 20 61 72 65 20 70 72 6f 76 69 64 65  aces are provide
f880: 64 0a 2a 2a 20 62 79 20 73 6f 6d 65 20 56 46 53  d.** by some VFS
f890: 65 73 20 74 6f 20 66 61 63 69 6c 69 74 61 74 65  es to facilitate
f8a0: 20 74 65 73 74 69 6e 67 20 6f 66 20 74 68 65 20   testing of the 
f8b0: 56 46 53 20 63 6f 64 65 2e 20 42 79 20 6f 76 65  VFS code. By ove
f8c0: 72 72 69 64 69 6e 67 20 0a 2a 2a 20 73 79 73 74  rriding .** syst
f8d0: 65 6d 20 63 61 6c 6c 73 20 77 69 74 68 20 66 75  em calls with fu
f8e0: 6e 63 74 69 6f 6e 73 20 75 6e 64 65 72 20 69 74  nctions under it
f8f0: 73 20 63 6f 6e 74 72 6f 6c 2c 20 61 20 74 65 73  s control, a tes
f900: 74 20 70 72 6f 67 72 61 6d 20 63 61 6e 0a 2a 2a  t program can.**
f910: 20 73 69 6d 75 6c 61 74 65 20 66 61 75 6c 74 73   simulate faults
f920: 20 61 6e 64 20 65 72 72 6f 72 20 63 6f 6e 64 69   and error condi
f930: 74 69 6f 6e 73 20 74 68 61 74 20 77 6f 75 6c 64  tions that would
f940: 20 6f 74 68 65 72 77 69 73 65 20 62 65 20 64 69   otherwise be di
f950: 66 66 69 63 75 6c 74 0a 2a 2a 20 6f 72 20 69 6d  fficult.** or im
f960: 70 6f 73 73 69 62 6c 65 20 74 6f 20 69 6e 64 75  possible to indu
f970: 63 65 2e 20 20 54 68 65 20 73 65 74 20 6f 66 20  ce.  The set of 
f980: 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 74 68 61  system calls tha
f990: 74 20 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64  t can be overrid
f9a0: 64 65 6e 0a 2a 2a 20 76 61 72 69 65 73 20 66 72  den.** varies fr
f9b0: 6f 6d 20 6f 6e 65 20 56 46 53 20 74 6f 20 61 6e  om one VFS to an
f9c0: 6f 74 68 65 72 2c 20 61 6e 64 20 66 72 6f 6d 20  other, and from 
f9d0: 6f 6e 65 20 76 65 72 73 69 6f 6e 20 6f 66 20 74  one version of t
f9e0: 68 65 20 73 61 6d 65 20 56 46 53 20 74 6f 20 74  he same VFS to t
f9f0: 68 65 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70 70  he.** next.  App
fa00: 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 75  lications that u
fa10: 73 65 20 74 68 65 73 65 20 69 6e 74 65 72 66 61  se these interfa
fa20: 63 65 73 20 6d 75 73 74 20 62 65 20 70 72 65 70  ces must be prep
fa30: 61 72 65 64 20 66 6f 72 20 61 6e 79 0a 2a 2a 20  ared for any.** 
fa40: 6f 72 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20  or all of these 
fa50: 69 6e 74 65 72 66 61 63 65 73 20 74 6f 20 62 65  interfaces to be
fa60: 20 4e 55 4c 4c 20 6f 72 20 66 6f 72 20 74 68 65   NULL or for the
fa70: 69 72 20 62 65 68 61 76 69 6f 72 20 74 6f 20 63  ir behavior to c
fa80: 68 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f 6e  hange.** from on
fa90: 65 20 72 65 6c 65 61 73 65 20 74 6f 20 74 68 65  e release to the
faa0: 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74   next.  Applicat
fab0: 69 6f 6e 73 20 6d 75 73 74 20 6e 6f 74 20 61 74  ions must not at
fac0: 74 65 6d 70 74 20 74 6f 20 61 63 63 65 73 73 0a  tempt to access.
fad0: 2a 2a 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20  ** any of these 
fae0: 6d 65 74 68 6f 64 73 20 69 66 20 74 68 65 20 69  methods if the i
faf0: 56 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 56  Version of the V
fb00: 46 53 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20  FS is less than 
fb10: 33 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  3..*/.typedef st
fb20: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73  ruct sqlite3_vfs
fb30: 20 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a 74 79   sqlite3_vfs;.ty
fb40: 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c  pedef void (*sql
fb50: 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72  ite3_syscall_ptr
fb60: 29 28 76 6f 69 64 29 3b 0a 73 74 72 75 63 74 20  )(void);.struct 
fb70: 73 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20  sqlite3_vfs {.  
fb80: 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20  int iVersion;   
fb90: 20 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75           /* Stru
fba0: 63 74 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75  cture version nu
fbb0: 6d 62 65 72 20 28 63 75 72 72 65 6e 74 6c 79 20  mber (currently 
fbc0: 33 29 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73  3) */.  int szOs
fbd0: 46 69 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20  File;           
fbe0: 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63   /* Size of subc
fbf0: 6c 61 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66  lassed sqlite3_f
fc00: 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50  ile */.  int mxP
fc10: 61 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20  athname;        
fc20: 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c    /* Maximum fil
fc30: 65 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74  e pathname lengt
fc40: 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76  h */.  sqlite3_v
fc50: 66 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20  fs *pNext;      
fc60: 2f 2a 20 4e 65 78 74 20 72 65 67 69 73 74 65 72  /* Next register
fc70: 65 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73  ed VFS */.  cons
fc80: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20  t char *zName;  
fc90: 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20       /* Name of 
fca0: 74 68 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c  this virtual fil
fcb0: 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f  e system */.  vo
fcc0: 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20  id *pAppData;   
fcd0: 20 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65         /* Pointe
fce0: 72 20 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e  r to application
fcf0: 2d 73 70 65 63 69 66 69 63 20 64 61 74 61 20 2a  -specific data *
fd00: 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29  /.  int (*xOpen)
fd10: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
fd20: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
fd30: 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  , sqlite3_file*,
fd40: 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
fd50: 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a  int flags, int *
fd60: 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e  pOutFlags);.  in
fd70: 74 20 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c  t (*xDelete)(sql
fd80: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
fd90: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e   char *zName, in
fda0: 74 20 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e  t syncDir);.  in
fdb0: 74 20 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c  t (*xAccess)(sql
fdc0: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
fdd0: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e   char *zName, in
fde0: 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52  t flags, int *pR
fdf0: 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a  esOut);.  int (*
fe00: 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73  xFullPathname)(s
fe10: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
fe20: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
fe30: 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a  int nOut, char *
fe40: 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28  zOut);.  void *(
fe50: 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65  *xDlOpen)(sqlite
fe60: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
fe70: 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a  ar *zFilename);.
fe80: 20 20 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f    void (*xDlErro
fe90: 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  r)(sqlite3_vfs*,
fea0: 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72   int nByte, char
feb0: 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f   *zErrMsg);.  vo
fec0: 69 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73  id (*(*xDlSym)(s
fed0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64  qlite3_vfs*,void
fee0: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
fef0: 53 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a  Symbol))(void);.
ff00: 20 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73    void (*xDlClos
ff10: 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  e)(sqlite3_vfs*,
ff20: 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28   void*);.  int (
ff30: 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71  *xRandomness)(sq
ff40: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20  lite3_vfs*, int 
ff50: 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75  nByte, char *zOu
ff60: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65  t);.  int (*xSle
ff70: 65 70 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ep)(sqlite3_vfs*
ff80: 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e  , int microsecon
ff90: 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75  ds);.  int (*xCu
ffa0: 72 72 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74  rrentTime)(sqlit
ffb0: 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a  e3_vfs*, double*
ffc0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c  );.  int (*xGetL
ffd0: 61 73 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65  astError)(sqlite
ffe0: 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61  3_vfs*, int, cha
fff0: 72 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20  r *);.  /*.  ** 
10000 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76  The methods abov
10010 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e  e are in version
10020 20 31 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65   1 of the sqlite
10030 5f 76 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a 2a  _vfs object.  **
10040 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68   definition.  Th
10050 6f 73 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20  ose that follow 
10060 61 72 65 20 61 64 64 65 64 20 69 6e 20 76 65 72  are added in ver
10070 73 69 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72 0a  sion 2 or later.
10080 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 43 75    */.  int (*xCu
10090 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 29 28  rrentTimeInt64)(
100a0 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 73 71  sqlite3_vfs*, sq
100b0 6c 69 74 65 33 5f 69 6e 74 36 34 2a 29 3b 0a 20  lite3_int64*);. 
100c0 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74   /*.  ** The met
100d0 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69  hods above are i
100e0 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 61 6e 64  n versions 1 and
100f0 20 32 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65   2 of the sqlite
10100 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a  _vfs object..  *
10110 2a 20 54 68 6f 73 65 20 62 65 6c 6f 77 20 61 72  * Those below ar
10120 65 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20  e for version 3 
10130 61 6e 64 20 67 72 65 61 74 65 72 2e 0a 20 20 2a  and greater..  *
10140 2f 0a 20 20 69 6e 74 20 28 2a 78 53 65 74 53 79  /.  int (*xSetSy
10150 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65  stemCall)(sqlite
10160 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
10170 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74  ar *zName, sqlit
10180 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 3b  e3_syscall_ptr);
10190 0a 20 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61  .  sqlite3_sysca
101a0 6c 6c 5f 70 74 72 20 28 2a 78 47 65 74 53 79 73  ll_ptr (*xGetSys
101b0 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33  temCall)(sqlite3
101c0 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
101d0 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f 6e  r *zName);.  con
101e0 73 74 20 63 68 61 72 20 2a 28 2a 78 4e 65 78 74  st char *(*xNext
101f0 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69  SystemCall)(sqli
10200 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
10210 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20  char *zName);.  
10220 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68  /*.  ** The meth
10230 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e  ods above are in
10240 20 76 65 72 73 69 6f 6e 73 20 31 20 74 68 72 6f   versions 1 thro
10250 75 67 68 20 33 20 6f 66 20 74 68 65 20 73 71 6c  ugh 3 of the sql
10260 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a  ite_vfs object..
10270 20 20 2a 2a 20 4e 65 77 20 66 69 65 6c 64 73 20    ** New fields 
10280 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20  may be appended 
10290 69 6e 20 66 69 67 75 72 65 20 76 65 72 73 69 6f  in figure versio
102a0 6e 73 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f  ns.  The iVersio
102b0 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c  n.  ** value wil
102c0 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e  l increment when
102d0 65 76 65 72 20 74 68 69 73 20 68 61 70 70 65 6e  ever this happen
102e0 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a  s. .  */.};../*.
102f0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61  ** CAPI3REF: Fla
10300 67 73 20 66 6f 72 20 74 68 65 20 78 41 63 63 65  gs for the xAcce
10310 73 73 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a  ss VFS method.**
10320 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65  .** These intege
10330 72 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20  r constants can 
10340 62 65 20 75 73 65 64 20 61 73 20 74 68 65 20 74  be used as the t
10350 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
10360 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73  o.** the xAccess
10370 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73   method of an [s
10380 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
10390 63 74 2e 20 20 54 68 65 79 20 64 65 74 65 72 6d  ct.  They determ
103a0 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64  ine.** what kind
103b0 20 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e 73 20   of permissions 
103c0 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68  the xAccess meth
103d0 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f  od is looking fo
103e0 72 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54  r..** With SQLIT
103f0 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 2c  E_ACCESS_EXISTS,
10400 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74   the xAccess met
10410 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68  hod.** simply ch
10420 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65  ecks whether the
10430 20 66 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a   file exists..**
10440 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43   With SQLITE_ACC
10450 45 53 53 5f 52 45 41 44 57 52 49 54 45 2c 20 74  ESS_READWRITE, t
10460 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
10470 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74  d.** checks whet
10480 68 65 72 20 74 68 65 20 6e 61 6d 65 64 20 64 69  her the named di
10490 72 65 63 74 6f 72 79 20 69 73 20 62 6f 74 68 20  rectory is both 
104a0 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69  readable and wri
104b0 74 61 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74 68  table.** (in oth
104c0 65 72 20 77 6f 72 64 73 2c 20 69 66 20 66 69 6c  er words, if fil
104d0 65 73 20 63 61 6e 20 62 65 20 61 64 64 65 64 2c  es can be added,
104e0 20 72 65 6d 6f 76 65 64 2c 20 61 6e 64 20 72 65   removed, and re
104f0 6e 61 6d 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20  named within.** 
10500 74 68 65 20 64 69 72 65 63 74 6f 72 79 29 2e 0a  the directory)..
10510 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43  ** The SQLITE_AC
10520 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20 63  CESS_READWRITE c
10530 6f 6e 73 74 61 6e 74 20 69 73 20 63 75 72 72 65  onstant is curre
10540 6e 74 6c 79 20 75 73 65 64 20 6f 6e 6c 79 20 62  ntly used only b
10550 79 20 74 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73  y the.** [temp_s
10560 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70  tore_directory p
10570 72 61 67 6d 61 5d 2c 20 74 68 6f 75 67 68 20 74  ragma], though t
10580 68 69 73 20 63 6f 75 6c 64 20 63 68 61 6e 67 65  his could change
10590 20 69 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a 20   in a future.** 
105a0 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74  release of SQLit
105b0 65 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54  e..** With SQLIT
105c0 45 5f 41 43 43 45 53 53 5f 52 45 41 44 2c 20 74  E_ACCESS_READ, t
105d0 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
105e0 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74  d.** checks whet
105f0 68 65 72 20 74 68 65 20 66 69 6c 65 20 69 73 20  her the file is 
10600 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20 53  readable.  The S
10610 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
10620 44 20 63 6f 6e 73 74 61 6e 74 20 69 73 0a 2a 2a  D constant is.**
10630 20 63 75 72 72 65 6e 74 6c 79 20 75 6e 75 73 65   currently unuse
10640 64 2c 20 74 68 6f 75 67 68 20 69 74 20 6d 69 67  d, though it mig
10650 68 74 20 62 65 20 75 73 65 64 20 69 6e 20 61 20  ht be used in a 
10660 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f  future release o
10670 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a  f.** SQLite..*/.
10680 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
10690 43 43 45 53 53 5f 45 58 49 53 54 53 20 20 20 20  CCESS_EXISTS    
106a0 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
106b0 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54  _ACCESS_READWRIT
106c0 45 20 31 20 20 20 2f 2a 20 55 73 65 64 20 62 79  E 1   /* Used by
106d0 20 50 52 41 47 4d 41 20 74 65 6d 70 5f 73 74 6f   PRAGMA temp_sto
106e0 72 65 5f 64 69 72 65 63 74 6f 72 79 20 2a 2f 0a  re_directory */.
106f0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
10700 43 43 45 53 53 5f 52 45 41 44 20 20 20 20 20 20  CCESS_READ      
10710 32 20 20 20 2f 2a 20 55 6e 75 73 65 64 20 2a 2f  2   /* Unused */
10720 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
10730 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20  : Flags for the 
10740 78 53 68 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74  xShmLock VFS met
10750 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  hod.**.** These 
10760 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74  integer constant
10770 73 20 64 65 66 69 6e 65 20 74 68 65 20 76 61 72  s define the var
10780 69 6f 75 73 20 6c 6f 63 6b 69 6e 67 20 6f 70 65  ious locking ope
10790 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77  rations.** allow
107a0 65 64 20 62 79 20 74 68 65 20 78 53 68 6d 4c 6f  ed by the xShmLo
107b0 63 6b 20 6d 65 74 68 6f 64 20 6f 66 20 5b 73 71  ck method of [sq
107c0 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
107d0 5d 2e 20 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f  ].  The.** follo
107e0 77 69 6e 67 20 61 72 65 20 74 68 65 20 6f 6e 6c  wing are the onl
107f0 79 20 6c 65 67 61 6c 20 63 6f 6d 62 69 6e 61 74  y legal combinat
10800 69 6f 6e 73 20 6f 66 20 66 6c 61 67 73 20 74 6f  ions of flags to
10810 20 74 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b   the.** xShmLock
10820 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c   method:.**.** <
10830 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  ul>.** <li>  SQL
10840 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53  ITE_SHM_LOCK | S
10850 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44  QLITE_SHM_SHARED
10860 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
10870 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49  _SHM_LOCK | SQLI
10880 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45  TE_SHM_EXCLUSIVE
10890 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
108a0 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51  _SHM_UNLOCK | SQ
108b0 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a  LITE_SHM_SHARED.
108c0 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f  ** <li>  SQLITE_
108d0 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c  SHM_UNLOCK | SQL
108e0 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56  ITE_SHM_EXCLUSIV
108f0 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  E.** </ul>.**.**
10900 20 57 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c   When unlocking,
10910 20 74 68 65 20 73 61 6d 65 20 53 48 41 52 45 44   the same SHARED
10920 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 66 6c   or EXCLUSIVE fl
10930 61 67 20 6d 75 73 74 20 62 65 20 73 75 70 70 6c  ag must be suppl
10940 69 65 64 20 61 73 0a 2a 2a 20 77 61 73 20 67 69  ied as.** was gi
10950 76 65 6e 20 6e 6f 20 74 68 65 20 63 6f 72 72 65  ven no the corre
10960 73 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20 20  sponding lock.  
10970 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c  .**.** The xShmL
10980 6f 63 6b 20 6d 65 74 68 6f 64 20 63 61 6e 20 74  ock method can t
10990 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65  ransition betwee
109a0 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 53  n unlocked and S
109b0 48 41 52 45 44 20 6f 72 0a 2a 2a 20 62 65 74 77  HARED or.** betw
109c0 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64  een unlocked and
109d0 20 45 58 43 4c 55 53 49 56 45 2e 20 20 49 74 20   EXCLUSIVE.  It 
109e0 63 61 6e 6e 6f 74 20 74 72 61 6e 73 69 74 69 6f  cannot transitio
109f0 6e 20 62 65 74 77 65 65 6e 20 53 48 41 52 45 44  n between SHARED
10a00 0a 2a 2a 20 61 6e 64 20 45 58 43 4c 55 53 49 56  .** and EXCLUSIV
10a10 45 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  E..*/.#define SQ
10a20 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20  LITE_SHM_UNLOCK 
10a30 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
10a40 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20  SQLITE_SHM_LOCK 
10a50 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e          2.#defin
10a60 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41  e SQLITE_SHM_SHA
10a70 52 45 44 20 20 20 20 20 20 20 34 0a 23 64 65 66  RED       4.#def
10a80 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45  ine SQLITE_SHM_E
10a90 58 43 4c 55 53 49 56 45 20 20 20 20 38 0a 0a 2f  XCLUSIVE    8../
10aa0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
10ab0 61 78 69 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b 20  aximum xShmLock 
10ac0 69 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20  index.**.** The 
10ad0 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20  xShmLock method 
10ae0 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  on [sqlite3_io_m
10af0 65 74 68 6f 64 73 5d 20 6d 61 79 20 75 73 65 20  ethods] may use 
10b00 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65  values.** betwee
10b10 6e 20 30 20 61 6e 64 20 74 68 69 73 20 75 70 70  n 0 and this upp
10b20 65 72 20 62 6f 75 6e 64 20 61 73 20 69 74 73 20  er bound as its 
10b30 22 6f 66 66 73 65 74 22 20 61 72 67 75 6d 65 6e  "offset" argumen
10b40 74 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65  t..** The SQLite
10b50 20 63 6f 72 65 20 77 69 6c 6c 20 6e 65 76 65 72   core will never
10b60 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63 71 75   attempt to acqu
10b70 69 72 65 20 6f 72 20 72 65 6c 65 61 73 65 20 61  ire or release a
10b80 0a 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73 69 64 65  .** lock outside
10b90 20 6f 66 20 74 68 69 73 20 72 61 6e 67 65 0a 2a   of this range.*
10ba0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
10bb0 5f 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20 20  _SHM_NLOCK      
10bc0 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49    8.../*.** CAPI
10bd0 33 52 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65  3REF: Initialize
10be0 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72   The SQLite Libr
10bf0 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ary.**.** ^The s
10c00 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
10c10 65 28 29 20 72 6f 75 74 69 6e 65 20 69 6e 69 74  e() routine init
10c20 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53  ializes the.** S
10c30 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20  QLite library.  
10c40 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75  ^The sqlite3_shu
10c50 74 64 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a  tdown() routine.
10c60 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61  ** deallocates a
10c70 6e 79 20 72 65 73 6f 75 72 63 65 73 20 74 68 61  ny resources tha
10c80 74 20 77 65 72 65 20 61 6c 6c 6f 63 61 74 65 64  t were allocated
10c90 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   by sqlite3_init
10ca0 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65  ialize()..** The
10cb0 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
10cc0 64 65 73 69 67 6e 65 64 20 74 6f 20 61 69 64 20  designed to aid 
10cd0 69 6e 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69  in process initi
10ce0 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a  alization and.**
10cf0 20 73 68 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62   shutdown on emb
10d00 65 64 64 65 64 20 73 79 73 74 65 6d 73 2e 20 20  edded systems.  
10d10 57 6f 72 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c  Workstation appl
10d20 69 63 61 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a  ications using.*
10d30 2a 20 53 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c  * SQLite normall
10d40 79 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f  y do not need to
10d50 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 6f   invoke either o
10d60 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
10d70 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74  ..**.** A call t
10d80 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  o sqlite3_initia
10d90 6c 69 7a 65 28 29 20 69 73 20 61 6e 20 22 65 66  lize() is an "ef
10da0 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66  fective" call if
10db0 20 69 74 20 69 73 0a 2a 2a 20 74 68 65 20 66 69   it is.** the fi
10dc0 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33  rst time sqlite3
10dd0 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
10de0 20 69 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67 20   invoked during 
10df0 74 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a  the lifetime of.
10e00 2a 2a 20 74 68 65 20 70 72 6f 63 65 73 73 2c 20  ** the process, 
10e10 6f 72 20 69 66 20 69 74 20 69 73 20 74 68 65 20  or if it is the 
10e20 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74  first time sqlit
10e30 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
10e40 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f  is invoked.** fo
10e50 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 74  llowing a call t
10e60 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
10e70 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e  wn().  ^(Only an
10e80 20 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 0a   effective call.
10e90 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e  ** of sqlite3_in
10ea0 69 74 69 61 6c 69 7a 65 28 29 20 64 6f 65 73 20  itialize() does 
10eb0 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  any initializati
10ec0 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 63  on.  All other c
10ed0 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d  alls.** are harm
10ee0 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a  less no-ops.)^.*
10ef0 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73  *.** A call to s
10f00 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
10f10 29 20 69 73 20 61 6e 20 22 65 66 66 65 63 74 69  ) is an "effecti
10f20 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69  ve" call if it i
10f30 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 63  s the first.** c
10f40 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
10f50 68 75 74 64 6f 77 6e 28 29 20 73 69 6e 63 65 20  hutdown() since 
10f60 74 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33  the last sqlite3
10f70 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20 20  _initialize().  
10f80 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66  ^(Only.** an eff
10f90 65 63 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 73  ective call to s
10fa0 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
10fb0 29 20 64 6f 65 73 20 61 6e 79 20 64 65 69 6e 69  ) does any deini
10fc0 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20  tialization..** 
10fd0 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 69 64 20  All other valid 
10fe0 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
10ff0 5f 73 68 75 74 64 6f 77 6e 28 29 20 61 72 65 20  _shutdown() are 
11000 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e  harmless no-ops.
11010 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  )^.**.** The sql
11020 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
11030 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74  ) interface is t
11040 68 72 65 61 64 73 61 66 65 2c 20 62 75 74 20 73  hreadsafe, but s
11050 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
11060 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68  ).** is not.  Th
11070 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  e sqlite3_shutdo
11080 77 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d  wn() interface m
11090 75 73 74 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c  ust only be call
110a0 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e  ed from a.** sin
110b0 67 6c 65 20 74 68 72 65 61 64 2e 20 20 41 6c 6c  gle thread.  All
110c0 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20   open [database 
110d0 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73  connections] mus
110e0 74 20 62 65 20 63 6c 6f 73 65 64 20 61 6e 64 20  t be closed and 
110f0 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c  all.** other SQL
11100 69 74 65 20 72 65 73 6f 75 72 63 65 73 20 6d 75  ite resources mu
11110 73 74 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65  st be deallocate
11120 64 20 70 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b  d prior to invok
11130 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  ing.** sqlite3_s
11140 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a  hutdown()..**.**
11150 20 41 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68 69   Among other thi
11160 6e 67 73 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e  ngs, ^sqlite3_in
11170 69 74 69 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20  itialize() will 
11180 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65  invoke.** sqlite
11190 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53 69  3_os_init().  Si
111a0 6d 69 6c 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65  milarly, ^sqlite
111b0 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20  3_shutdown().** 
111c0 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69  will invoke sqli
111d0 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a  te3_os_end()..**
111e0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
111f0 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f  _initialize() ro
11200 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53  utine returns [S
11210 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63  QLITE_OK] on suc
11220 63 65 73 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72  cess..** ^If for
11230 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71   some reason, sq
11240 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
11250 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  () is unable to 
11260 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68  initialize.** th
11270 65 20 6c 69 62 72 61 72 79 20 28 70 65 72 68 61  e library (perha
11280 70 73 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20  ps it is unable 
11290 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65  to allocate a ne
112a0 65 64 65 64 20 72 65 73 6f 75 72 63 65 20 73 75  eded resource su
112b0 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65 78  ch.** as a mutex
112c0 29 20 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20  ) it returns an 
112d0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68  [error code] oth
112e0 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
112f0 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  OK]..**.** ^The 
11300 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
11310 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20  ze() routine is 
11320 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c  called internall
11330 79 20 62 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a  y by many other.
11340 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  ** SQLite interf
11350 61 63 65 73 20 73 6f 20 74 68 61 74 20 61 6e 20  aces so that an 
11360 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 75 61  application usua
11370 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65  lly does not nee
11380 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73  d to.** invoke s
11390 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
113a0 65 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 46  e() directly.  F
113b0 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c  or example, [sql
113c0 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20  ite3_open()].** 
113d0 63 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e  calls sqlite3_in
113e0 69 74 69 61 6c 69 7a 65 28 29 20 73 6f 20 74 68  itialize() so th
113f0 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  e SQLite library
11400 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74   will be automat
11410 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61  ically.** initia
11420 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c 69  lized when [sqli
11430 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63  te3_open()] is c
11440 61 6c 6c 65 64 20 69 66 20 69 74 20 68 61 73 20  alled if it has 
11450 6e 6f 74 20 62 65 20 69 6e 69 74 69 61 6c 69 7a  not be initializ
11460 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20  ed.** already.  
11470 5e 48 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c  ^However, if SQL
11480 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
11490 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45  with the [SQLITE
114a0 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a  _OMIT_AUTOINIT].
114b0 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  ** compile-time 
114c0 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65  option, then the
114d0 20 61 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73   automatic calls
114e0 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   to sqlite3_init
114f0 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20  ialize().** are 
11500 6f 6d 69 74 74 65 64 20 61 6e 64 20 74 68 65 20  omitted and the 
11510 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
11520 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e   call sqlite3_in
11530 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63  itialize() direc
11540 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20  tly.** prior to 
11550 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20  using any other 
11560 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
11570 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70  .  For maximum p
11580 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69  ortability,.** i
11590 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  t is recommended
115a0 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f   that applicatio
115b0 6e 73 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65  ns always invoke
115c0 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
115d0 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c  ize().** directl
115e0 79 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67  y prior to using
115f0 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74   any other SQLit
11600 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46 75  e interface.  Fu
11610 74 75 72 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a  ture releases.**
11620 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 72   of SQLite may r
11630 65 71 75 69 72 65 20 74 68 69 73 2e 20 20 49 6e  equire this.  In
11640 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
11650 65 20 62 65 68 61 76 69 6f 72 20 65 78 68 69 62  e behavior exhib
11660 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c  ited.** when SQL
11670 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
11680 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49  with [SQLITE_OMI
11690 54 5f 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68  T_AUTOINIT] migh
116a0 74 20 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20  t become the.** 
116b0 64 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72  default behavior
116c0 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20   in some future 
116d0 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74  release of SQLit
116e0 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  e..**.** The sql
116f0 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72  ite3_os_init() r
11700 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f 70 65 72  outine does oper
11710 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65  ating-system spe
11720 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c  cific.** initial
11730 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 53  ization of the S
11740 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20  QLite library.  
11750 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  The sqlite3_os_e
11760 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  nd().** routine 
11770 75 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65 63  undoes the effec
11780 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f  t of sqlite3_os_
11790 69 6e 69 74 28 29 2e 20 20 54 79 70 69 63 61 6c  init().  Typical
117a0 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72   tasks.** perfor
117b0 6d 65 64 20 62 79 20 74 68 65 73 65 20 72 6f 75  med by these rou
117c0 74 69 6e 65 73 20 69 6e 63 6c 75 64 65 20 61 6c  tines include al
117d0 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c  location or deal
117e0 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73  location.** of s
117f0 74 61 74 69 63 20 72 65 73 6f 75 72 63 65 73 2c  tatic resources,
11800 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
11810 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62  of global variab
11820 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20  les,.** setting 
11830 75 70 20 61 20 64 65 66 61 75 6c 74 20 5b 73 71  up a default [sq
11840 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c  lite3_vfs] modul
11850 65 2c 20 6f 72 20 73 65 74 74 69 6e 67 20 75 70  e, or setting up
11860 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74 20 63 6f  .** a default co
11870 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 73 69 6e  nfiguration usin
11880 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  g [sqlite3_confi
11890 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  g()]..**.** The 
118a0 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
118b0 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20  ld never invoke 
118c0 65 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f 6f  either sqlite3_o
118d0 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73  s_init().** or s
118e0 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20  qlite3_os_end() 
118f0 64 69 72 65 63 74 6c 79 2e 20 20 54 68 65 20 61  directly.  The a
11900 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
11910 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a  d only invoke.**
11920 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
11930 69 7a 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ize() and sqlite
11940 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 54  3_shutdown().  T
11950 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  he sqlite3_os_in
11960 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  it().** interfac
11970 65 20 69 73 20 63 61 6c 6c 65 64 20 61 75 74 6f  e is called auto
11980 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c  matically by sql
11990 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
119a0 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ) and.** sqlite3
119b0 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20 63 61 6c  _os_end() is cal
119c0 6c 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73  led by sqlite3_s
119d0 68 75 74 64 6f 77 6e 28 29 2e 20 20 41 70 70 72  hutdown().  Appr
119e0 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65  opriate.** imple
119f0 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 73  mentations for s
11a00 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
11a10 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f   and sqlite3_os_
11a20 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20 62 75 69  end().** are bui
11a30 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 77  lt into SQLite w
11a40 68 65 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c  hen it is compil
11a50 65 64 20 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e  ed for Unix, Win
11a60 64 6f 77 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a  dows, or OS/2..*
11a70 2a 20 57 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62  * When [custom b
11a80 75 69 6c 64 73 20 7c 20 62 75 69 6c 74 20 66 6f  uilds | built fo
11a90 72 20 6f 74 68 65 72 20 70 6c 61 74 66 6f 72 6d  r other platform
11aa0 73 5d 0a 2a 2a 20 28 75 73 69 6e 67 20 74 68 65  s].** (using the
11ab0 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45   [SQLITE_OS_OTHE
11ac0 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  R=1] compile-tim
11ad0 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65  e.** option) the
11ae0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
11af0 74 20 73 75 70 70 6c 79 20 61 20 73 75 69 74 61  t supply a suita
11b00 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ble implementati
11b10 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  on for.** sqlite
11b20 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20  3_os_init() and 
11b30 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
11b40 2e 20 20 41 6e 20 61 70 70 6c 69 63 61 74 69 6f  .  An applicatio
11b50 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d  n-supplied.** im
11b60 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
11b70 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
11b80 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f  ) or sqlite3_os_
11b90 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65  end().** must re
11ba0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
11bb0 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20   on success and 
11bc0 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65 72 72 6f  some other [erro
11bd0 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20  r code] upon.** 
11be0 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 53 51 4c 49  failure..*/.SQLI
11bf0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
11c00 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 76 6f  e3_initialize(vo
11c10 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  id);.SQLITE_API 
11c20 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74  int sqlite3_shut
11c30 64 6f 77 6e 28 76 6f 69 64 29 3b 0a 53 51 4c 49  down(void);.SQLI
11c40 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
11c50 65 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29  e3_os_init(void)
11c60 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
11c70 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
11c80 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  void);../*.** CA
11c90 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72  PI3REF: Configur
11ca0 69 6e 67 20 54 68 65 20 53 51 4c 69 74 65 20 4c  ing The SQLite L
11cb0 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65  ibrary.**.** The
11cc0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
11cd0 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75  ) interface is u
11ce0 73 65 64 20 74 6f 20 6d 61 6b 65 20 67 6c 6f 62  sed to make glob
11cf0 61 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  al configuration
11d00 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 53  .** changes to S
11d10 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74  QLite in order t
11d20 6f 20 74 75 6e 65 20 53 51 4c 69 74 65 20 74 6f  o tune SQLite to
11d30 20 74 68 65 20 73 70 65 63 69 66 69 63 20 6e 65   the specific ne
11d40 65 64 73 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70  eds of.** the ap
11d50 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68 65 20  plication.  The 
11d60 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72  default configur
11d70 61 74 69 6f 6e 20 69 73 20 72 65 63 6f 6d 6d 65  ation is recomme
11d80 6e 64 65 64 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a  nded for most.**
11d90 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6e   applications an
11da0 64 20 73 6f 20 74 68 69 73 20 72 6f 75 74 69 6e  d so this routin
11db0 65 20 69 73 20 75 73 75 61 6c 6c 79 20 6e 6f 74  e is usually not
11dc0 20 6e 65 63 65 73 73 61 72 79 2e 20 20 49 74 20   necessary.  It 
11dd0 69 73 0a 2a 2a 20 70 72 6f 76 69 64 65 64 20 74  is.** provided t
11de0 6f 20 73 75 70 70 6f 72 74 20 72 61 72 65 20 61  o support rare a
11df0 70 70 6c 69 63 61 74 69 6f 6e 73 20 77 69 74 68  pplications with
11e00 20 75 6e 75 73 75 61 6c 20 6e 65 65 64 73 2e 0a   unusual needs..
11e10 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
11e20 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72  3_config() inter
11e30 66 61 63 65 20 69 73 20 6e 6f 74 20 74 68 72 65  face is not thre
11e40 61 64 73 61 66 65 2e 20 20 54 68 65 20 61 70 70  adsafe.  The app
11e50 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74  lication.** must
11e60 20 69 6e 73 75 72 65 20 74 68 61 74 20 6e 6f 20   insure that no 
11e70 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74  other SQLite int
11e80 65 72 66 61 63 65 73 20 61 72 65 20 69 6e 76 6f  erfaces are invo
11e90 6b 65 64 20 62 79 20 6f 74 68 65 72 0a 2a 2a 20  ked by other.** 
11ea0 74 68 72 65 61 64 73 20 77 68 69 6c 65 20 73 71  threads while sq
11eb0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
11ec0 73 20 72 75 6e 6e 69 6e 67 2e 20 20 46 75 72 74  s running.  Furt
11ed0 68 65 72 6d 6f 72 65 2c 20 73 71 6c 69 74 65 33  hermore, sqlite3
11ee0 5f 63 6f 6e 66 69 67 28 29 0a 2a 2a 20 6d 61 79  _config().** may
11ef0 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64   only be invoked
11f00 20 70 72 69 6f 72 20 74 6f 20 6c 69 62 72 61 72   prior to librar
11f10 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  y initialization
11f20 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
11f30 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d  e3_initialize()]
11f40 20 6f 72 20 61 66 74 65 72 20 73 68 75 74 64 6f   or after shutdo
11f50 77 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73  wn by [sqlite3_s
11f60 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e  hutdown()]..** ^
11f70 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  If sqlite3_confi
11f80 67 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 66  g() is called af
11f90 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69  ter [sqlite3_ini
11fa0 74 69 61 6c 69 7a 65 28 29 5d 20 61 6e 64 20 62  tialize()] and b
11fb0 65 66 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  efore.** [sqlite
11fc0 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 74 68  3_shutdown()] th
11fd0 65 6e 20 69 74 20 77 69 6c 6c 20 72 65 74 75 72  en it will retur
11fe0 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e  n SQLITE_MISUSE.
11ff0 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65  .** Note, howeve
12000 72 2c 20 74 68 61 74 20 5e 73 71 6c 69 74 65 33  r, that ^sqlite3
12010 5f 63 6f 6e 66 69 67 28 29 20 63 61 6e 20 62 65  _config() can be
12020 20 63 61 6c 6c 65 64 20 61 73 20 70 61 72 74 20   called as part 
12030 6f 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d  of the.** implem
12040 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61  entation of an a
12050 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
12060 65 64 20 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69  ed [sqlite3_os_i
12070 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  nit()]..**.** Th
12080 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
12090 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66   to sqlite3_conf
120a0 69 67 28 29 20 69 73 20 61 6e 20 69 6e 74 65 67  ig() is an integ
120b0 65 72 0a 2a 2a 20 5b 63 6f 6e 66 69 67 75 72 61  er.** [configura
120c0 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74 68 61  tion option] tha
120d0 74 20 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20  t determines.** 
120e0 77 68 61 74 20 70 72 6f 70 65 72 74 79 20 6f 66  what property of
120f0 20 53 51 4c 69 74 65 20 69 73 20 74 6f 20 62 65   SQLite is to be
12100 20 63 6f 6e 66 69 67 75 72 65 64 2e 20 20 53 75   configured.  Su
12110 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e  bsequent argumen
12120 74 73 0a 2a 2a 20 76 61 72 79 20 64 65 70 65 6e  ts.** vary depen
12130 64 69 6e 67 20 6f 6e 20 74 68 65 20 5b 63 6f 6e  ding on the [con
12140 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
12150 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 72  n].** in the fir
12160 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  st argument..**.
12170 2a 2a 20 5e 57 68 65 6e 20 61 20 63 6f 6e 66 69  ** ^When a confi
12180 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
12190 69 73 20 73 65 74 2c 20 73 71 6c 69 74 65 33 5f  is set, sqlite3_
121a0 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e 73  config() returns
121b0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a   [SQLITE_OK]..**
121c0 20 5e 49 66 20 74 68 65 20 6f 70 74 69 6f 6e 20   ^If the option 
121d0 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51  is unknown or SQ
121e0 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74  Lite is unable t
121f0 6f 20 73 65 74 20 74 68 65 20 6f 70 74 69 6f 6e  o set the option
12200 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 72 6f  .** then this ro
12210 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20  utine returns a 
12220 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20  non-zero [error 
12230 63 6f 64 65 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45  code]..*/.SQLITE
12240 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
12250 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20 2e 2e 2e  _config(int, ...
12260 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
12270 45 46 3a 20 43 6f 6e 66 69 67 75 72 65 20 64 61  EF: Configure da
12280 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
12290 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  ns.**.** The sql
122a0 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
122b0 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73   interface is us
122c0 65 64 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 69  ed to make confi
122d0 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e  guration.** chan
122e0 67 65 73 20 74 6f 20 61 20 5b 64 61 74 61 62 61  ges to a [databa
122f0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20  se connection]. 
12300 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 69   The interface i
12310 73 20 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20  s similar to.** 
12320 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
12330 29 5d 20 65 78 63 65 70 74 20 74 68 61 74 20 74  )] except that t
12340 68 65 20 63 68 61 6e 67 65 73 20 61 70 70 6c 79  he changes apply
12350 20 74 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20   to a single.** 
12360 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
12370 74 69 6f 6e 5d 20 28 73 70 65 63 69 66 69 65 64  tion] (specified
12380 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
12390 67 75 6d 65 6e 74 29 2e 0a 2a 2a 0a 2a 2a 20 54  gument)..**.** T
123a0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
123b0 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62  nt to sqlite3_db
123c0 5f 63 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e 29  _config(D,V,...)
123d0 20 20 69 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c    is the.** [SQL
123e0 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
123f0 4b 41 53 49 44 45 20 7c 20 63 6f 6e 66 69 67 75  KASIDE | configu
12400 72 61 74 69 6f 6e 20 76 65 72 62 5d 20 2d 20 61  ration verb] - a
12410 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 0a  n integer code .
12420 2a 2a 20 74 68 61 74 20 69 6e 64 69 63 61 74 65  ** that indicate
12430 73 20 77 68 61 74 20 61 73 70 65 63 74 20 6f 66  s what aspect of
12440 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
12450 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65  onnection] is be
12460 69 6e 67 20 63 6f 6e 66 69 67 75 72 65 64 2e 0a  ing configured..
12470 2a 2a 20 53 75 62 73 65 71 75 65 6e 74 20 61 72  ** Subsequent ar
12480 67 75 6d 65 6e 74 73 20 76 61 72 79 20 64 65 70  guments vary dep
12490 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f  ending on the co
124a0 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62  nfiguration verb
124b0 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74  ..**.** ^Calls t
124c0 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e  o sqlite3_db_con
124d0 66 69 67 28 29 20 72 65 74 75 72 6e 20 53 51 4c  fig() return SQL
124e0 49 54 45 5f 4f 4b 20 69 66 20 61 6e 64 20 6f 6e  ITE_OK if and on
124f0 6c 79 20 69 66 0a 2a 2a 20 74 68 65 20 63 61 6c  ly if.** the cal
12500 6c 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20  l is considered 
12510 73 75 63 63 65 73 73 66 75 6c 2e 0a 2a 2f 0a 53  successful..*/.S
12520 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
12530 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
12540 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 70  sqlite3*, int op
12550 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  , ...);../*.** C
12560 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20  API3REF: Memory 
12570 41 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f 75 74 69  Allocation Routi
12580 6e 65 73 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73  nes.**.** An ins
12590 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
125a0 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65  ject defines the
125b0 20 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 65   interface betwe
125c0 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64  en SQLite.** and
125d0 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72   low-level memor
125e0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75  y allocation rou
125f0 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  tines..**.** Thi
12600 73 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64  s object is used
12610 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61   in only one pla
12620 63 65 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65  ce in the SQLite
12630 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41   interface..** A
12640 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
12650 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
12660 6f 62 6a 65 63 74 20 69 73 20 74 68 65 20 61 72  object is the ar
12670 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71  gument to.** [sq
12680 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
12690 77 68 65 6e 20 74 68 65 20 63 6f 6e 66 69 67 75  when the configu
126a0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73  ration option is
126b0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  .** [SQLITE_CONF
126c0 49 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53  IG_MALLOC] or [S
126d0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
126e0 4d 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79  MALLOC].  .** By
126f0 20 63 72 65 61 74 69 6e 67 20 61 6e 20 69 6e 73   creating an ins
12700 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
12710 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 70 61 73 73  ject.** and pass
12720 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74  ing it to [sqlit
12730 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49  e3_config]([SQLI
12740 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
12750 5d 29 0a 2a 2a 20 64 75 72 69 6e 67 20 63 6f 6e  ]).** during con
12760 66 69 67 75 72 61 74 69 6f 6e 2c 20 61 6e 20 61  figuration, an a
12770 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 73  pplication can s
12780 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e  pecify an altern
12790 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20  ative.** memory 
127a0 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79  allocation subsy
127b0 73 74 65 6d 20 66 6f 72 20 53 51 4c 69 74 65 20  stem for SQLite 
127c0 74 6f 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f  to use for all o
127d0 66 20 69 74 73 0a 2a 2a 20 64 79 6e 61 6d 69 63  f its.** dynamic
127e0 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a 2a   memory needs..*
127f0 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53  *.** Note that S
12800 51 4c 69 74 65 20 63 6f 6d 65 73 20 77 69 74 68  QLite comes with
12810 20 73 65 76 65 72 61 6c 20 5b 62 75 69 6c 74 2d   several [built-
12820 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  in memory alloca
12830 74 6f 72 73 5d 0a 2a 2a 20 74 68 61 74 20 61 72  tors].** that ar
12840 65 20 70 65 72 66 65 63 74 6c 79 20 61 64 65 71  e perfectly adeq
12850 75 61 74 65 20 66 6f 72 20 74 68 65 20 6f 76 65  uate for the ove
12860 72 77 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69  rwhelming majori
12870 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f  ty of applicatio
12880 6e 73 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 74  ns.** and that t
12890 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 6f 6e  his object is on
128a0 6c 79 20 75 73 65 66 75 6c 20 74 6f 20 61 20 74  ly useful to a t
128b0 69 6e 79 20 6d 69 6e 6f 72 69 74 79 20 6f 66 20  iny minority of 
128c0 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20  applications.** 
128d0 77 69 74 68 20 73 70 65 63 69 61 6c 69 7a 65 64  with specialized
128e0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
128f0 6f 6e 20 72 65 71 75 69 72 65 6d 65 6e 74 73 2e  on requirements.
12900 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73    This object is
12910 0a 2a 2a 20 61 6c 73 6f 20 75 73 65 64 20 64 75  .** also used du
12920 72 69 6e 67 20 74 65 73 74 69 6e 67 20 6f 66 20  ring testing of 
12930 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20  SQLite in order 
12940 74 6f 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c  to specify an al
12950 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d  ternative.** mem
12960 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68  ory allocator th
12970 61 74 20 73 69 6d 75 6c 61 74 65 73 20 6d 65 6d  at simulates mem
12980 6f 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72  ory out-of-memor
12990 79 20 63 6f 6e 64 69 74 69 6f 6e 73 20 69 6e 0a  y conditions in.
129a0 2a 2a 20 6f 72 64 65 72 20 74 6f 20 76 65 72 69  ** order to veri
129b0 66 79 20 74 68 61 74 20 53 51 4c 69 74 65 20 72  fy that SQLite r
129c0 65 63 6f 76 65 72 73 20 67 72 61 63 65 66 75 6c  ecovers graceful
129d0 6c 79 20 66 72 6f 6d 20 73 75 63 68 0a 2a 2a 20  ly from such.** 
129e0 63 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a  conditions..**.*
129f0 2a 20 54 68 65 20 78 4d 61 6c 6c 6f 63 2c 20 78  * The xMalloc, x
12a00 52 65 61 6c 6c 6f 63 2c 20 61 6e 64 20 78 46 72  Realloc, and xFr
12a10 65 65 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20  ee methods must 
12a20 77 6f 72 6b 20 6c 69 6b 65 20 74 68 65 0a 2a 2a  work like the.**
12a30 20 6d 61 6c 6c 6f 63 28 29 2c 20 72 65 61 6c 6c   malloc(), reall
12a40 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20  oc() and free() 
12a50 66 75 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74  functions from t
12a60 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  he standard C li
12a70 62 72 61 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74  brary..** ^SQLit
12a80 65 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61  e guarantees tha
12a90 74 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  t the second arg
12aa0 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78 52 65 61  ument to.** xRea
12ab0 6c 6c 6f 63 20 69 73 20 61 6c 77 61 79 73 20 61  lloc is always a
12ac0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
12ad0 62 79 20 61 20 70 72 69 6f 72 20 63 61 6c 6c 20  by a prior call 
12ae0 74 6f 20 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a 0a  to xRoundup..**.
12af0 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75 6c 64 20  ** xSize should 
12b00 72 65 74 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63  return the alloc
12b10 61 74 65 64 20 73 69 7a 65 20 6f 66 20 61 20 6d  ated size of a m
12b20 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
12b30 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 6f  .** previously o
12b40 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61  btained from xMa
12b50 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63  lloc or xRealloc
12b60 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61 74 65 64  .  The allocated
12b70 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61   size.** is alwa
12b80 79 73 20 61 74 20 6c 65 61 73 74 20 61 73 20 62  ys at least as b
12b90 69 67 20 61 73 20 74 68 65 20 72 65 71 75 65 73  ig as the reques
12ba0 74 65 64 20 73 69 7a 65 20 62 75 74 20 6d 61 79  ted size but may
12bb0 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a   be larger..**.*
12bc0 2a 20 54 68 65 20 78 52 6f 75 6e 64 75 70 20 6d  * The xRoundup m
12bd0 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 77 68  ethod returns wh
12be0 61 74 20 77 6f 75 6c 64 20 62 65 20 74 68 65 20  at would be the 
12bf0 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f  allocated size o
12c00 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c  f.** a memory al
12c10 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65 6e 20 61  location given a
12c20 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 71 75   particular requ
12c30 65 73 74 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73  ested size.  Mos
12c40 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f  t memory.** allo
12c50 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20  cators round up 
12c60 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
12c70 6e 73 20 61 74 20 6c 65 61 73 74 20 74 6f 20 74  ns at least to t
12c80 68 65 20 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65  he next multiple
12c90 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20  .** of 8.  Some 
12ca0 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64  allocators round
12cb0 20 75 70 20 74 6f 20 61 20 6c 61 72 67 65 72 20   up to a larger 
12cc0 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74 6f 20 61  multiple or to a
12cd0 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 20   power of 2..** 
12ce0 45 76 65 72 79 20 6d 65 6d 6f 72 79 20 61 6c 6c  Every memory all
12cf0 6f 63 61 74 69 6f 6e 20 72 65 71 75 65 73 74 20  ocation request 
12d00 63 6f 6d 69 6e 67 20 69 6e 20 74 68 72 6f 75 67  coming in throug
12d10 68 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  h [sqlite3_mallo
12d20 63 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69  c()].** or [sqli
12d30 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 66  te3_realloc()] f
12d40 69 72 73 74 20 63 61 6c 6c 73 20 78 52 6f 75 6e  irst calls xRoun
12d50 64 75 70 2e 20 20 49 66 20 78 52 6f 75 6e 64 75  dup.  If xRoundu
12d60 70 20 72 65 74 75 72 6e 73 20 30 2c 20 0a 2a 2a  p returns 0, .**
12d70 20 74 68 61 74 20 63 61 75 73 65 73 20 74 68 65   that causes the
12d80 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6d   corresponding m
12d90 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
12da0 20 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20   to fail..**.** 
12db0 54 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64  The xInit method
12dc0 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65   initializes the
12dd0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
12de0 72 2e 20 20 28 46 6f 72 20 65 78 61 6d 70 6c 65  r.  (For example
12df0 2c 0a 2a 2a 20 69 74 20 6d 69 67 68 74 20 61 6c  ,.** it might al
12e00 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 71 75 69  locate any requi
12e10 72 65 20 6d 75 74 65 78 65 73 20 6f 72 20 69 6e  re mutexes or in
12e20 69 74 69 61 6c 69 7a 65 20 69 6e 74 65 72 6e 61  itialize interna
12e30 6c 20 64 61 74 61 0a 2a 2a 20 73 74 72 75 63 74  l data.** struct
12e40 75 72 65 73 2e 20 20 54 68 65 20 78 53 68 75 74  ures.  The xShut
12e50 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 69  down method is i
12e60 6e 76 6f 6b 65 64 20 28 69 6e 64 69 72 65 63 74  nvoked (indirect
12e70 6c 79 29 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74  ly) by.** [sqlit
12e80 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 61  e3_shutdown()] a
12e90 6e 64 20 73 68 6f 75 6c 64 20 64 65 61 6c 6c 6f  nd should deallo
12ea0 63 61 74 65 20 61 6e 79 20 72 65 73 6f 75 72 63  cate any resourc
12eb0 65 73 20 61 63 71 75 69 72 65 64 0a 2a 2a 20 62  es acquired.** b
12ec0 79 20 78 49 6e 69 74 2e 20 20 54 68 65 20 70 41  y xInit.  The pA
12ed0 70 70 44 61 74 61 20 70 6f 69 6e 74 65 72 20 69  ppData pointer i
12ee0 73 20 75 73 65 64 20 61 73 20 74 68 65 20 6f 6e  s used as the on
12ef0 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  ly parameter to.
12f00 2a 2a 20 78 49 6e 69 74 20 61 6e 64 20 78 53 68  ** xInit and xSh
12f10 75 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51  utdown..**.** SQ
12f20 4c 69 74 65 20 68 6f 6c 64 73 20 74 68 65 20 5b  Lite holds the [
12f30 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41  SQLITE_MUTEX_STA
12f40 54 49 43 5f 4d 41 53 54 45 52 5d 20 6d 75 74 65  TIC_MASTER] mute
12f50 78 20 77 68 65 6e 20 69 74 20 69 6e 76 6f 6b 65  x when it invoke
12f60 73 0a 2a 2a 20 74 68 65 20 78 49 6e 69 74 20 6d  s.** the xInit m
12f70 65 74 68 6f 64 2c 20 73 6f 20 74 68 65 20 78 49  ethod, so the xI
12f80 6e 69 74 20 6d 65 74 68 6f 64 20 6e 65 65 64 20  nit method need 
12f90 6e 6f 74 20 62 65 20 74 68 72 65 61 64 73 61 66  not be threadsaf
12fa0 65 2e 20 20 54 68 65 0a 2a 2a 20 78 53 68 75 74  e.  The.** xShut
12fb0 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 6f  down method is o
12fc0 6e 6c 79 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20  nly called from 
12fd0 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77  [sqlite3_shutdow
12fe0 6e 28 29 5d 20 73 6f 20 69 74 20 64 6f 65 73 0a  n()] so it does.
12ff0 2a 2a 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62  ** not need to b
13000 65 20 74 68 72 65 61 64 73 61 66 65 20 65 69 74  e threadsafe eit
13010 68 65 72 2e 20 20 46 6f 72 20 61 6c 6c 20 6f 74  her.  For all ot
13020 68 65 72 20 6d 65 74 68 6f 64 73 2c 20 53 51 4c  her methods, SQL
13030 69 74 65 0a 2a 2a 20 68 6f 6c 64 73 20 74 68 65  ite.** holds the
13040 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53   [SQLITE_MUTEX_S
13050 54 41 54 49 43 5f 4d 45 4d 5d 20 6d 75 74 65 78  TATIC_MEM] mutex
13060 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 0a   as long as the.
13070 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ** [SQLITE_CONFI
13080 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 63 6f 6e  G_MEMSTATUS] con
13090 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
130a0 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 6e 20 28  n is turned on (
130b0 77 68 69 63 68 0a 2a 2a 20 69 74 20 69 73 20 62  which.** it is b
130c0 79 20 64 65 66 61 75 6c 74 29 20 61 6e 64 20 73  y default) and s
130d0 6f 20 74 68 65 20 6d 65 74 68 6f 64 73 20 61 72  o the methods ar
130e0 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  e automatically 
130f0 73 65 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48  serialized..** H
13100 6f 77 65 76 65 72 2c 20 69 66 20 5b 53 51 4c 49  owever, if [SQLI
13110 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41  TE_CONFIG_MEMSTA
13120 54 55 53 5d 20 69 73 20 64 69 73 61 62 6c 65 64  TUS] is disabled
13130 2c 20 74 68 65 6e 20 74 68 65 20 6f 74 68 65 72  , then the other
13140 0a 2a 2a 20 6d 65 74 68 6f 64 73 20 6d 75 73 74  .** methods must
13150 20 62 65 20 74 68 72 65 61 64 73 61 66 65 20 6f   be threadsafe o
13160 72 20 65 6c 73 65 20 6d 61 6b 65 20 74 68 65 69  r else make thei
13170 72 20 6f 77 6e 20 61 72 72 61 6e 67 65 6d 65 6e  r own arrangemen
13180 74 73 20 66 6f 72 0a 2a 2a 20 73 65 72 69 61 6c  ts for.** serial
13190 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53  ization..**.** S
131a0 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72  QLite will never
131b0 20 69 6e 76 6f 6b 65 20 78 49 6e 69 74 28 29 20   invoke xInit() 
131c0 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 20 77  more than once w
131d0 69 74 68 6f 75 74 20 61 6e 20 69 6e 74 65 72 76  ithout an interv
131e0 65 6e 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f  ening.** call to
131f0 20 78 53 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f   xShutdown()..*/
13200 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
13210 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
13220 6f 64 73 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  ods sqlite3_mem_
13230 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20  methods;.struct 
13240 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
13250 6f 64 73 20 7b 0a 20 20 76 6f 69 64 20 2a 28 2a  ods {.  void *(*
13260 78 4d 61 6c 6c 6f 63 29 28 69 6e 74 29 3b 20 20  xMalloc)(int);  
13270 20 20 20 20 20 20 20 2f 2a 20 4d 65 6d 6f 72 79         /* Memory
13280 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63   allocation func
13290 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28  tion */.  void (
132a0 2a 78 46 72 65 65 29 28 76 6f 69 64 2a 29 3b 20  *xFree)(void*); 
132b0 20 20 20 20 20 20 20 20 20 2f 2a 20 46 72 65 65           /* Free
132c0 20 61 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74   a prior allocat
132d0 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 28  ion */.  void *(
132e0 2a 78 52 65 61 6c 6c 6f 63 29 28 76 6f 69 64 2a  *xRealloc)(void*
132f0 2c 69 6e 74 29 3b 20 20 2f 2a 20 52 65 73 69 7a  ,int);  /* Resiz
13300 65 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  e an allocation 
13310 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 69 7a 65  */.  int (*xSize
13320 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20  )(void*);       
13330 20 20 20 20 2f 2a 20 52 65 74 75 72 6e 20 74 68      /* Return th
13340 65 20 73 69 7a 65 20 6f 66 20 61 6e 20 61 6c 6c  e size of an all
13350 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74  ocation */.  int
13360 20 28 2a 78 52 6f 75 6e 64 75 70 29 28 69 6e 74   (*xRoundup)(int
13370 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52  );          /* R
13380 6f 75 6e 64 20 75 70 20 72 65 71 75 65 73 74 20  ound up request 
13390 73 69 7a 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69  size to allocati
133a0 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20 20 69 6e 74  on size */.  int
133b0 20 28 2a 78 49 6e 69 74 29 28 76 6f 69 64 2a 29   (*xInit)(void*)
133c0 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 49  ;           /* I
133d0 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65  nitialize the me
133e0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a  mory allocator *
133f0 2f 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 75 74  /.  void (*xShut
13400 64 6f 77 6e 29 28 76 6f 69 64 2a 29 3b 20 20 20  down)(void*);   
13410 20 20 20 2f 2a 20 44 65 69 6e 69 74 69 61 6c 69     /* Deinitiali
13420 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c  ze the memory al
13430 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69  locator */.  voi
13440 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20  d *pAppData;    
13450 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41              /* A
13460 72 67 75 6d 65 6e 74 20 74 6f 20 78 49 6e 69 74  rgument to xInit
13470 28 29 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e  () and xShutdown
13480 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20  () */.};../*.** 
13490 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67  CAPI3REF: Config
134a0 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a  uration Options.
134b0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f  ** KEYWORDS: {co
134c0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
134d0 6f 6e 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  on}.**.** These 
134e0 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68  constants are th
134f0 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65  e available inte
13500 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ger configuratio
13510 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a  n options that.*
13520 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65 64 20  * can be passed 
13530 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67  as the first arg
13540 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71  ument to the [sq
13550 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
13560 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
13570 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69   New configurati
13580 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62  on options may b
13590 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
135a0 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51  e releases of SQ
135b0 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e  Lite..** Existin
135c0 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  g configuration 
135d0 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65  options might be
135e0 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20   discontinued.  
135f0 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20  Applications.** 
13600 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65  should check the
13610 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f   return code fro
13620 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  m [sqlite3_confi
13630 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72  g()] to make sur
13640 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61  e that.** the ca
13650 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 54 68 65 20  ll worked.  The 
13660 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
13670 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c  )] interface wil
13680 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f  l return a.** no
13690 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f  n-zero [error co
136a0 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74  de] if a discont
136b0 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f  inued or unsuppo
136c0 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69  rted configurati
136d0 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20  on option.** is 
136e0 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c  invoked..**.** <
136f0 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  dl>.** [[SQLITE_
13700 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52  CONFIG_SINGLETHR
13710 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  EAD]] <dt>SQLITE
13720 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
13730 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  READ</dt>.** <dd
13740 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72  >There are no ar
13750 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20  guments to this 
13760 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f  option.  ^This o
13770 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a  ption sets the.*
13780 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  * [threading mod
13790 65 5d 20 74 6f 20 53 69 6e 67 6c 65 2d 74 68 72  e] to Single-thr
137a0 65 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77  ead.  In other w
137b0 6f 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65  ords, it disable
137c0 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 69 6e  s.** all mutexin
137d0 67 20 61 6e 64 20 70 75 74 73 20 53 51 4c 69 74  g and puts SQLit
137e0 65 20 69 6e 74 6f 20 61 20 6d 6f 64 65 20 77 68  e into a mode wh
137f0 65 72 65 20 69 74 20 63 61 6e 20 6f 6e 6c 79 20  ere it can only 
13800 62 65 20 75 73 65 64 0a 2a 2a 20 62 79 20 61 20  be used.** by a 
13810 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20  single thread.  
13820 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63   ^If SQLite is c
13830 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
13840 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
13850 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f  ADSAFE | SQLITE_
13860 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f  THREADSAFE=0] co
13870 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
13880 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20  n then.** it is 
13890 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20  not possible to 
138a0 63 68 61 6e 67 65 20 74 68 65 20 5b 74 68 72 65  change the [thre
138b0 61 64 69 6e 67 20 6d 6f 64 65 5d 20 66 72 6f 6d  ading mode] from
138c0 20 69 74 73 20 64 65 66 61 75 6c 74 0a 2a 2a 20   its default.** 
138d0 76 61 6c 75 65 20 6f 66 20 53 69 6e 67 6c 65 2d  value of Single-
138e0 74 68 72 65 61 64 20 61 6e 64 20 73 6f 20 5b 73  thread and so [s
138f0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
13900 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 0a 2a 2a   will return .**
13910 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
13920 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74  if called with t
13930 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
13940 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 0a 2a 2a  _SINGLETHREAD.**
13950 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
13960 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ption.</dd>.**.*
13970 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
13980 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 5d 20  G_MULTITHREAD]] 
13990 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
139a0 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 3c 2f 64  G_MULTITHREAD</d
139b0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20  t>.** <dd>There 
139c0 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73  are no arguments
139d0 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e   to this option.
139e0 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73    ^This option s
139f0 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65  ets the.** [thre
13a00 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 4d  ading mode] to M
13a10 75 6c 74 69 2d 74 68 72 65 61 64 2e 20 20 49 6e  ulti-thread.  In
13a20 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74   other words, it
13a30 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75 74   disables.** mut
13a40 65 78 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62 61  exing on [databa
13a50 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61  se connection] a
13a60 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  nd [prepared sta
13a70 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e  tement] objects.
13a80 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
13a90 69 6f 6e 20 69 73 20 72 65 73 70 6f 6e 73 69 62  ion is responsib
13aa0 6c 65 20 66 6f 72 20 73 65 72 69 61 6c 69 7a 69  le for serializi
13ab0 6e 67 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a 20  ng access to.** 
13ac0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
13ad0 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70  tions] and [prep
13ae0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d  ared statements]
13af0 2e 20 20 42 75 74 20 6f 74 68 65 72 20 6d 75 74  .  But other mut
13b00 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62  exes.** are enab
13b10 6c 65 64 20 73 6f 20 74 68 61 74 20 53 51 4c 69  led so that SQLi
13b20 74 65 20 77 69 6c 6c 20 62 65 20 73 61 66 65 20  te will be safe 
13b30 74 6f 20 75 73 65 20 69 6e 20 61 20 6d 75 6c 74  to use in a mult
13b40 69 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 65 6e  i-threaded.** en
13b50 76 69 72 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e  vironment as lon
13b60 67 20 61 73 20 6e 6f 20 74 77 6f 20 74 68 72 65  g as no two thre
13b70 61 64 73 20 61 74 74 65 6d 70 74 20 74 6f 20 75  ads attempt to u
13b80 73 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 5b  se the same.** [
13b90 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
13ba0 69 6f 6e 5d 20 61 74 20 74 68 65 20 73 61 6d 65  ion] at the same
13bb0 20 74 69 6d 65 2e 20 20 5e 49 66 20 53 51 4c 69   time.  ^If SQLi
13bc0 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
13bd0 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49  ith.** the [SQLI
13be0 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20  TE_THREADSAFE | 
13bf0 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
13c00 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  E=0] compile-tim
13c10 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a  e option then.**
13c20 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69   it is not possi
13c30 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 4d  ble to set the M
13c40 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72  ulti-thread [thr
13c50 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64  eading mode] and
13c60 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
13c70 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75  fig()] will retu
13c80 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  rn [SQLITE_ERROR
13c90 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68  ] if called with
13ca0 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43   the.** SQLITE_C
13cb0 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
13cc0 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  D configuration 
13cd0 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a  option.</dd>.**.
13ce0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
13cf0 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 5d 5d 20  IG_SERIALIZED]] 
13d00 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
13d10 47 5f 53 45 52 49 41 4c 49 5a 45 44 3c 2f 64 74  G_SERIALIZED</dt
13d20 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61  >.** <dd>There a
13d30 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20  re no arguments 
13d40 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20  to this option. 
13d50 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65   ^This option se
13d60 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61  ts the.** [threa
13d70 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 65  ding mode] to Se
13d80 72 69 61 6c 69 7a 65 64 2e 20 49 6e 20 6f 74 68  rialized. In oth
13d90 65 72 20 77 6f 72 64 73 2c 20 74 68 69 73 20 6f  er words, this o
13da0 70 74 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a  ption enables.**
13db0 20 61 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e 63   all mutexes inc
13dc0 6c 75 64 69 6e 67 20 74 68 65 20 72 65 63 75 72  luding the recur
13dd0 73 69 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73 20  sive.** mutexes 
13de0 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  on [database con
13df0 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72  nection] and [pr
13e00 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
13e10 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e  ] objects..** In
13e20 20 74 68 69 73 20 6d 6f 64 65 20 28 77 68 69 63   this mode (whic
13e30 68 20 69 73 20 74 68 65 20 64 65 66 61 75 6c 74  h is the default
13e40 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20   when SQLite is 
13e50 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
13e60 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
13e70 41 46 45 3d 31 5d 29 20 74 68 65 20 53 51 4c 69  AFE=1]) the SQLi
13e80 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20  te library will 
13e90 69 74 73 65 6c 66 20 73 65 72 69 61 6c 69 7a 65  itself serialize
13ea0 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b 64   access.** to [d
13eb0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
13ec0 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72  ons] and [prepar
13ed0 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 73  ed statements] s
13ee0 6f 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 61 70  o that the.** ap
13ef0 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 66 72 65  plication is fre
13f00 65 20 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d  e to use the sam
13f10 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
13f20 65 63 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a  ection] or the.*
13f30 2a 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64  * same [prepared
13f40 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 64   statement] in d
13f50 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 73  ifferent threads
13f60 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d   at the same tim
13f70 65 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65  e..** ^If SQLite
13f80 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
13f90 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  h.** the [SQLITE
13fa0 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51  _THREADSAFE | SQ
13fb0 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
13fc0 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  0] compile-time 
13fd0 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69  option then.** i
13fe0 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c  t is not possibl
13ff0 65 20 74 6f 20 73 65 74 20 74 68 65 20 53 65 72  e to set the Ser
14000 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69  ialized [threadi
14010 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20  ng mode] and.** 
14020 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
14030 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b  )] will return [
14040 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66  SQLITE_ERROR] if
14050 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65   called with the
14060 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  .** SQLITE_CONFI
14070 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 63 6f 6e  G_SERIALIZED con
14080 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
14090 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  n.</dd>.**.** [[
140a0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
140b0 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  LLOC]] <dt>SQLIT
140c0 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c  E_CONFIG_MALLOC<
140d0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
140e0 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
140f0 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
14100 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f  nt which is a po
14110 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69  inter to an.** i
14120 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b  nstance of the [
14130 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
14140 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20  ods] structure. 
14150 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70   The argument sp
14160 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72  ecifies.** alter
14170 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c  native low-level
14180 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
14190 6f 6e 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62  on routines to b
141a0 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65 20  e used in place 
141b0 6f 66 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79  of.** the memory
141c0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74   allocation rout
141d0 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20  ines built into 
141e0 53 51 4c 69 74 65 2e 29 5e 20 5e 53 51 4c 69 74  SQLite.)^ ^SQLit
141f0 65 20 6d 61 6b 65 73 0a 2a 2a 20 69 74 73 20 6f  e makes.** its o
14200 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20  wn private copy 
14210 6f 66 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f  of the content o
14220 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
14230 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  em_methods] stru
14240 63 74 75 72 65 0a 2a 2a 20 62 65 66 6f 72 65 20  cture.** before 
14250 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  the [sqlite3_con
14260 66 69 67 28 29 5d 20 63 61 6c 6c 20 72 65 74 75  fig()] call retu
14270 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  rns.</dd>.**.** 
14280 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
14290 47 45 54 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e  GETMALLOC]] <dt>
142a0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
142b0 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20  TMALLOC</dt>.** 
142c0 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69  <dd> ^(This opti
142d0 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
142e0 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
142f0 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
14300 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20   an.** instance 
14310 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
14320 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  mem_methods] str
14330 75 63 74 75 72 65 2e 20 20 54 68 65 20 5b 73 71  ucture.  The [sq
14340 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
14350 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20  s].** structure 
14360 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74  is filled with t
14370 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66  he currently def
14380 69 6e 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ined memory allo
14390 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e  cation routines.
143a0 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f  )^.** This optio
143b0 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  n can be used to
143c0 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65   overload the de
143d0 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c  fault memory all
143e0 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69  ocation.** routi
143f0 6e 65 73 20 77 69 74 68 20 61 20 77 72 61 70 70  nes with a wrapp
14400 65 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 69  er that simulati
14410 6f 6e 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ons memory alloc
14420 61 74 69 6f 6e 20 66 61 69 6c 75 72 65 20 6f 72  ation failure or
14430 0a 2a 2a 20 74 72 61 63 6b 73 20 6d 65 6d 6f 72  .** tracks memor
14440 79 20 75 73 61 67 65 2c 20 66 6f 72 20 65 78 61  y usage, for exa
14450 6d 70 6c 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  mple. </dd>.**.*
14460 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
14470 47 5f 4d 45 4d 53 54 41 54 55 53 5d 5d 20 3c 64  G_MEMSTATUS]] <d
14480 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
14490 4d 45 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a 2a  MEMSTATUS</dt>.*
144a0 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74  * <dd> ^This opt
144b0 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c 65  ion takes single
144c0 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70   argument of typ
144d0 65 20 69 6e 74 2c 20 69 6e 74 65 72 70 72 65 74  e int, interpret
144e0 65 64 20 61 73 20 61 20 0a 2a 2a 20 62 6f 6f 6c  ed as a .** bool
144f0 65 61 6e 2c 20 77 68 69 63 68 20 65 6e 61 62 6c  ean, which enabl
14500 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74  es or disables t
14510 68 65 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66  he collection of
14520 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
14530 6f 6e 20 0a 2a 2a 20 73 74 61 74 69 73 74 69 63  on .** statistic
14540 73 2e 20 5e 28 57 68 65 6e 20 6d 65 6d 6f 72 79  s. ^(When memory
14550 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74   allocation stat
14560 69 73 74 69 63 73 20 61 72 65 20 64 69 73 61 62  istics are disab
14570 6c 65 64 2c 20 74 68 65 20 0a 2a 2a 20 66 6f 6c  led, the .** fol
14580 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65 20 69 6e  lowing SQLite in
14590 74 65 72 66 61 63 65 73 20 62 65 63 6f 6d 65 20  terfaces become 
145a0 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a  non-operational:
145b0 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20  .**   <ul>.**   
145c0 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65  <li> [sqlite3_me
145d0 6d 6f 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20  mory_used()].** 
145e0 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f    <li> [sqlite3_
145f0 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
14600 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73  ()].**   <li> [s
14610 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70  qlite3_soft_heap
14620 5f 6c 69 6d 69 74 36 34 28 29 5d 0a 2a 2a 20 20  _limit64()].**  
14630 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73   <li> [sqlite3_s
14640 74 61 74 75 73 28 29 5d 0a 2a 2a 20 20 20 3c 2f  tatus()].**   </
14650 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 79  ul>)^.** ^Memory
14660 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74   allocation stat
14670 69 73 74 69 63 73 20 61 72 65 20 65 6e 61 62 6c  istics are enabl
14680 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 75 6e  ed by default un
14690 6c 65 73 73 20 53 51 4c 69 74 65 20 69 73 0a 2a  less SQLite is.*
146a0 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  * compiled with 
146b0 5b 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f  [SQLITE_DEFAULT_
146c0 4d 45 4d 53 54 41 54 55 53 5d 3d 30 20 69 6e 20  MEMSTATUS]=0 in 
146d0 77 68 69 63 68 20 63 61 73 65 20 6d 65 6d 6f 72  which case memor
146e0 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  y.** allocation 
146f0 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20 64  statistics are d
14700 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  isabled by defau
14710 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a  lt..** </dd>.**.
14720 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
14730 49 47 5f 53 43 52 41 54 43 48 5d 5d 20 3c 64 74  IG_SCRATCH]] <dt
14740 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  >SQLITE_CONFIG_S
14750 43 52 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  CRATCH</dt>.** <
14760 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  dd> ^This option
14770 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61   specifies a sta
14780 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  tic memory buffe
14790 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61  r that SQLite ca
147a0 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20 73 63 72  n use for.** scr
147b0 61 74 63 68 20 6d 65 6d 6f 72 79 2e 20 20 54 68  atch memory.  Th
147c0 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72  ere are three ar
147d0 67 75 6d 65 6e 74 73 3a 20 20 41 20 70 6f 69 6e  guments:  A poin
147e0 74 65 72 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a  ter an 8-byte.**
147f0 20 61 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20   aligned memory 
14800 62 75 66 66 65 72 20 66 72 6f 6d 20 77 68 69 63  buffer from whic
14810 68 20 74 68 65 20 73 63 72 61 74 63 68 20 61 6c  h the scratch al
14820 6c 6f 63 61 74 69 6f 6e 73 20 77 69 6c 6c 20 62  locations will b
14830 65 0a 2a 2a 20 64 72 61 77 6e 2c 20 74 68 65 20  e.** drawn, the 
14840 73 69 7a 65 20 6f 66 20 65 61 63 68 20 73 63 72  size of each scr
14850 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  atch allocation 
14860 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65  (sz),.** and the
14870 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
14880 6f 66 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63  of scratch alloc
14890 61 74 69 6f 6e 73 20 28 4e 29 2e 20 20 54 68 65  ations (N).  The
148a0 20 73 7a 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20   sz.** argument 
148b0 6d 75 73 74 20 62 65 20 61 20 6d 75 6c 74 69 70  must be a multip
148c0 6c 65 20 6f 66 20 31 36 2e 0a 2a 2a 20 54 68 65  le of 16..** The
148d0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
148e0 6d 75 73 74 20 62 65 20 61 20 70 6f 69 6e 74 65  must be a pointe
148f0 72 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 61  r to an 8-byte a
14900 6c 69 67 6e 65 64 20 62 75 66 66 65 72 0a 2a 2a  ligned buffer.**
14910 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a   of at least sz*
14920 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72  N bytes of memor
14930 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69  y..** ^SQLite wi
14940 6c 6c 20 75 73 65 20 6e 6f 20 6d 6f 72 65 20 74  ll use no more t
14950 68 61 6e 20 74 77 6f 20 73 63 72 61 74 63 68 20  han two scratch 
14960 62 75 66 66 65 72 73 20 70 65 72 20 74 68 72 65  buffers per thre
14970 61 64 2e 20 20 53 6f 0a 2a 2a 20 4e 20 73 68 6f  ad.  So.** N sho
14980 75 6c 64 20 62 65 20 73 65 74 20 74 6f 20 74 77  uld be set to tw
14990 69 63 65 20 74 68 65 20 65 78 70 65 63 74 65 64  ice the expected
149a0 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
149b0 6f 66 20 74 68 72 65 61 64 73 2e 0a 2a 2a 20 5e  of threads..** ^
149c0 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65  SQLite will neve
149d0 72 20 72 65 71 75 69 72 65 20 61 20 73 63 72 61  r require a scra
149e0 74 63 68 20 62 75 66 66 65 72 20 74 68 61 74 20  tch buffer that 
149f0 69 73 20 6d 6f 72 65 20 74 68 61 6e 20 36 0a 2a  is more than 6.*
14a00 2a 20 74 69 6d 65 73 20 74 68 65 20 64 61 74 61  * times the data
14a10 62 61 73 65 20 70 61 67 65 20 73 69 7a 65 2e 20  base page size. 
14a20 5e 49 66 20 53 51 4c 69 74 65 20 6e 65 65 64 73  ^If SQLite needs
14a30 20 6e 65 65 64 73 20 61 64 64 69 74 69 6f 6e 61   needs additiona
14a40 6c 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d 65 6d  l.** scratch mem
14a50 6f 72 79 20 62 65 79 6f 6e 64 20 77 68 61 74 20  ory beyond what 
14a60 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 74  is provided by t
14a70 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  his configuratio
14a80 6e 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 0a  n option, then .
14a90 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ** [sqlite3_mall
14aa0 6f 63 28 29 5d 20 77 69 6c 6c 20 62 65 20 75 73  oc()] will be us
14ab0 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65  ed to obtain the
14ac0 20 6d 65 6d 6f 72 79 20 6e 65 65 64 65 64 2e 3c   memory needed.<
14ad0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
14ae0 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43  ITE_CONFIG_PAGEC
14af0 41 43 48 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  ACHE]] <dt>SQLIT
14b00 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
14b10 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  HE</dt>.** <dd> 
14b20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65  ^This option spe
14b30 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20  cifies a static 
14b40 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68  memory buffer th
14b50 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73  at SQLite can us
14b60 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 64 61 74  e for.** the dat
14b70 61 62 61 73 65 20 70 61 67 65 20 63 61 63 68 65  abase page cache
14b80 20 77 69 74 68 20 74 68 65 20 64 65 66 61 75 6c   with the defaul
14b90 74 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70  t page cache imp
14ba0 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 0a 2a  lementation.  .*
14bb0 2a 20 54 68 69 73 20 63 6f 6e 66 69 67 75 72 61  * This configura
14bc0 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f 74 20  tion should not 
14bd0 62 65 20 75 73 65 64 20 69 66 20 61 6e 20 61 70  be used if an ap
14be0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
14bf0 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69   page.** cache i
14c00 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73  mplementation is
14c10 20 6c 6f 61 64 65 64 20 75 73 69 6e 67 20 74 68   loaded using th
14c20 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
14c30 50 43 41 43 48 45 20 6f 70 74 69 6f 6e 2e 0a 2a  PCACHE option..*
14c40 2a 20 54 68 65 72 65 20 61 72 65 20 74 68 72 65  * There are thre
14c50 65 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  e arguments to t
14c60 68 69 73 20 6f 70 74 69 6f 6e 3a 20 41 20 70 6f  his option: A po
14c70 69 6e 74 65 72 20 74 6f 20 38 2d 62 79 74 65 20  inter to 8-byte 
14c80 61 6c 69 67 6e 65 64 0a 2a 2a 20 6d 65 6d 6f 72  aligned.** memor
14c90 79 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65  y, the size of e
14ca0 61 63 68 20 70 61 67 65 20 62 75 66 66 65 72 20  ach page buffer 
14cb0 28 73 7a 29 2c 20 61 6e 64 20 74 68 65 20 6e 75  (sz), and the nu
14cc0 6d 62 65 72 20 6f 66 20 70 61 67 65 73 20 28 4e  mber of pages (N
14cd0 29 2e 0a 2a 2a 20 54 68 65 20 73 7a 20 61 72 67  )..** The sz arg
14ce0 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20  ument should be 
14cf0 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
14d00 6c 61 72 67 65 73 74 20 64 61 74 61 62 61 73 65  largest database
14d10 20 70 61 67 65 0a 2a 2a 20 28 61 20 70 6f 77 65   page.** (a powe
14d20 72 20 6f 66 20 74 77 6f 20 62 65 74 77 65 65 6e  r of two between
14d30 20 35 31 32 20 61 6e 64 20 33 32 37 36 38 29 20   512 and 32768) 
14d40 70 6c 75 73 20 61 20 6c 69 74 74 6c 65 20 65 78  plus a little ex
14d50 74 72 61 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20  tra for each.** 
14d60 70 61 67 65 20 68 65 61 64 65 72 2e 20 20 5e 54  page header.  ^T
14d70 68 65 20 70 61 67 65 20 68 65 61 64 65 72 20 73  he page header s
14d80 69 7a 65 20 69 73 20 32 30 20 74 6f 20 34 30 20  ize is 20 to 40 
14d90 62 79 74 65 73 20 64 65 70 65 6e 64 69 6e 67 20  bytes depending 
14da0 6f 6e 0a 2a 2a 20 74 68 65 20 68 6f 73 74 20 61  on.** the host a
14db0 72 63 68 69 74 65 63 74 75 72 65 2e 20 20 5e 49  rchitecture.  ^I
14dc0 74 20 69 73 20 68 61 72 6d 6c 65 73 73 2c 20 61  t is harmless, a
14dd0 70 61 72 74 20 66 72 6f 6d 20 74 68 65 20 77 61  part from the wa
14de0 73 74 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20  sted memory,.** 
14df0 74 6f 20 6d 61 6b 65 20 73 7a 20 61 20 6c 69 74  to make sz a lit
14e00 74 6c 65 20 74 6f 6f 20 6c 61 72 67 65 2e 20 20  tle too large.  
14e10 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 61 72 67  The first.** arg
14e20 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 70 6f 69  ument should poi
14e30 6e 74 20 74 6f 20 61 6e 20 61 6c 6c 6f 63 61 74  nt to an allocat
14e40 69 6f 6e 20 6f 66 20 61 74 20 6c 65 61 73 74 20  ion of at least 
14e50 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65  sz*N bytes of me
14e60 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  mory..** ^SQLite
14e70 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20 6d 65   will use the me
14e80 6d 6f 72 79 20 70 72 6f 76 69 64 65 64 20 62 79  mory provided by
14e90 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
14ea0 65 6e 74 20 74 6f 20 73 61 74 69 73 66 79 20 69  ent to satisfy i
14eb0 74 73 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6e 65 65  ts.** memory nee
14ec0 64 73 20 66 6f 72 20 74 68 65 20 66 69 72 73 74  ds for the first
14ed0 20 4e 20 70 61 67 65 73 20 74 68 61 74 20 69 74   N pages that it
14ee0 20 61 64 64 73 20 74 6f 20 63 61 63 68 65 2e 20   adds to cache. 
14ef0 20 5e 49 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a   ^If additional.
14f00 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20 6d 65  ** page cache me
14f10 6d 6f 72 79 20 69 73 20 6e 65 65 64 65 64 20 62  mory is needed b
14f20 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72  eyond what is pr
14f30 6f 76 69 64 65 64 20 62 79 20 74 68 69 73 20 6f  ovided by this o
14f40 70 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20 53  ption, then.** S
14f50 51 4c 69 74 65 20 67 6f 65 73 20 74 6f 20 5b 73  QLite goes to [s
14f60 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
14f70 20 66 6f 72 20 74 68 65 20 61 64 64 69 74 69 6f   for the additio
14f80 6e 61 6c 20 73 74 6f 72 61 67 65 20 73 70 61 63  nal storage spac
14f90 65 2e 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65  e..** The pointe
14fa0 72 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61  r in the first a
14fb0 72 67 75 6d 65 6e 74 20 6d 75 73 74 0a 2a 2a 20  rgument must.** 
14fc0 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e  be aligned to an
14fd0 20 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 79   8-byte boundary
14fe0 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20 62   or subsequent b
14ff0 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74  ehavior of SQLit
15000 65 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 75 6e 64  e.** will be und
15010 65 66 69 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a  efined.</dd>.**.
15020 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
15030 49 47 5f 48 45 41 50 5d 5d 20 3c 64 74 3e 53 51  IG_HEAP]] <dt>SQ
15040 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50  LITE_CONFIG_HEAP
15050 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
15060 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69  his option speci
15070 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65  fies a static me
15080 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68 61 74  mory buffer that
15090 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65   SQLite will use
150a0 0a 2a 2a 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69  .** for all of i
150b0 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72  ts dynamic memor
150c0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65  y allocation nee
150d0 64 73 20 62 65 79 6f 6e 64 20 74 68 6f 73 65 20  ds beyond those 
150e0 70 72 6f 76 69 64 65 64 0a 2a 2a 20 66 6f 72 20  provided.** for 
150f0 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  by [SQLITE_CONFI
15100 47 5f 53 43 52 41 54 43 48 5d 20 61 6e 64 20 5b  G_SCRATCH] and [
15110 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
15120 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 54 68 65  GECACHE]..** The
15130 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67  re are three arg
15140 75 6d 65 6e 74 73 3a 20 41 6e 20 38 2d 62 79 74  uments: An 8-byt
15150 65 20 61 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65  e aligned pointe
15160 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c  r to the memory,
15170 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
15180 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 6d  f bytes in the m
15190 65 6d 6f 72 79 20 62 75 66 66 65 72 2c 20 61 6e  emory buffer, an
151a0 64 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c  d the minimum al
151b0 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a  location size..*
151c0 2a 20 5e 49 66 20 74 68 65 20 66 69 72 73 74 20  * ^If the first 
151d0 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d  pointer (the mem
151e0 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 69 73 20  ory pointer) is 
151f0 4e 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74  NULL, then SQLit
15200 65 20 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20  e reverts.** to 
15210 75 73 69 6e 67 20 69 74 73 20 64 65 66 61 75 6c  using its defaul
15220 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  t memory allocat
15230 6f 72 20 28 74 68 65 20 73 79 73 74 65 6d 20 6d  or (the system m
15240 61 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e  alloc() implemen
15250 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f  tation),.** undo
15260 69 6e 67 20 61 6e 79 20 70 72 69 6f 72 20 69 6e  ing any prior in
15270 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c  vocation of [SQL
15280 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
15290 43 5d 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20  C].  ^If the.** 
152a0 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20 69  memory pointer i
152b0 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 65  s not NULL and e
152c0 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 45 4e  ither [SQLITE_EN
152d0 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20 6f 72  ABLE_MEMSYS3] or
152e0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42  .** [SQLITE_ENAB
152f0 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 61 72 65 20  LE_MEMSYS5] are 
15300 64 65 66 69 6e 65 64 2c 20 74 68 65 6e 20 74 68  defined, then th
15310 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6d 65  e alternative me
15320 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f  mory.** allocato
15330 72 20 69 73 20 65 6e 67 61 67 65 64 20 74 6f 20  r is engaged to 
15340 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53 51  handle all of SQ
15350 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c 6c  Lites memory all
15360 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a  ocation needs..*
15370 2a 20 54 68 65 20 66 69 72 73 74 20 70 6f 69 6e  * The first poin
15380 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20  ter (the memory 
15390 70 6f 69 6e 74 65 72 29 20 6d 75 73 74 20 62 65  pointer) must be
153a0 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38   aligned to an 8
153b0 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64 61 72  -byte.** boundar
153c0 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20  y or subsequent 
153d0 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69  behavior of SQLi
153e0 74 65 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66  te will be undef
153f0 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 6d 69 6e  ined..** The min
15400 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  imum allocation 
15410 73 69 7a 65 20 69 73 20 63 61 70 70 65 64 20 61  size is capped a
15420 74 20 32 5e 31 32 2e 20 52 65 61 73 6f 6e 61 62  t 2^12. Reasonab
15430 6c 65 20 76 61 6c 75 65 73 0a 2a 2a 20 66 6f 72  le values.** for
15440 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c   the minimum all
15450 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 61 72 65  ocation size are
15460 20 32 5e 35 20 74 68 72 6f 75 67 68 20 32 5e 38   2^5 through 2^8
15470 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
15480 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54  QLITE_CONFIG_MUT
15490 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  EX]] <dt>SQLITE_
154a0 43 4f 4e 46 49 47 5f 4d 55 54 45 58 3c 2f 64 74  CONFIG_MUTEX</dt
154b0 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73  >.** <dd> ^(This
154c0 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
154d0 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
154e0 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74  which is a point
154f0 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74  er to an.** inst
15500 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c  ance of the [sql
15510 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
15520 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20  ds] structure.  
15530 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65  The argument spe
15540 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e  cifies.** altern
15550 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20  ative low-level 
15560 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 74  mutex routines t
15570 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61  o be used in pla
15580 63 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 20  ce.** the mutex 
15590 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69  routines built i
155a0 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 20 5e  nto SQLite.)^  ^
155b0 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63  SQLite makes a c
155c0 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f  opy of the.** co
155d0 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71  ntent of the [sq
155e0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
155f0 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 20 62  ods] structure b
15600 65 66 6f 72 65 20 74 68 65 20 63 61 6c 6c 20 74  efore the call t
15610 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  o.** [sqlite3_co
15620 6e 66 69 67 28 29 5d 20 72 65 74 75 72 6e 73 2e  nfig()] returns.
15630 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63   ^If SQLite is c
15640 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
15650 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
15660 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f  ADSAFE | SQLITE_
15670 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f  THREADSAFE=0] co
15680 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
15690 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e  n then.** the en
156a0 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75  tire mutexing su
156b0 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74  bsystem is omitt
156c0 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c  ed from the buil
156d0 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c  d and hence call
156e0 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  s to.** [sqlite3
156f0 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20  _config()] with 
15700 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  the SQLITE_CONFI
15710 47 5f 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72  G_MUTEX configur
15720 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c  ation option wil
15730 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c  l.** return [SQL
15740 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e  ITE_ERROR].</dd>
15750 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
15760 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 5d  CONFIG_GETMUTEX]
15770 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
15780 46 49 47 5f 47 45 54 4d 55 54 45 58 3c 2f 64 74  FIG_GETMUTEX</dt
15790 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73  >.** <dd> ^(This
157a0 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
157b0 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
157c0 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74  which is a point
157d0 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74  er to an.** inst
157e0 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c  ance of the [sql
157f0 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
15800 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20  ds] structure.  
15810 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  The.** [sqlite3_
15820 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a  mutex_methods].*
15830 2a 20 73 74 72 75 63 74 75 72 65 20 69 73 20 66  * structure is f
15840 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 63  illed with the c
15850 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64  urrently defined
15860 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 2e   mutex routines.
15870 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f  )^.** This optio
15880 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  n can be used to
15890 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65   overload the de
158a0 66 61 75 6c 74 20 6d 75 74 65 78 20 61 6c 6c 6f  fault mutex allo
158b0 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e  cation.** routin
158c0 65 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65  es with a wrappe
158d0 72 20 75 73 65 64 20 74 6f 20 74 72 61 63 6b 20  r used to track 
158e0 6d 75 74 65 78 20 75 73 61 67 65 20 66 6f 72 20  mutex usage for 
158f0 70 65 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70  performance.** p
15900 72 6f 66 69 6c 69 6e 67 20 6f 72 20 74 65 73 74  rofiling or test
15910 69 6e 67 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65  ing, for example
15920 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69  .   ^If SQLite i
15930 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
15940 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** the [SQLITE_T
15950 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49  HREADSAFE | SQLI
15960 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
15970 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
15980 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65  tion then.** the
15990 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67   entire mutexing
159a0 20 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d   subsystem is om
159b0 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62  itted from the b
159c0 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63  uild and hence c
159d0 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  alls to.** [sqli
159e0 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69  te3_config()] wi
159f0 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f  th the SQLITE_CO
15a00 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 63 6f  NFIG_GETMUTEX co
15a10 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
15a20 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72  on will.** retur
15a30 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  n [SQLITE_ERROR]
15a40 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
15a50 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f  QLITE_CONFIG_LOO
15a60 4b 41 53 49 44 45 5d 5d 20 3c 64 74 3e 53 51 4c  KASIDE]] <dt>SQL
15a70 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  ITE_CONFIG_LOOKA
15a80 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  SIDE</dt>.** <dd
15a90 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20  > ^(This option 
15aa0 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65  takes two argume
15ab0 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 6d 69  nts that determi
15ac0 6e 65 20 74 68 65 20 64 65 66 61 75 6c 74 0a 2a  ne the default.*
15ad0 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  * memory allocat
15ae0 69 6f 6e 20 66 6f 72 20 74 68 65 20 6c 6f 6f 6b  ion for the look
15af0 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  aside memory all
15b00 6f 63 61 74 6f 72 20 6f 6e 20 65 61 63 68 0a 2a  ocator on each.*
15b10 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
15b20 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 66 69  ection].  The fi
15b30 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20  rst argument is 
15b40 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65  the.** size of e
15b50 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75  ach lookaside bu
15b60 66 66 65 72 20 73 6c 6f 74 20 61 6e 64 20 74 68  ffer slot and th
15b70 65 20 73 65 63 6f 6e 64 20 69 73 20 74 68 65 20  e second is the 
15b80 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f  number of.** slo
15b90 74 73 20 61 6c 6c 6f 63 61 74 65 64 20 74 6f 20  ts allocated to 
15ba0 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f  each database co
15bb0 6e 6e 65 63 74 69 6f 6e 2e 29 5e 20 20 5e 28 54  nnection.)^  ^(T
15bc0 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20  his option sets 
15bd0 74 68 65 0a 2a 2a 20 3c 69 3e 64 65 66 61 75 6c  the.** <i>defaul
15be0 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64 65 20  t</i> lookaside 
15bf0 73 69 7a 65 2e 20 54 68 65 20 5b 53 51 4c 49 54  size. The [SQLIT
15c00 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
15c10 53 49 44 45 5d 0a 2a 2a 20 76 65 72 62 20 74 6f  SIDE].** verb to
15c20 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e   [sqlite3_db_con
15c30 66 69 67 28 29 5d 20 63 61 6e 20 62 65 20 75 73  fig()] can be us
15c40 65 64 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65  ed to change the
15c50 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 63 6f   lookaside.** co
15c60 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 6e 20 69  nfiguration on i
15c70 6e 64 69 76 69 64 75 61 6c 20 63 6f 6e 6e 65 63  ndividual connec
15c80 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64 3e 0a 2a  tions.)^ </dd>.*
15c90 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
15ca0 4e 46 49 47 5f 50 43 41 43 48 45 5d 5d 20 3c 64  NFIG_PCACHE]] <d
15cb0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
15cc0 50 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c  PCACHE</dt>.** <
15cd0 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f  dd> ^(This optio
15ce0 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
15cf0 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
15d00 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a  is a pointer to.
15d10 2a 2a 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70  ** an [sqlite3_p
15d20 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 5d 20 6f  cache_methods] o
15d30 62 6a 65 63 74 2e 20 20 54 68 69 73 20 6f 62 6a  bject.  This obj
15d40 65 63 74 20 73 70 65 63 69 66 69 65 73 20 74 68  ect specifies th
15d50 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 74  e interface.** t
15d60 6f 20 61 20 63 75 73 74 6f 6d 20 70 61 67 65 20  o a custom page 
15d70 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  cache implementa
15d80 74 69 6f 6e 2e 29 5e 20 20 5e 53 51 4c 69 74 65  tion.)^  ^SQLite
15d90 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66   makes a copy of
15da0 20 74 68 65 0a 2a 2a 20 6f 62 6a 65 63 74 20 61   the.** object a
15db0 6e 64 20 75 73 65 73 20 69 74 20 66 6f 72 20 70  nd uses it for p
15dc0 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79  age cache memory
15dd0 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 3c 2f 64   allocations.</d
15de0 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
15df0 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43  E_CONFIG_GETPCAC
15e00 48 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  HE]] <dt>SQLITE_
15e10 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
15e20 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
15e30 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
15e40 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
15e50 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70  ent which is a p
15e60 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20  ointer to an.** 
15e70 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f  [sqlite3_pcache_
15e80 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e  methods] object.
15e90 20 20 53 51 4c 69 74 65 20 63 6f 70 69 65 73 20    SQLite copies 
15ea0 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a  of the current.*
15eb0 2a 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70  * page cache imp
15ec0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 74 6f  lementation into
15ed0 20 74 68 61 74 20 6f 62 6a 65 63 74 2e 29 5e 20   that object.)^ 
15ee0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
15ef0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 5d  LITE_CONFIG_LOG]
15f00 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
15f10 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a 20  FIG_LOG</dt>.** 
15f20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45  <dd> ^The SQLITE
15f30 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69  _CONFIG_LOG opti
15f40 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67  on takes two arg
15f50 75 6d 65 6e 74 73 3a 20 61 20 70 6f 69 6e 74 65  uments: a pointe
15f60 72 20 74 6f 20 61 0a 2a 2a 20 66 75 6e 63 74 69  r to a.** functi
15f70 6f 6e 20 77 69 74 68 20 61 20 63 61 6c 6c 20 73  on with a call s
15f80 69 67 6e 61 74 75 72 65 20 6f 66 20 76 6f 69 64  ignature of void
15f90 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  (*)(void*,int,co
15fa0 6e 73 74 20 63 68 61 72 2a 29 2c 20 0a 2a 2a 20  nst char*), .** 
15fb0 61 6e 64 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  and a pointer to
15fc0 20 76 6f 69 64 2e 20 5e 49 66 20 74 68 65 20 66   void. ^If the f
15fd0 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20  unction pointer 
15fe0 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 69 74 20  is not NULL, it 
15ff0 69 73 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 62 79  is.** invoked by
16000 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d   [sqlite3_log()]
16010 20 74 6f 20 70 72 6f 63 65 73 73 20 65 61 63 68   to process each
16020 20 6c 6f 67 67 69 6e 67 20 65 76 65 6e 74 2e 20   logging event. 
16030 20 5e 49 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63   ^If the.** func
16040 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20  tion pointer is 
16050 4e 55 4c 4c 2c 20 74 68 65 20 5b 73 71 6c 69 74  NULL, the [sqlit
16060 65 33 5f 6c 6f 67 28 29 5d 20 69 6e 74 65 72 66  e3_log()] interf
16070 61 63 65 20 62 65 63 6f 6d 65 73 20 61 20 6e 6f  ace becomes a no
16080 2d 6f 70 2e 0a 2a 2a 20 5e 54 68 65 20 76 6f 69  -op..** ^The voi
16090 64 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69  d pointer that i
160a0 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  s the second arg
160b0 75 6d 65 6e 74 20 74 6f 20 53 51 4c 49 54 45 5f  ument to SQLITE_
160c0 43 4f 4e 46 49 47 5f 4c 4f 47 20 69 73 0a 2a 2a  CONFIG_LOG is.**
160d0 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 20   passed through 
160e0 61 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72  as the first par
160f0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 70  ameter to the ap
16100 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
16110 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63  d logger.** func
16120 74 69 6f 6e 20 77 68 65 6e 65 76 65 72 20 74 68  tion whenever th
16130 61 74 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 69  at function is i
16140 6e 76 6f 6b 65 64 2e 20 20 5e 54 68 65 20 73 65  nvoked.  ^The se
16150 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74  cond parameter t
16160 6f 0a 2a 2a 20 74 68 65 20 6c 6f 67 67 65 72 20  o.** the logger 
16170 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 20 63 6f  function is a co
16180 70 79 20 6f 66 20 74 68 65 20 66 69 72 73 74 20  py of the first 
16190 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
161a0 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a   corresponding.*
161b0 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29  * [sqlite3_log()
161c0 5d 20 63 61 6c 6c 20 61 6e 64 20 69 73 20 69 6e  ] call and is in
161d0 74 65 6e 64 65 64 20 74 6f 20 62 65 20 61 20 5b  tended to be a [
161e0 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20  result code] or 
161f0 61 6e 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  an.** [extended 
16200 72 65 73 75 6c 74 20 63 6f 64 65 5d 2e 20 20 5e  result code].  ^
16210 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  The third parame
16220 74 65 72 20 70 61 73 73 65 64 20 74 6f 20 74 68  ter passed to th
16230 65 20 6c 6f 67 67 65 72 20 69 73 0a 2a 2a 20 6c  e logger is.** l
16240 6f 67 20 6d 65 73 73 61 67 65 20 61 66 74 65 72  og message after
16250 20 66 6f 72 6d 61 74 74 69 6e 67 20 76 69 61 20   formatting via 
16260 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  [sqlite3_snprint
16270 66 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 53 51 4c  f()]..** The SQL
16280 69 74 65 20 6c 6f 67 67 69 6e 67 20 69 6e 74 65  ite logging inte
16290 72 66 61 63 65 20 69 73 20 6e 6f 74 20 72 65 65  rface is not ree
162a0 6e 74 72 61 6e 74 3b 20 74 68 65 20 6c 6f 67 67  ntrant; the logg
162b0 65 72 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73  er function.** s
162c0 75 70 70 6c 69 65 64 20 62 79 20 74 68 65 20 61  upplied by the a
162d0 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
162e0 6e 6f 74 20 69 6e 76 6f 6b 65 20 61 6e 79 20 53  not invoke any S
162f0 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e  QLite interface.
16300 0a 2a 2a 20 49 6e 20 61 20 6d 75 6c 74 69 2d 74  .** In a multi-t
16310 68 72 65 61 64 65 64 20 61 70 70 6c 69 63 61 74  hreaded applicat
16320 69 6f 6e 2c 20 74 68 65 20 61 70 70 6c 69 63 61  ion, the applica
16330 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67  tion-defined log
16340 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ger.** function 
16350 6d 75 73 74 20 62 65 20 74 68 72 65 61 64 73 61  must be threadsa
16360 66 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  fe. </dd>.**.** 
16370 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
16380 55 52 49 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  URI]] <dt>SQLITE
16390 5f 43 4f 4e 46 49 47 5f 55 52 49 0a 2a 2a 20 3c  _CONFIG_URI.** <
163a0 64 64 3e 20 54 68 69 73 20 6f 70 74 69 6f 6e 20  dd> This option 
163b0 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
163c0 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20  rgument of type 
163d0 69 6e 74 2e 20 49 66 20 6e 6f 6e 2d 7a 65 72 6f  int. If non-zero
163e0 2c 20 74 68 65 6e 0a 2a 2a 20 55 52 49 20 68 61  , then.** URI ha
163f0 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c  ndling is global
16400 6c 79 20 65 6e 61 62 6c 65 64 2e 20 49 66 20 74  ly enabled. If t
16410 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  he parameter is 
16420 7a 65 72 6f 2c 20 74 68 65 6e 20 55 52 49 20 68  zero, then URI h
16430 61 6e 64 6c 69 6e 67 0a 2a 2a 20 69 73 20 67 6c  andling.** is gl
16440 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2e  obally disabled.
16450 20 49 66 20 55 52 49 20 68 61 6e 64 6c 69 6e 67   If URI handling
16460 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e 61   is globally ena
16470 62 6c 65 64 2c 20 61 6c 6c 20 66 69 6c 65 6e 61  bled, all filena
16480 6d 65 73 0a 2a 2a 20 70 61 73 73 65 64 20 74 6f  mes.** passed to
16490 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
164a0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ], [sqlite3_open
164b0 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  _v2()], [sqlite3
164c0 5f 6f 70 65 6e 31 36 28 29 5d 20 6f 72 0a 2a 2a  _open16()] or.**
164d0 20 73 70 65 63 69 66 69 65 64 20 61 73 20 70 61   specified as pa
164e0 72 74 20 6f 66 20 5b 41 54 54 41 43 48 5d 20 63  rt of [ATTACH] c
164f0 6f 6d 6d 61 6e 64 73 20 61 72 65 20 69 6e 74 65  ommands are inte
16500 72 70 72 65 74 65 64 20 61 73 20 55 52 49 73 2c  rpreted as URIs,
16510 20 72 65 67 61 72 64 6c 65 73 73 0a 2a 2a 20 6f   regardless.** o
16520 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
16530 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   the [SQLITE_OPE
16540 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 20 73  N_URI] flag is s
16550 65 74 20 77 68 65 6e 20 74 68 65 20 64 61 74 61  et when the data
16560 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  base.** connecti
16570 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 49 66  on is opened. If
16580 20 69 74 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20   it is globally 
16590 64 69 73 61 62 6c 65 64 2c 20 66 69 6c 65 6e 61  disabled, filena
165a0 6d 65 73 20 61 72 65 0a 2a 2a 20 6f 6e 6c 79 20  mes are.** only 
165b0 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55  interpreted as U
165c0 52 49 73 20 69 66 20 74 68 65 20 53 51 4c 49 54  RIs if the SQLIT
165d0 45 5f 4f 50 45 4e 5f 55 52 49 20 66 6c 61 67 20  E_OPEN_URI flag 
165e0 69 73 20 73 65 74 20 77 68 65 6e 20 74 68 65 0a  is set when the.
165f0 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
16600 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64  ection is opened
16610 2e 20 42 79 20 64 65 66 61 75 6c 74 2c 20 55 52  . By default, UR
16620 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c  I handling is gl
16630 6f 62 61 6c 6c 79 0a 2a 2a 20 64 69 73 61 62 6c  obally.** disabl
16640 65 64 2e 20 54 68 65 20 64 65 66 61 75 6c 74 20  ed. The default 
16650 76 61 6c 75 65 20 6d 61 79 20 62 65 20 63 68 61  value may be cha
16660 6e 67 65 64 20 62 79 20 63 6f 6d 70 69 6c 69 6e  nged by compilin
16670 67 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53  g with the.** [S
16680 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d 20 73  QLITE_USE_URI] s
16690 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 0a 2a  ymbol defined..*
166a0 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69  * </dl>.*/.#defi
166b0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
166c0 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20 20 31  _SINGLETHREAD  1
166d0 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66    /* nil */.#def
166e0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
166f0 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 20 20  G_MULTITHREAD   
16700 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65  2  /* nil */.#de
16710 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
16720 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 20 20  IG_SERIALIZED   
16730 20 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64   3  /* nil */.#d
16740 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
16750 46 49 47 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20  FIG_MALLOC      
16760 20 20 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f    4  /* sqlite3_
16770 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a  mem_methods* */.
16780 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
16790 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20  ONFIG_GETMALLOC 
167a0 20 20 20 20 35 20 20 2f 2a 20 73 71 6c 69 74 65      5  /* sqlite
167b0 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a  3_mem_methods* *
167c0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
167d0 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20  _CONFIG_SCRATCH 
167e0 20 20 20 20 20 20 36 20 20 2f 2a 20 76 6f 69 64        6  /* void
167f0 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e  *, int sz, int N
16800 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
16810 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41  TE_CONFIG_PAGECA
16820 43 48 45 20 20 20 20 20 37 20 20 2f 2a 20 76 6f  CHE     7  /* vo
16830 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74  id*, int sz, int
16840 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51   N */.#define SQ
16850 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50  LITE_CONFIG_HEAP
16860 20 20 20 20 20 20 20 20 20 20 38 20 20 2f 2a 20            8  /* 
16870 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 42 79 74 65  void*, int nByte
16880 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 65  , int min */.#de
16890 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
168a0 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 20 20 20  IG_MEMSTATUS    
168b0 20 39 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a   9  /* boolean *
168c0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
168d0 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 20 20  _CONFIG_MUTEX   
168e0 20 20 20 20 20 31 30 20 20 2f 2a 20 73 71 6c 69       10  /* sqli
168f0 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
16900 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  s* */.#define SQ
16910 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
16920 55 54 45 58 20 20 20 20 20 31 31 20 20 2f 2a 20  UTEX     11  /* 
16930 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
16940 74 68 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65  thods* */./* pre
16950 76 69 6f 75 73 6c 79 20 53 51 4c 49 54 45 5f 43  viously SQLITE_C
16960 4f 4e 46 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43  ONFIG_CHUNKALLOC
16970 20 31 32 20 77 68 69 63 68 20 69 73 20 6e 6f 77   12 which is now
16980 20 75 6e 75 73 65 64 2e 20 2a 2f 20 0a 23 64 65   unused. */ .#de
16990 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
169a0 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20  IG_LOOKASIDE    
169b0 31 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74 20 2a  13  /* int int *
169c0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
169d0 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 20  _CONFIG_PCACHE  
169e0 20 20 20 20 20 31 34 20 20 2f 2a 20 73 71 6c 69       14  /* sqli
169f0 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f  te3_pcache_metho
16a00 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ds* */.#define S
16a10 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
16a20 50 43 41 43 48 45 20 20 20 20 31 35 20 20 2f 2a  PCACHE    15  /*
16a30 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f   sqlite3_pcache_
16a40 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66  methods* */.#def
16a50 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
16a60 47 5f 4c 4f 47 20 20 20 20 20 20 20 20 20 20 31  G_LOG          1
16a70 36 20 20 2f 2a 20 78 46 75 6e 63 2c 20 76 6f 69  6  /* xFunc, voi
16a80 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  d* */.#define SQ
16a90 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 20  LITE_CONFIG_URI 
16aa0 20 20 20 20 20 20 20 20 20 31 37 20 20 2f 2a 20           17  /* 
16ab0 69 6e 74 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  int */../*.** CA
16ac0 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65  PI3REF: Database
16ad0 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 43 6f 6e 66   Connection Conf
16ae0 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e  iguration Option
16af0 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  s.**.** These co
16b00 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65 20  nstants are the 
16b10 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65  available intege
16b20 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  r configuration 
16b30 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20  options that.** 
16b40 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61 73  can be passed as
16b50 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
16b60 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c  ment to the [sql
16b70 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
16b80 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  ] interface..**.
16b90 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61  ** New configura
16ba0 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79  tion options may
16bb0 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74   be added in fut
16bc0 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20  ure releases of 
16bd0 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74  SQLite..** Exist
16be0 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ing configuratio
16bf0 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20  n options might 
16c00 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e  be discontinued.
16c10 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a    Applications.*
16c20 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74  * should check t
16c30 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66  he return code f
16c40 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f  rom [sqlite3_db_
16c50 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b  config()] to mak
16c60 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74  e sure that.** t
16c70 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20  he call worked. 
16c80 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 64   ^The [sqlite3_d
16c90 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65  b_config()] inte
16ca0 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72  rface will retur
16cb0 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20  n a.** non-zero 
16cc0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20  [error code] if 
16cd0 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f  a discontinued o
16ce0 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f  r unsupported co
16cf0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
16d00 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64  on.** is invoked
16d10 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20  ..**.** <dl>.** 
16d20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e  <dt>SQLITE_DBCON
16d30 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64  FIG_LOOKASIDE</d
16d40 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
16d50 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 68   option takes th
16d60 72 65 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 61  ree additional a
16d70 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65  rguments that de
16d80 74 65 72 6d 69 6e 65 20 74 68 65 20 0a 2a 2a 20  termine the .** 
16d90 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72  [lookaside memor
16da0 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e  y allocator] con
16db0 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 74  figuration for t
16dc0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
16dd0 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68  nection]..** ^Th
16de0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
16df0 20 28 74 68 65 20 74 68 69 72 64 20 70 61 72 61   (the third para
16e00 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
16e10 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69  3_db_config()] i
16e20 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74  s a.** pointer t
16e30 6f 20 61 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  o a memory buffe
16e40 72 20 74 6f 20 75 73 65 20 66 6f 72 20 6c 6f 6f  r to use for loo
16e50 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2e 0a 2a  kaside memory..*
16e60 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67  * ^The first arg
16e70 75 6d 65 6e 74 20 61 66 74 65 72 20 74 68 65 20  ument after the 
16e80 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
16e90 4c 4f 4f 4b 41 53 49 44 45 20 76 65 72 62 0a 2a  LOOKASIDE verb.*
16ea0 2a 20 6d 61 79 20 62 65 20 4e 55 4c 4c 20 69 6e  * may be NULL in
16eb0 20 77 68 69 63 68 20 63 61 73 65 20 53 51 4c 69   which case SQLi
16ec0 74 65 20 77 69 6c 6c 20 61 6c 6c 6f 63 61 74 65  te will allocate
16ed0 20 74 68 65 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 64   the.** lookasid
16ee0 65 20 62 75 66 66 65 72 20 69 74 73 65 6c 66 20  e buffer itself 
16ef0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d  using [sqlite3_m
16f00 61 6c 6c 6f 63 28 29 5d 2e 20 5e 54 68 65 20 73  alloc()]. ^The s
16f10 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69  econd argument i
16f20 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66  s the.** size of
16f30 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20   each lookaside 
16f40 62 75 66 66 65 72 20 73 6c 6f 74 2e 20 20 5e 54  buffer slot.  ^T
16f50 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
16f60 74 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  t is the number 
16f70 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e 20 20 54 68  of.** slots.  Th
16f80 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75  e size of the bu
16f90 66 66 65 72 20 69 6e 20 74 68 65 20 66 69 72 73  ffer in the firs
16fa0 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20  t argument must 
16fb0 62 65 20 67 72 65 61 74 65 72 20 74 68 61 6e 0a  be greater than.
16fc0 2a 2a 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 74  ** or equal to t
16fd0 68 65 20 70 72 6f 64 75 63 74 20 6f 66 20 74 68  he product of th
16fe0 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 69  e second and thi
16ff0 72 64 20 61 72 67 75 6d 65 6e 74 73 2e 20 20 54  rd arguments.  T
17000 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 6d 75 73  he buffer.** mus
17010 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20  t be aligned to 
17020 61 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e 64 61  an 8-byte bounda
17030 72 79 2e 20 20 5e 49 66 20 74 68 65 20 73 65 63  ry.  ^If the sec
17040 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  ond argument to.
17050 2a 2a 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  ** SQLITE_DBCONF
17060 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 69 73 20  IG_LOOKASIDE is 
17070 6e 6f 74 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f  not a multiple o
17080 66 20 38 2c 20 69 74 20 69 73 20 69 6e 74 65 72  f 8, it is inter
17090 6e 61 6c 6c 79 0a 2a 2a 20 72 6f 75 6e 64 65 64  nally.** rounded
170a0 20 64 6f 77 6e 20 74 6f 20 74 68 65 20 6e 65 78   down to the nex
170b0 74 20 73 6d 61 6c 6c 65 72 20 6d 75 6c 74 69 70  t smaller multip
170c0 6c 65 20 6f 66 20 38 2e 20 20 5e 28 54 68 65 20  le of 8.  ^(The 
170d0 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79  lookaside memory
170e0 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  .** configuratio
170f0 6e 20 66 6f 72 20 61 20 64 61 74 61 62 61 73 65  n for a database
17100 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 61 6e 20   connection can 
17110 6f 6e 6c 79 20 62 65 20 63 68 61 6e 67 65 64 20  only be changed 
17120 77 68 65 6e 20 74 68 61 74 0a 2a 2a 20 63 6f 6e  when that.** con
17130 6e 65 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20 63  nection is not c
17140 75 72 72 65 6e 74 6c 79 20 75 73 69 6e 67 20 6c  urrently using l
17150 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2c  ookaside memory,
17160 20 6f 72 20 69 6e 20 6f 74 68 65 72 20 77 6f 72   or in other wor
17170 64 73 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 22  ds.** when the "
17180 63 75 72 72 65 6e 74 20 76 61 6c 75 65 22 20 72  current value" r
17190 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73  eturned by.** [s
171a0 71 6c 69 74 65 33 5f 64 62 5f 73 74 61 74 75 73  qlite3_db_status
171b0 5d 28 44 2c 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ](D,[SQLITE_CONF
171c0 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2c 2e 2e  IG_LOOKASIDE],..
171d0 2e 29 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a 20 41  .) is zero..** A
171e0 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63 68  ny attempt to ch
171f0 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69  ange the lookasi
17200 64 65 20 6d 65 6d 6f 72 79 20 63 6f 6e 66 69 67  de memory config
17210 75 72 61 74 69 6f 6e 20 77 68 65 6e 20 6c 6f 6f  uration when loo
17220 6b 61 73 69 64 65 0a 2a 2a 20 6d 65 6d 6f 72 79  kaside.** memory
17230 20 69 73 20 69 6e 20 75 73 65 20 6c 65 61 76 65   is in use leave
17240 73 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74  s the configurat
17250 69 6f 6e 20 75 6e 63 68 61 6e 67 65 64 20 61 6e  ion unchanged an
17260 64 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20 5b 53  d returns .** [S
17270 51 4c 49 54 45 5f 42 55 53 59 5d 2e 29 5e 3c 2f  QLITE_BUSY].)^</
17280 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
17290 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e  LITE_DBCONFIG_EN
172a0 41 42 4c 45 5f 46 4b 45 59 3c 2f 64 74 3e 0a 2a  ABLE_FKEY</dt>.*
172b0 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74  * <dd> ^This opt
172c0 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65  ion is used to e
172d0 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65  nable or disable
172e0 20 74 68 65 20 65 6e 66 6f 72 63 65 6d 65 6e 74   the enforcement
172f0 20 6f 66 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20   of.** [foreign 
17300 6b 65 79 20 63 6f 6e 73 74 72 61 69 6e 74 73 5d  key constraints]
17310 2e 20 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20  .  There should 
17320 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61  be two additiona
17330 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20  l arguments..** 
17340 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
17350 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  nt is an integer
17360 20 77 68 69 63 68 20 69 73 20 30 20 74 6f 20 64   which is 0 to d
17370 69 73 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63  isable FK enforc
17380 65 6d 65 6e 74 2c 0a 2a 2a 20 70 6f 73 69 74 69  ement,.** positi
17390 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 46 4b 20  ve to enable FK 
173a0 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 72 20 6e  enforcement or n
173b0 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65  egative to leave
173c0 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 0a   FK enforcement.
173d0 2a 2a 20 75 6e 63 68 61 6e 67 65 64 2e 20 20 54  ** unchanged.  T
173e0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
173f0 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ter is a pointer
17400 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69   to an integer i
17410 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  nto which.** is 
17420 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74  written 0 or 1 t
17430 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65 74 68  o indicate wheth
17440 65 72 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e  er FK enforcemen
17450 74 20 69 73 20 6f 66 66 20 6f 72 20 6f 6e 0a 2a  t is off or on.*
17460 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73  * following this
17470 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f   call.  The seco
17480 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79  nd parameter may
17490 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   be a NULL point
174a0 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20  er, in.** which 
174b0 63 61 73 65 20 74 68 65 20 46 4b 20 65 6e 66 6f  case the FK enfo
174c0 72 63 65 6d 65 6e 74 20 73 65 74 74 69 6e 67 20  rcement setting 
174d0 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20  is not reported 
174e0 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  back. </dd>.**.*
174f0 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43  * <dt>SQLITE_DBC
17500 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49  ONFIG_ENABLE_TRI
17510 47 47 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  GGER</dt>.** <dd
17520 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69  > ^This option i
17530 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65  s used to enable
17540 20 6f 72 20 64 69 73 61 62 6c 65 20 5b 43 52 45   or disable [CRE
17550 41 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 72  ATE TRIGGER | tr
17560 69 67 67 65 72 73 5d 2e 0a 2a 2a 20 54 68 65 72  iggers]..** Ther
17570 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20  e should be two 
17580 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d  additional argum
17590 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72  ents..** The fir
175a0 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  st argument is a
175b0 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20  n integer which 
175c0 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20  is 0 to disable 
175d0 74 72 69 67 67 65 72 73 2c 0a 2a 2a 20 70 6f 73  triggers,.** pos
175e0 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20  itive to enable 
175f0 74 72 69 67 67 65 72 73 20 6f 72 20 6e 65 67 61  triggers or nega
17600 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 74 68  tive to leave th
17610 65 20 73 65 74 74 69 6e 67 20 75 6e 63 68 61 6e  e setting unchan
17620 67 65 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f  ged..** The seco
17630 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
17640 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
17650 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69  integer into whi
17660 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e  ch.** is written
17670 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63   0 or 1 to indic
17680 61 74 65 20 77 68 65 74 68 65 72 20 74 72 69 67  ate whether trig
17690 67 65 72 73 20 61 72 65 20 64 69 73 61 62 6c 65  gers are disable
176a0 64 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20  d or enabled.** 
176b0 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63  following this c
176c0 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64  all.  The second
176d0 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62   parameter may b
176e0 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  e a NULL pointer
176f0 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61  , in.** which ca
17700 73 65 20 74 68 65 20 74 72 69 67 67 65 72 20 73  se the trigger s
17710 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65  etting is not re
17720 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64  ported back. </d
17730 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  d>.**.** </dl>.*
17740 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
17750 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  _DBCONFIG_LOOKAS
17760 49 44 45 20 20 20 20 20 20 20 31 30 30 31 20 20  IDE       1001  
17770 2f 2a 20 76 6f 69 64 2a 20 69 6e 74 20 69 6e 74  /* void* int int
17780 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
17790 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42  TE_DBCONFIG_ENAB
177a0 4c 45 5f 46 4b 45 59 20 20 20 20 20 31 30 30 32  LE_FKEY     1002
177b0 20 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f    /* int int* */
177c0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
177d0 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f  DBCONFIG_ENABLE_
177e0 54 52 49 47 47 45 52 20 20 31 30 30 33 20 20 2f  TRIGGER  1003  /
177f0 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 0a 0a  * int int* */...
17800 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
17810 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c  Enable Or Disabl
17820 65 20 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c  e Extended Resul
17830 74 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 5e 54  t Codes.**.** ^T
17840 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  he sqlite3_exten
17850 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73  ded_result_codes
17860 28 29 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c  () routine enabl
17870 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74  es or disables t
17880 68 65 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  he.** [extended 
17890 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 65  result codes] fe
178a0 61 74 75 72 65 20 6f 66 20 53 51 4c 69 74 65 2e  ature of SQLite.
178b0 20 5e 54 68 65 20 65 78 74 65 6e 64 65 64 20 72   ^The extended r
178c0 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 61  esult.** codes a
178d0 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 64  re disabled by d
178e0 65 66 61 75 6c 74 20 66 6f 72 20 68 69 73 74 6f  efault for histo
178f0 72 69 63 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c  rical compatibil
17900 69 74 79 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ity..*/.SQLITE_A
17910 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  PI int sqlite3_e
17920 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63  xtended_result_c
17930 6f 64 65 73 28 73 71 6c 69 74 65 33 2a 2c 20 69  odes(sqlite3*, i
17940 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a  nt onoff);../*.*
17950 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 61 73 74  * CAPI3REF: Last
17960 20 49 6e 73 65 72 74 20 52 6f 77 69 64 0a 2a 2a   Insert Rowid.**
17970 0a 2a 2a 20 5e 45 61 63 68 20 65 6e 74 72 79 20  .** ^Each entry 
17980 69 6e 20 61 6e 20 53 51 4c 69 74 65 20 74 61 62  in an SQLite tab
17990 6c 65 20 68 61 73 20 61 20 75 6e 69 71 75 65 20  le has a unique 
179a0 36 34 2d 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a  64-bit signed.**
179b0 20 69 6e 74 65 67 65 72 20 6b 65 79 20 63 61 6c   integer key cal
179c0 6c 65 64 20 74 68 65 20 5b 52 4f 57 49 44 20 7c  led the [ROWID |
179d0 20 22 72 6f 77 69 64 22 5d 2e 20 5e 54 68 65 20   "rowid"]. ^The 
179e0 72 6f 77 69 64 20 69 73 20 61 6c 77 61 79 73 20  rowid is always 
179f0 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20  available.** as 
17a00 61 6e 20 75 6e 64 65 63 6c 61 72 65 64 20 63 6f  an undeclared co
17a10 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44  lumn named ROWID
17a20 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44  , OID, or _ROWID
17a30 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f  _ as long as tho
17a40 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20  se.** names are 
17a50 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64 20 62 79  not also used by
17a60 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c   explicitly decl
17a70 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49  ared columns. ^I
17a80 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65 20 68  f.** the table h
17a90 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74  as a column of t
17aa0 79 70 65 20 5b 49 4e 54 45 47 45 52 20 50 52 49  ype [INTEGER PRI
17ab0 4d 41 52 59 20 4b 45 59 5d 20 74 68 65 6e 20 74  MARY KEY] then t
17ac0 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73  hat column.** is
17ad0 20 61 6e 6f 74 68 65 72 20 61 6c 69 61 73 20 66   another alias f
17ae0 6f 72 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a  or the rowid..**
17af0 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e  .** ^This routin
17b00 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b 72  e returns the [r
17b10 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 6d 6f 73  owid] of the mos
17b20 74 20 72 65 63 65 6e 74 0a 2a 2a 20 73 75 63 63  t recent.** succ
17b30 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20  essful [INSERT] 
17b40 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61 73  into the databas
17b50 65 20 66 72 6f 6d 20 74 68 65 20 5b 64 61 74 61  e from the [data
17b60 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
17b70 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74  .** in the first
17b80 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 41 73 20   argument.  ^As 
17b90 6f 66 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  of SQLite versio
17ba0 6e 20 33 2e 37 2e 37 2c 20 74 68 69 73 20 72 6f  n 3.7.7, this ro
17bb0 75 74 69 6e 65 73 0a 2a 2a 20 72 65 63 6f 72 64  utines.** record
17bc0 73 20 74 68 65 20 6c 61 73 74 20 69 6e 73 65 72  s the last inser
17bd0 74 20 72 6f 77 69 64 20 6f 66 20 62 6f 74 68 20  t rowid of both 
17be0 6f 72 64 69 6e 61 72 79 20 74 61 62 6c 65 73 20  ordinary tables 
17bf0 61 6e 64 20 5b 76 69 72 74 75 61 6c 20 74 61 62  and [virtual tab
17c00 6c 65 73 5d 2e 0a 2a 2a 20 5e 49 66 20 6e 6f 20  les]..** ^If no 
17c10 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45  successful [INSE
17c20 52 54 5d 73 0a 2a 2a 20 68 61 76 65 20 65 76 65  RT]s.** have eve
17c30 72 20 6f 63 63 75 72 72 65 64 20 6f 6e 20 74 68  r occurred on th
17c40 61 74 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  at database conn
17c50 65 63 74 69 6f 6e 2c 20 7a 65 72 6f 20 69 73 20  ection, zero is 
17c60 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
17c70 5e 28 49 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d  ^(If an [INSERT]
17c80 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61   occurs within a
17c90 20 74 72 69 67 67 65 72 20 6f 72 20 77 69 74 68   trigger or with
17ca0 69 6e 20 61 20 5b 76 69 72 74 75 61 6c 20 74 61  in a [virtual ta
17cb0 62 6c 65 5d 0a 2a 2a 20 6d 65 74 68 6f 64 2c 20  ble].** method, 
17cc0 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e  then this routin
17cd0 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 74 68  e will return th
17ce0 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65  e [rowid] of the
17cf0 20 69 6e 73 65 72 74 65 64 0a 2a 2a 20 72 6f 77   inserted.** row
17d00 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20   as long as the 
17d10 74 72 69 67 67 65 72 20 6f 72 20 76 69 72 74 75  trigger or virtu
17d20 61 6c 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20  al table method 
17d30 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42  is running..** B
17d40 75 74 20 6f 6e 63 65 20 74 68 65 20 74 72 69 67  ut once the trig
17d50 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c 20 74  ger or virtual t
17d60 61 62 6c 65 20 6d 65 74 68 6f 64 20 65 6e 64 73  able method ends
17d70 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  , the value retu
17d80 72 6e 65 64 20 0a 2a 2a 20 62 79 20 74 68 69 73  rned .** by this
17d90 20 72 6f 75 74 69 6e 65 20 72 65 76 65 72 74 73   routine reverts
17da0 20 74 6f 20 77 68 61 74 20 69 74 20 77 61 73 20   to what it was 
17db0 62 65 66 6f 72 65 20 74 68 65 20 74 72 69 67 67  before the trigg
17dc0 65 72 20 6f 72 20 76 69 72 74 75 61 6c 0a 2a 2a  er or virtual.**
17dd0 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 62 65   table method be
17de0 67 61 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e  gan.)^.**.** ^An
17df0 20 5b 49 4e 53 45 52 54 5d 20 74 68 61 74 20 66   [INSERT] that f
17e00 61 69 6c 73 20 64 75 65 20 74 6f 20 61 20 63 6f  ails due to a co
17e10 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69  nstraint violati
17e20 6f 6e 20 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 73  on is not a.** s
17e30 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52  uccessful [INSER
17e40 54 5d 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20  T] and does not 
17e50 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65  change the value
17e60 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69   returned by thi
17e70 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 20 5e  s.** routine.  ^
17e80 54 68 75 73 20 49 4e 53 45 52 54 20 4f 52 20 46  Thus INSERT OR F
17e90 41 49 4c 2c 20 49 4e 53 45 52 54 20 4f 52 20 49  AIL, INSERT OR I
17ea0 47 4e 4f 52 45 2c 20 49 4e 53 45 52 54 20 4f 52  GNORE, INSERT OR
17eb0 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e   ROLLBACK,.** an
17ec0 64 20 49 4e 53 45 52 54 20 4f 52 20 41 42 4f 52  d INSERT OR ABOR
17ed0 54 20 6d 61 6b 65 20 6e 6f 20 63 68 61 6e 67 65  T make no change
17ee0 73 20 74 6f 20 74 68 65 20 72 65 74 75 72 6e 20  s to the return 
17ef0 76 61 6c 75 65 20 6f 66 20 74 68 69 73 0a 2a 2a  value of this.**
17f00 20 72 6f 75 74 69 6e 65 20 77 68 65 6e 20 74 68   routine when th
17f10 65 69 72 20 69 6e 73 65 72 74 69 6f 6e 20 66 61  eir insertion fa
17f20 69 6c 73 2e 20 20 5e 28 57 68 65 6e 20 49 4e 53  ils.  ^(When INS
17f30 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45 0a 2a  ERT OR REPLACE.*
17f40 2a 20 65 6e 63 6f 75 6e 74 65 72 73 20 61 20 63  * encounters a c
17f50 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74  onstraint violat
17f60 69 6f 6e 2c 20 69 74 20 64 6f 65 73 20 6e 6f 74  ion, it does not
17f70 20 66 61 69 6c 2e 20 20 54 68 65 0a 2a 2a 20 49   fail.  The.** I
17f80 4e 53 45 52 54 20 63 6f 6e 74 69 6e 75 65 73 20  NSERT continues 
17f90 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 66  to completion af
17fa0 74 65 72 20 64 65 6c 65 74 69 6e 67 20 72 6f 77  ter deleting row
17fb0 73 20 74 68 61 74 20 63 61 75 73 65 64 0a 2a 2a  s that caused.**
17fc0 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 20   the constraint 
17fd0 70 72 6f 62 6c 65 6d 20 73 6f 20 49 4e 53 45 52  problem so INSER
17fe0 54 20 4f 52 20 52 45 50 4c 41 43 45 20 77 69 6c  T OR REPLACE wil
17ff0 6c 20 61 6c 77 61 79 73 20 63 68 61 6e 67 65 0a  l always change.
18000 2a 2a 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  ** the return va
18010 6c 75 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65  lue of this inte
18020 72 66 61 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  rface.)^.**.** ^
18030 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65 73  For the purposes
18040 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65   of this routine
18050 2c 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 69 73  , an [INSERT] is
18060 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 0a 2a   considered to.*
18070 2a 20 62 65 20 73 75 63 63 65 73 73 66 75 6c 20  * be successful 
18080 65 76 65 6e 20 69 66 20 69 74 20 69 73 20 73 75  even if it is su
18090 62 73 65 71 75 65 6e 74 6c 79 20 72 6f 6c 6c 65  bsequently rolle
180a0 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68  d back..**.** Th
180b0 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61  is function is a
180c0 63 63 65 73 73 69 62 6c 65 20 74 6f 20 53 51 4c  ccessible to SQL
180d0 20 73 74 61 74 65 6d 65 6e 74 73 20 76 69 61 20   statements via 
180e0 74 68 65 0a 2a 2a 20 5b 6c 61 73 74 5f 69 6e 73  the.** [last_ins
180f0 65 72 74 5f 72 6f 77 69 64 28 29 20 53 51 4c 20  ert_rowid() SQL 
18100 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a  function]..**.**
18110 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74   If a separate t
18120 68 72 65 61 64 20 70 65 72 66 6f 72 6d 73 20 61  hread performs a
18130 20 6e 65 77 20 5b 49 4e 53 45 52 54 5d 20 6f 6e   new [INSERT] on
18140 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 64 61 74   the same.** dat
18150 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
18160 20 77 68 69 6c 65 20 74 68 65 20 5b 73 71 6c 69   while the [sqli
18170 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
18180 72 6f 77 69 64 28 29 5d 0a 2a 2a 20 66 75 6e 63  rowid()].** func
18190 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 20  tion is running 
181a0 61 6e 64 20 74 68 75 73 20 63 68 61 6e 67 65 73  and thus changes
181b0 20 74 68 65 20 6c 61 73 74 20 69 6e 73 65 72 74   the last insert
181c0 20 5b 72 6f 77 69 64 5d 2c 0a 2a 2a 20 74 68 65   [rowid],.** the
181d0 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  n the value retu
181e0 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
181f0 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
18200 69 64 28 29 5d 20 69 73 0a 2a 2a 20 75 6e 70 72  id()] is.** unpr
18210 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6d 69  edictable and mi
18220 67 68 74 20 6e 6f 74 20 65 71 75 61 6c 20 65 69  ght not equal ei
18230 74 68 65 72 20 74 68 65 20 6f 6c 64 20 6f 72 20  ther the old or 
18240 74 68 65 20 6e 65 77 0a 2a 2a 20 6c 61 73 74 20  the new.** last 
18250 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2e 0a  insert [rowid]..
18260 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71  */.SQLITE_API sq
18270 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
18280 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
18290 72 6f 77 69 64 28 73 71 6c 69 74 65 33 2a 29 3b  rowid(sqlite3*);
182a0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
182b0 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e 75 6d 62  : Count The Numb
182c0 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66  er Of Rows Modif
182d0 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  ied.**.** ^This 
182e0 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
182f0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64   the number of d
18300 61 74 61 62 61 73 65 20 72 6f 77 73 20 74 68 61  atabase rows tha
18310 74 20 77 65 72 65 20 63 68 61 6e 67 65 64 0a 2a  t were changed.*
18320 2a 20 6f 72 20 69 6e 73 65 72 74 65 64 20 6f 72  * or inserted or
18330 20 64 65 6c 65 74 65 64 20 62 79 20 74 68 65 20   deleted by the 
18340 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f  most recently co
18350 6d 70 6c 65 74 65 64 20 53 51 4c 20 73 74 61 74  mpleted SQL stat
18360 65 6d 65 6e 74 0a 2a 2a 20 6f 6e 20 74 68 65 20  ement.** on the 
18370 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
18380 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20  tion] specified 
18390 62 79 20 74 68 65 20 66 69 72 73 74 20 70 61 72  by the first par
183a0 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 28 4f 6e 6c  ameter..** ^(Onl
183b0 79 20 63 68 61 6e 67 65 73 20 74 68 61 74 20 61  y changes that a
183c0 72 65 20 64 69 72 65 63 74 6c 79 20 73 70 65 63  re directly spec
183d0 69 66 69 65 64 20 62 79 20 74 68 65 20 5b 49 4e  ified by the [IN
183e0 53 45 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d 2c  SERT], [UPDATE],
183f0 0a 2a 2a 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20  .** or [DELETE] 
18400 73 74 61 74 65 6d 65 6e 74 20 61 72 65 20 63 6f  statement are co
18410 75 6e 74 65 64 2e 20 20 41 75 78 69 6c 69 61 72  unted.  Auxiliar
18420 79 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64  y changes caused
18430 20 62 79 0a 2a 2a 20 74 72 69 67 67 65 72 73 20   by.** triggers 
18440 6f 72 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20  or [foreign key 
18450 61 63 74 69 6f 6e 73 5d 20 61 72 65 20 6e 6f 74  actions] are not
18460 20 63 6f 75 6e 74 65 64 2e 29 5e 20 55 73 65 20   counted.)^ Use 
18470 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
18480 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d  total_changes()]
18490 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 66 69 6e   function to fin
184a0 64 20 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62  d the total numb
184b0 65 72 20 6f 66 20 63 68 61 6e 67 65 73 0a 2a 2a  er of changes.**
184c0 20 69 6e 63 6c 75 64 69 6e 67 20 63 68 61 6e 67   including chang
184d0 65 73 20 63 61 75 73 65 64 20 62 79 20 74 72 69  es caused by tri
184e0 67 67 65 72 73 20 61 6e 64 20 66 6f 72 65 69 67  ggers and foreig
184f0 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 2e 0a 2a  n key actions..*
18500 2a 0a 2a 2a 20 5e 43 68 61 6e 67 65 73 20 74 6f  *.** ^Changes to
18510 20 61 20 76 69 65 77 20 74 68 61 74 20 61 72 65   a view that are
18520 20 73 69 6d 75 6c 61 74 65 64 20 62 79 20 61 6e   simulated by an
18530 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69   [INSTEAD OF tri
18540 67 67 65 72 5d 0a 2a 2a 20 61 72 65 20 6e 6f 74  gger].** are not
18550 20 63 6f 75 6e 74 65 64 2e 20 20 4f 6e 6c 79 20   counted.  Only 
18560 72 65 61 6c 20 74 61 62 6c 65 20 63 68 61 6e 67  real table chang
18570 65 73 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 0a  es are counted..
18580 2a 2a 0a 2a 2a 20 5e 28 41 20 22 72 6f 77 20 63  **.** ^(A "row c
18590 68 61 6e 67 65 22 20 69 73 20 61 20 63 68 61 6e  hange" is a chan
185a0 67 65 20 74 6f 20 61 20 73 69 6e 67 6c 65 20 72  ge to a single r
185b0 6f 77 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 74  ow of a single t
185c0 61 62 6c 65 0a 2a 2a 20 63 61 75 73 65 64 20 62  able.** caused b
185d0 79 20 61 6e 20 49 4e 53 45 52 54 2c 20 44 45 4c  y an INSERT, DEL
185e0 45 54 45 2c 20 6f 72 20 55 50 44 41 54 45 20 73  ETE, or UPDATE s
185f0 74 61 74 65 6d 65 6e 74 2e 20 20 52 6f 77 73 20  tatement.  Rows 
18600 74 68 61 74 0a 2a 2a 20 61 72 65 20 63 68 61 6e  that.** are chan
18610 67 65 64 20 61 73 20 73 69 64 65 20 65 66 66 65  ged as side effe
18620 63 74 73 20 6f 66 20 5b 52 45 50 4c 41 43 45 5d  cts of [REPLACE]
18630 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73 6f   constraint reso
18640 6c 75 74 69 6f 6e 2c 0a 2a 2a 20 72 6f 6c 6c 62  lution,.** rollb
18650 61 63 6b 2c 20 41 42 4f 52 54 20 70 72 6f 63 65  ack, ABORT proce
18660 73 73 69 6e 67 2c 20 5b 44 52 4f 50 20 54 41 42  ssing, [DROP TAB
18670 4c 45 5d 2c 20 6f 72 20 62 79 20 61 6e 79 20 6f  LE], or by any o
18680 74 68 65 72 0a 2a 2a 20 6d 65 63 68 61 6e 69 73  ther.** mechanis
18690 6d 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20  ms do not count 
186a0 61 73 20 64 69 72 65 63 74 20 72 6f 77 20 63 68  as direct row ch
186b0 61 6e 67 65 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41  anges.)^.**.** A
186c0 20 22 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78   "trigger contex
186d0 74 22 20 69 73 20 61 20 73 63 6f 70 65 20 6f 66  t" is a scope of
186e0 20 65 78 65 63 75 74 69 6f 6e 20 74 68 61 74 20   execution that 
186f0 62 65 67 69 6e 73 20 61 6e 64 0a 2a 2a 20 65 6e  begins and.** en
18700 64 73 20 77 69 74 68 20 74 68 65 20 73 63 72 69  ds with the scri
18710 70 74 20 6f 66 20 61 20 5b 43 52 45 41 54 45 20  pt of a [CREATE 
18720 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 65  TRIGGER | trigge
18730 72 5d 2e 20 0a 2a 2a 20 4d 6f 73 74 20 53 51 4c  r]. .** Most SQL
18740 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 0a   statements are.
18750 2a 2a 20 65 76 61 6c 75 61 74 65 64 20 6f 75 74  ** evaluated out
18760 73 69 64 65 20 6f 66 20 61 6e 79 20 74 72 69 67  side of any trig
18770 67 65 72 2e 20 20 54 68 69 73 20 69 73 20 74 68  ger.  This is th
18780 65 20 22 74 6f 70 20 6c 65 76 65 6c 22 0a 2a 2a  e "top level".**
18790 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74   trigger context
187a0 2e 20 20 49 66 20 61 20 74 72 69 67 67 65 72 20  .  If a trigger 
187b0 66 69 72 65 73 20 66 72 6f 6d 20 74 68 65 20 74  fires from the t
187c0 6f 70 20 6c 65 76 65 6c 2c 20 61 0a 2a 2a 20 6e  op level, a.** n
187d0 65 77 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65  ew trigger conte
187e0 78 74 20 69 73 20 65 6e 74 65 72 65 64 20 66 6f  xt is entered fo
187f0 72 20 74 68 65 20 64 75 72 61 74 69 6f 6e 20 6f  r the duration o
18800 66 20 74 68 61 74 20 6f 6e 65 0a 2a 2a 20 74 72  f that one.** tr
18810 69 67 67 65 72 2e 20 20 53 75 62 74 72 69 67 67  igger.  Subtrigg
18820 65 72 73 20 63 72 65 61 74 65 20 73 75 62 63 6f  ers create subco
18830 6e 74 65 78 74 73 20 66 6f 72 20 74 68 65 69 72  ntexts for their
18840 20 64 75 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a   duration..**.**
18850 20 5e 43 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74   ^Calling [sqlit
18860 65 33 5f 65 78 65 63 28 29 5d 20 6f 72 20 5b 73  e3_exec()] or [s
18870 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72  qlite3_step()] r
18880 65 63 75 72 73 69 76 65 6c 79 20 64 6f 65 73 0a  ecursively does.
18890 2a 2a 20 6e 6f 74 20 63 72 65 61 74 65 20 61 20  ** not create a 
188a0 6e 65 77 20 74 72 69 67 67 65 72 20 63 6f 6e 74  new trigger cont
188b0 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  ext..**.** ^This
188c0 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
188d0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
188e0 64 69 72 65 63 74 20 72 6f 77 20 63 68 61 6e 67  direct row chang
188f0 65 73 20 69 6e 20 74 68 65 0a 2a 2a 20 6d 6f 73  es in the.** mos
18900 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c  t recent INSERT,
18910 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45   UPDATE, or DELE
18920 54 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74  TE statement wit
18930 68 69 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20  hin the same.** 
18940 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e  trigger context.
18950 0a 2a 2a 0a 2a 2a 20 5e 54 68 75 73 2c 20 77 68  .**.** ^Thus, wh
18960 65 6e 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74  en called from t
18970 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20 74 68  he top level, th
18980 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  is function retu
18990 72 6e 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65  rns the.** numbe
189a0 72 20 6f 66 20 63 68 61 6e 67 65 73 20 69 6e 20  r of changes in 
189b0 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
189c0 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20  INSERT, UPDATE, 
189d0 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61  or DELETE.** tha
189e0 74 20 61 6c 73 6f 20 6f 63 63 75 72 72 65 64 20  t also occurred 
189f0 61 74 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c  at the top level
18a00 2e 20 20 5e 28 57 69 74 68 69 6e 20 74 68 65 20  .  ^(Within the 
18a10 62 6f 64 79 20 6f 66 20 61 20 74 72 69 67 67 65  body of a trigge
18a20 72 2c 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65  r,.** the sqlite
18a30 33 5f 63 68 61 6e 67 65 73 28 29 20 69 6e 74 65  3_changes() inte
18a40 72 66 61 63 65 20 63 61 6e 20 62 65 20 63 61 6c  rface can be cal
18a50 6c 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20  led to find the 
18a60 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61  number of.** cha
18a70 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f 73 74  nges in the most
18a80 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65   recently comple
18a90 74 65 64 20 49 4e 53 45 52 54 2c 20 55 50 44 41  ted INSERT, UPDA
18aa0 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a  TE, or DELETE.**
18ab0 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69   statement withi
18ac0 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 20 74 68  n the body of th
18ad0 65 20 73 61 6d 65 20 74 72 69 67 67 65 72 2e 0a  e same trigger..
18ae0 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20  ** However, the 
18af0 6e 75 6d 62 65 72 20 72 65 74 75 72 6e 65 64 20  number returned 
18b00 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65  does not include
18b10 20 63 68 61 6e 67 65 73 0a 2a 2a 20 63 61 75 73   changes.** caus
18b20 65 64 20 62 79 20 73 75 62 74 72 69 67 67 65 72  ed by subtrigger
18b30 73 20 73 69 6e 63 65 20 74 68 6f 73 65 20 68 61  s since those ha
18b40 76 65 20 74 68 65 69 72 20 6f 77 6e 20 63 6f 6e  ve their own con
18b50 74 65 78 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65  text.)^.**.** Se
18b60 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69  e also the [sqli
18b70 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
18b80 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20  s()] interface, 
18b90 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68  the.** [count_ch
18ba0 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 61  anges pragma], a
18bb0 6e 64 20 74 68 65 20 5b 63 68 61 6e 67 65 73 28  nd the [changes(
18bc0 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e  ) SQL function].
18bd0 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61  .**.** If a sepa
18be0 72 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65  rate thread make
18bf0 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65  s changes on the
18c00 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63   same database c
18c10 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69  onnection.** whi
18c20 6c 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e  le [sqlite3_chan
18c30 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e  ges()] is runnin
18c40 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65  g then the value
18c50 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20   returned.** is 
18c60 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e  unpredictable an
18c70 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c  d not meaningful
18c80 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
18c90 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e  int sqlite3_chan
18ca0 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  ges(sqlite3*);..
18cb0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
18cc0 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20  Total Number Of 
18cd0 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a  Rows Modified.**
18ce0 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69  .** ^This functi
18cf0 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  on returns the n
18d00 75 6d 62 65 72 20 6f 66 20 72 6f 77 20 63 68 61  umber of row cha
18d10 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20 5b  nges caused by [
18d20 49 4e 53 45 52 54 5d 2c 0a 2a 2a 20 5b 55 50 44  INSERT],.** [UPD
18d30 41 54 45 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d  ATE] or [DELETE]
18d40 20 73 74 61 74 65 6d 65 6e 74 73 20 73 69 6e 63   statements sinc
18d50 65 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  e the [database 
18d60 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 61 73 20  connection] was 
18d70 6f 70 65 6e 65 64 2e 0a 2a 2a 20 5e 28 54 68 65  opened..** ^(The
18d80 20 63 6f 75 6e 74 20 72 65 74 75 72 6e 65 64 20   count returned 
18d90 62 79 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  by sqlite3_total
18da0 5f 63 68 61 6e 67 65 73 28 29 20 69 6e 63 6c 75  _changes() inclu
18db0 64 65 73 20 61 6c 6c 20 63 68 61 6e 67 65 73 0a  des all changes.
18dc0 2a 2a 20 66 72 6f 6d 20 61 6c 6c 20 5b 43 52 45  ** from all [CRE
18dd0 41 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 72  ATE TRIGGER | tr
18de0 69 67 67 65 72 5d 20 63 6f 6e 74 65 78 74 73 20  igger] contexts 
18df0 61 6e 64 20 63 68 61 6e 67 65 73 20 6d 61 64 65  and changes made
18e00 20 62 79 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20   by.** [foreign 
18e10 6b 65 79 20 61 63 74 69 6f 6e 73 5d 2e 20 48 6f  key actions]. Ho
18e20 77 65 76 65 72 2c 0a 2a 2a 20 74 68 65 20 63 6f  wever,.** the co
18e30 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63  unt does not inc
18e40 6c 75 64 65 20 63 68 61 6e 67 65 73 20 75 73 65  lude changes use
18e50 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b  d to implement [
18e60 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61  REPLACE] constra
18e70 69 6e 74 73 2c 0a 2a 2a 20 64 6f 20 72 6f 6c 6c  ints,.** do roll
18e80 62 61 63 6b 73 20 6f 72 20 41 42 4f 52 54 20 70  backs or ABORT p
18e90 72 6f 63 65 73 73 69 6e 67 2c 20 6f 72 20 5b 44  rocessing, or [D
18ea0 52 4f 50 20 54 41 42 4c 45 5d 20 70 72 6f 63 65  ROP TABLE] proce
18eb0 73 73 69 6e 67 2e 20 20 54 68 65 0a 2a 2a 20 63  ssing.  The.** c
18ec0 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e  ount does not in
18ed0 63 6c 75 64 65 20 72 6f 77 73 20 6f 66 20 76 69  clude rows of vi
18ee0 65 77 73 20 74 68 61 74 20 66 69 72 65 20 61 6e  ews that fire an
18ef0 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69   [INSTEAD OF tri
18f00 67 67 65 72 5d 2c 0a 2a 2a 20 74 68 6f 75 67 68  gger],.** though
18f10 20 69 66 20 74 68 65 20 49 4e 53 54 45 41 44 20   if the INSTEAD 
18f20 4f 46 20 74 72 69 67 67 65 72 20 6d 61 6b 65 73  OF trigger makes
18f30 20 63 68 61 6e 67 65 73 20 6f 66 20 69 74 73 20   changes of its 
18f40 6f 77 6e 2c 20 74 68 6f 73 65 20 63 68 61 6e 67  own, those chang
18f50 65 73 20 0a 2a 2a 20 61 72 65 20 63 6f 75 6e 74  es .** are count
18f60 65 64 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 73 71  ed.)^.** ^The sq
18f70 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
18f80 67 65 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 63  ges() function c
18f90 6f 75 6e 74 73 20 74 68 65 20 63 68 61 6e 67 65  ounts the change
18fa0 73 20 61 73 20 73 6f 6f 6e 20 61 73 0a 2a 2a 20  s as soon as.** 
18fb0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 68  the statement th
18fc0 61 74 20 6d 61 6b 65 73 20 74 68 65 6d 20 69 73  at makes them is
18fd0 20 63 6f 6d 70 6c 65 74 65 64 20 28 77 68 65 6e   completed (when
18fe0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68   the statement h
18ff0 61 6e 64 6c 65 0a 2a 2a 20 69 73 20 70 61 73 73  andle.** is pass
19000 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72  ed to [sqlite3_r
19010 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69  eset()] or [sqli
19020 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 29  te3_finalize()])
19030 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
19040 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68   the [sqlite3_ch
19050 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61  anges()] interfa
19060 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e  ce, the.** [coun
19070 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61  t_changes pragma
19080 5d 2c 20 61 6e 64 20 74 68 65 20 5b 74 6f 74 61  ], and the [tota
19090 6c 5f 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20  l_changes() SQL 
190a0 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a  function]..**.**
190b0 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74   If a separate t
190c0 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e  hread makes chan
190d0 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  ges on the same 
190e0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
190f0 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71  ion.** while [sq
19100 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
19110 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e  ges()] is runnin
19120 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65  g then the value
19130 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 73 20  .** returned is 
19140 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e  unpredictable an
19150 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c  d not meaningful
19160 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
19170 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 6f 74 61  int sqlite3_tota
19180 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65  l_changes(sqlite
19190 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  3*);../*.** CAPI
191a0 33 52 45 46 3a 20 49 6e 74 65 72 72 75 70 74 20  3REF: Interrupt 
191b0 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20 51  A Long-Running Q
191c0 75 65 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  uery.**.** ^This
191d0 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73   function causes
191e0 20 61 6e 79 20 70 65 6e 64 69 6e 67 20 64 61 74   any pending dat
191f0 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 20  abase operation 
19200 74 6f 20 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20  to abort and.** 
19210 72 65 74 75 72 6e 20 61 74 20 69 74 73 20 65 61  return at its ea
19220 72 6c 69 65 73 74 20 6f 70 70 6f 72 74 75 6e 69  rliest opportuni
19230 74 79 2e 20 54 68 69 73 20 72 6f 75 74 69 6e 65  ty. This routine
19240 20 69 73 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a   is typically.**
19250 20 63 61 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f   called in respo
19260 6e 73 65 20 74 6f 20 61 20 75 73 65 72 20 61 63  nse to a user ac
19270 74 69 6f 6e 20 73 75 63 68 20 61 73 20 70 72 65  tion such as pre
19280 73 73 69 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a  ssing "Cancel".*
19290 2a 20 6f 72 20 43 74 72 6c 2d 43 20 77 68 65 72  * or Ctrl-C wher
192a0 65 20 74 68 65 20 75 73 65 72 20 77 61 6e 74 73  e the user wants
192b0 20 61 20 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70   a long query op
192c0 65 72 61 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a  eration to halt.
192d0 2a 2a 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a  ** immediately..
192e0 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 73 61 66  **.** ^It is saf
192f0 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72  e to call this r
19300 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61 20 74 68  outine from a th
19310 72 65 61 64 20 64 69 66 66 65 72 65 6e 74 20 66  read different f
19320 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 72 65 61  rom the.** threa
19330 64 20 74 68 61 74 20 69 73 20 63 75 72 72 65 6e  d that is curren
19340 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74 68 65 20  tly running the 
19350 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69  database operati
19360 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a 2a 20 69  on.  But it.** i
19370 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 63 61  s not safe to ca
19380 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  ll this routine 
19390 77 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 65  with a [database
193a0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61   connection] tha
193b0 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 64 20 6f  t.** is closed o
193c0 72 20 6d 69 67 68 74 20 63 6c 6f 73 65 20 62 65  r might close be
193d0 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 69 6e 74  fore sqlite3_int
193e0 65 72 72 75 70 74 28 29 20 72 65 74 75 72 6e 73  errupt() returns
193f0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 53  ..**.** ^If an S
19400 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20  QL operation is 
19410 76 65 72 79 20 6e 65 61 72 6c 79 20 66 69 6e 69  very nearly fini
19420 73 68 65 64 20 61 74 20 74 68 65 20 74 69 6d 65  shed at the time
19430 20 77 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33   when.** sqlite3
19440 5f 69 6e 74 65 72 72 75 70 74 28 29 20 69 73 20  _interrupt() is 
19450 63 61 6c 6c 65 64 2c 20 74 68 65 6e 20 69 74 20  called, then it 
19460 6d 69 67 68 74 20 6e 6f 74 20 68 61 76 65 20 61  might not have a
19470 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79 0a 2a 2a  n opportunity.**
19480 20 74 6f 20 62 65 20 69 6e 74 65 72 72 75 70 74   to be interrupt
19490 65 64 20 61 6e 64 20 6d 69 67 68 74 20 63 6f 6e  ed and might con
194a0 74 69 6e 75 65 20 74 6f 20 63 6f 6d 70 6c 65 74  tinue to complet
194b0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 53  ion..**.** ^An S
194c0 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61  QL operation tha
194d0 74 20 69 73 20 69 6e 74 65 72 72 75 70 74 65 64  t is interrupted
194e0 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51   will return [SQ
194f0 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e  LITE_INTERRUPT].
19500 0a 2a 2a 20 5e 49 66 20 74 68 65 20 69 6e 74 65  .** ^If the inte
19510 72 72 75 70 74 65 64 20 53 51 4c 20 6f 70 65 72  rrupted SQL oper
19520 61 74 69 6f 6e 20 69 73 20 61 6e 20 49 4e 53 45  ation is an INSE
19530 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44  RT, UPDATE, or D
19540 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 69 73  ELETE.** that is
19550 20 69 6e 73 69 64 65 20 61 6e 20 65 78 70 6c 69   inside an expli
19560 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c  cit transaction,
19570 20 74 68 65 6e 20 74 68 65 20 65 6e 74 69 72 65   then the entire
19580 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20   transaction.** 
19590 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62  will be rolled b
195a0 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ack automaticall
195b0 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  y..**.** ^The sq
195c0 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
195d0 44 29 20 63 61 6c 6c 20 69 73 20 69 6e 20 65 66  D) call is in ef
195e0 66 65 63 74 20 75 6e 74 69 6c 20 61 6c 6c 20 63  fect until all c
195f0 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67  urrently running
19600 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
19610 74 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20  ts on [database 
19620 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 63 6f  connection] D co
19630 6d 70 6c 65 74 65 2e 20 20 5e 41 6e 79 20 6e 65  mplete.  ^Any ne
19640 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  w SQL statements
19650 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61  .** that are sta
19660 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20 73  rted after the s
19670 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
19680 28 29 20 63 61 6c 6c 20 61 6e 64 20 62 65 66 6f  () call and befo
19690 72 65 20 74 68 65 20 0a 2a 2a 20 72 75 6e 6e 69  re the .** runni
196a0 6e 67 20 73 74 61 74 65 6d 65 6e 74 73 20 72 65  ng statements re
196b0 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65 20 69  aches zero are i
196c0 6e 74 65 72 72 75 70 74 65 64 20 61 73 20 69 66  nterrupted as if
196d0 20 74 68 65 79 20 68 61 64 20 62 65 65 6e 0a 2a   they had been.*
196e0 2a 20 72 75 6e 6e 69 6e 67 20 70 72 69 6f 72 20  * running prior 
196f0 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69  to the sqlite3_i
19700 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 2e  nterrupt() call.
19710 20 20 5e 4e 65 77 20 53 51 4c 20 73 74 61 74 65    ^New SQL state
19720 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72  ments.** that ar
19730 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20  e started after 
19740 74 68 65 20 72 75 6e 6e 69 6e 67 20 73 74 61 74  the running stat
19750 65 6d 65 6e 74 20 63 6f 75 6e 74 20 72 65 61 63  ement count reac
19760 68 65 73 20 7a 65 72 6f 20 61 72 65 0a 2a 2a 20  hes zero are.** 
19770 6e 6f 74 20 65 66 66 65 63 74 65 64 20 62 79 20  not effected by 
19780 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  the sqlite3_inte
19790 72 72 75 70 74 28 29 2e 0a 2a 2a 20 5e 41 20 63  rrupt()..** ^A c
197a0 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69  all to sqlite3_i
197b0 6e 74 65 72 72 75 70 74 28 44 29 20 74 68 61 74  nterrupt(D) that
197c0 20 6f 63 63 75 72 73 20 77 68 65 6e 20 74 68 65   occurs when the
197d0 72 65 20 61 72 65 20 6e 6f 20 72 75 6e 6e 69 6e  re are no runnin
197e0 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65  g.** SQL stateme
197f0 6e 74 73 20 69 73 20 61 20 6e 6f 2d 6f 70 20 61  nts is a no-op a
19800 6e 64 20 68 61 73 20 6e 6f 20 65 66 66 65 63 74  nd has no effect
19810 20 6f 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   on SQL statemen
19820 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73  ts.** that are s
19830 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65  tarted after the
19840 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
19850 70 74 28 29 20 63 61 6c 6c 20 72 65 74 75 72 6e  pt() call return
19860 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  s..**.** If the 
19870 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
19880 69 6f 6e 20 63 6c 6f 73 65 73 20 77 68 69 6c 65  ion closes while
19890 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72   [sqlite3_interr
198a0 75 70 74 28 29 5d 0a 2a 2a 20 69 73 20 72 75 6e  upt()].** is run
198b0 6e 69 6e 67 20 74 68 65 6e 20 62 61 64 20 74 68  ning then bad th
198c0 69 6e 67 73 20 77 69 6c 6c 20 6c 69 6b 65 6c 79  ings will likely
198d0 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a 53 51 4c 49   happen..*/.SQLI
198e0 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69  TE_API void sqli
198f0 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 73 71  te3_interrupt(sq
19900 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
19910 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d  CAPI3REF: Determ
19920 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74  ine If An SQL St
19930 61 74 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c  atement Is Compl
19940 65 74 65 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ete.**.** These 
19950 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65  routines are use
19960 66 75 6c 20 64 75 72 69 6e 67 20 63 6f 6d 6d 61  ful during comma
19970 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f  nd-line input to
19980 20 64 65 74 65 72 6d 69 6e 65 20 69 66 20 74 68   determine if th
19990 65 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 65  e.** currently e
199a0 6e 74 65 72 65 64 20 74 65 78 74 20 73 65 65 6d  ntered text seem
199b0 73 20 74 6f 20 66 6f 72 6d 20 61 20 63 6f 6d 70  s to form a comp
199c0 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65  lete SQL stateme
199d0 6e 74 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69  nt or.** if addi
199e0 74 69 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73 20  tional input is 
199f0 6e 65 65 64 65 64 20 62 65 66 6f 72 65 20 73 65  needed before se
19a00 6e 64 69 6e 67 20 74 68 65 20 74 65 78 74 20 69  nding the text i
19a10 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f  nto.** SQLite fo
19a20 72 20 70 61 72 73 69 6e 67 2e 20 20 5e 54 68 65  r parsing.  ^The
19a30 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  se routines retu
19a40 72 6e 20 31 20 69 66 20 74 68 65 20 69 6e 70 75  rn 1 if the inpu
19a50 74 20 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65  t string.** appe
19a60 61 72 73 20 74 6f 20 62 65 20 61 20 63 6f 6d 70  ars to be a comp
19a70 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65  lete SQL stateme
19a80 6e 74 2e 20 20 5e 41 20 73 74 61 74 65 6d 65 6e  nt.  ^A statemen
19a90 74 20 69 73 20 6a 75 64 67 65 64 20 74 6f 20 62  t is judged to b
19aa0 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66  e.** complete if
19ab0 20 69 74 20 65 6e 64 73 20 77 69 74 68 20 61 20   it ends with a 
19ac0 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20  semicolon token 
19ad0 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 72 65  and is not a pre
19ae0 66 69 78 20 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c  fix of a.** well
19af0 2d 66 6f 72 6d 65 64 20 43 52 45 41 54 45 20 54  -formed CREATE T
19b00 52 49 47 47 45 52 20 73 74 61 74 65 6d 65 6e 74  RIGGER statement
19b10 2e 20 20 5e 53 65 6d 69 63 6f 6c 6f 6e 73 20 74  .  ^Semicolons t
19b20 68 61 74 20 61 72 65 20 65 6d 62 65 64 64 65 64  hat are embedded
19b30 20 77 69 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e   within.** strin
19b40 67 20 6c 69 74 65 72 61 6c 73 20 6f 72 20 71 75  g literals or qu
19b50 6f 74 65 64 20 69 64 65 6e 74 69 66 69 65 72 20  oted identifier 
19b60 6e 61 6d 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74  names or comment
19b70 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64  s are not.** ind
19b80 65 70 65 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20  ependent tokens 
19b90 28 74 68 65 79 20 61 72 65 20 70 61 72 74 20 6f  (they are part o
19ba0 66 20 74 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77  f the token in w
19bb0 68 69 63 68 20 74 68 65 79 20 61 72 65 0a 2a 2a  hich they are.**
19bc0 20 65 6d 62 65 64 64 65 64 29 20 61 6e 64 20 74   embedded) and t
19bd0 68 75 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74  hus do not count
19be0 20 61 73 20 61 20 73 74 61 74 65 6d 65 6e 74 20   as a statement 
19bf0 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 57 68  terminator.  ^Wh
19c00 69 74 65 73 70 61 63 65 0a 2a 2a 20 61 6e 64 20  itespace.** and 
19c10 63 6f 6d 6d 65 6e 74 73 20 74 68 61 74 20 66 6f  comments that fo
19c20 6c 6c 6f 77 20 74 68 65 20 66 69 6e 61 6c 20 73  llow the final s
19c30 65 6d 69 63 6f 6c 6f 6e 20 61 72 65 20 69 67 6e  emicolon are ign
19c40 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ored..**.** ^The
19c50 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  se routines retu
19c60 72 6e 20 30 20 69 66 20 74 68 65 20 73 74 61 74  rn 0 if the stat
19c70 65 6d 65 6e 74 20 69 73 20 69 6e 63 6f 6d 70 6c  ement is incompl
19c80 65 74 65 2e 20 20 5e 49 66 20 61 0a 2a 2a 20 6d  ete.  ^If a.** m
19c90 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
19ca0 20 66 61 69 6c 73 2c 20 74 68 65 6e 20 53 51 4c   fails, then SQL
19cb0 49 54 45 5f 4e 4f 4d 45 4d 20 69 73 20 72 65 74  ITE_NOMEM is ret
19cc0 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  urned..**.** ^Th
19cd0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 64 6f 20  ese routines do 
19ce0 6e 6f 74 20 70 61 72 73 65 20 74 68 65 20 53 51  not parse the SQ
19cf0 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 75  L statements thu
19d00 73 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65  s.** will not de
19d10 74 65 63 74 20 73 79 6e 74 61 63 74 69 63 61 6c  tect syntactical
19d20 6c 79 20 69 6e 63 6f 72 72 65 63 74 20 53 51 4c  ly incorrect SQL
19d30 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53 51 4c  ..**.** ^(If SQL
19d40 69 74 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e  ite has not been
19d50 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 75 73 69   initialized usi
19d60 6e 67 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74  ng [sqlite3_init
19d70 69 61 6c 69 7a 65 28 29 5d 20 70 72 69 6f 72 20  ialize()] prior 
19d80 0a 2a 2a 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 20  .** to invoking 
19d90 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
19da0 31 36 28 29 20 74 68 65 6e 20 73 71 6c 69 74 65  16() then sqlite
19db0 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
19dc0 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75 74  s invoked.** aut
19dd0 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71  omatically by sq
19de0 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36  lite3_complete16
19df0 28 29 2e 20 20 49 66 20 74 68 61 74 20 69 6e 69  ().  If that ini
19e00 74 69 61 6c 69 7a 61 74 69 6f 6e 20 66 61 69 6c  tialization fail
19e10 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 72  s,.** then the r
19e20 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d  eturn value from
19e30 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74   sqlite3_complet
19e40 65 31 36 28 29 20 77 69 6c 6c 20 62 65 20 6e 6f  e16() will be no
19e50 6e 2d 7a 65 72 6f 0a 2a 2a 20 72 65 67 61 72 64  n-zero.** regard
19e60 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20  less of whether 
19e70 6f 72 20 6e 6f 74 20 74 68 65 20 69 6e 70 75 74  or not the input
19e80 20 53 51 4c 20 69 73 20 63 6f 6d 70 6c 65 74 65   SQL is complete
19e90 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e  .)^.**.** The in
19ea0 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  put to [sqlite3_
19eb0 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6d 75 73 74  complete()] must
19ec0 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   be a zero-termi
19ed0 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 38 20 73  nated.** UTF-8 s
19ee0 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tring..**.** The
19ef0 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74   input to [sqlit
19f00 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d  e3_complete16()]
19f10 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d   must be a zero-
19f20 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54  terminated.** UT
19f30 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e  F-16 string in n
19f40 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
19f50 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
19f60 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  int sqlite3_comp
19f70 6c 65 74 65 28 63 6f 6e 73 74 20 63 68 61 72 20  lete(const char 
19f80 2a 73 71 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50  *sql);.SQLITE_AP
19f90 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  I int sqlite3_co
19fa0 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73 74 20 76  mplete16(const v
19fb0 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a  oid *sql);../*.*
19fc0 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 67 69  * CAPI3REF: Regi
19fd0 73 74 65 72 20 41 20 43 61 6c 6c 62 61 63 6b 20  ster A Callback 
19fe0 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49 54 45  To Handle SQLITE
19ff0 5f 42 55 53 59 20 45 72 72 6f 72 73 0a 2a 2a 0a  _BUSY Errors.**.
1a000 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65  ** ^This routine
1a010 20 73 65 74 73 20 61 20 63 61 6c 6c 62 61 63 6b   sets a callback
1a020 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 6d   function that m
1a030 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20  ight be invoked 
1a040 77 68 65 6e 65 76 65 72 0a 2a 2a 20 61 6e 20 61  whenever.** an a
1a050 74 74 65 6d 70 74 20 69 73 20 6d 61 64 65 20 74  ttempt is made t
1a060 6f 20 6f 70 65 6e 20 61 20 64 61 74 61 62 61 73  o open a databas
1a070 65 20 74 61 62 6c 65 20 74 68 61 74 20 61 6e 6f  e table that ano
1a080 74 68 65 72 20 74 68 72 65 61 64 0a 2a 2a 20 6f  ther thread.** o
1a090 72 20 70 72 6f 63 65 73 73 20 68 61 73 20 6c 6f  r process has lo
1a0a0 63 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  cked..**.** ^If 
1a0b0 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63  the busy callbac
1a0c0 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20  k is NULL, then 
1a0d0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72  [SQLITE_BUSY] or
1a0e0 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42   [SQLITE_IOERR_B
1a0f0 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 69 73 20 72 65  LOCKED].** is re
1a100 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65  turned immediate
1a110 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e 74 65  ly upon encounte
1a120 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e 20 20  ring the lock.  
1a130 5e 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c  ^If the busy cal
1a140 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20  lback.** is not 
1a150 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 63  NULL, then the c
1a160 61 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 62 65  allback might be
1a170 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 77   invoked with tw
1a180 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a  o arguments..**.
1a190 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  ** ^The first ar
1a1a0 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 62 75  gument to the bu
1a1b0 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 61 20  sy handler is a 
1a1c0 63 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64  copy of the void
1a1d0 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 0a  * pointer which.
1a1e0 2a 2a 20 69 73 20 74 68 65 20 74 68 69 72 64 20  ** is the third 
1a1f0 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
1a200 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
1a210 28 29 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64  ().  ^The second
1a220 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
1a230 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
1a240 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65   callback is the
1a250 20 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 73   number of times
1a260 20 74 68 61 74 20 74 68 65 20 62 75 73 79 20 68   that the busy h
1a270 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20 62 65  andler has.** be
1a280 65 6e 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 74  en invoked for t
1a290 68 69 73 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e  his locking even
1a2a0 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 62  t.  ^If the.** b
1a2b0 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  usy callback ret
1a2c0 75 72 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f 20  urns 0, then no 
1a2d0 61 64 64 69 74 69 6f 6e 61 6c 20 61 74 74 65 6d  additional attem
1a2e0 70 74 73 20 61 72 65 20 6d 61 64 65 20 74 6f 0a  pts are made to.
1a2f0 2a 2a 20 61 63 63 65 73 73 20 74 68 65 20 64 61  ** access the da
1a300 74 61 62 61 73 65 20 61 6e 64 20 5b 53 51 4c 49  tabase and [SQLI
1a310 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c  TE_BUSY] or [SQL
1a320 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45  ITE_IOERR_BLOCKE
1a330 44 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  D] is returned..
1a340 2a 2a 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62  ** ^If the callb
1a350 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d  ack returns non-
1a360 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68  zero, then anoth
1a370 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a 20 69 73  er attempt.** is
1a380 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20 74 68   made to open th
1a390 65 20 64 61 74 61 62 61 73 65 20 66 6f 72 20 72  e database for r
1a3a0 65 61 64 69 6e 67 20 61 6e 64 20 74 68 65 20 63  eading and the c
1a3b0 79 63 6c 65 20 72 65 70 65 61 74 73 2e 0a 2a 2a  ycle repeats..**
1a3c0 0a 2a 2a 20 54 68 65 20 70 72 65 73 65 6e 63 65  .** The presence
1a3d0 20 6f 66 20 61 20 62 75 73 79 20 68 61 6e 64 6c   of a busy handl
1a3e0 65 72 20 64 6f 65 73 20 6e 6f 74 20 67 75 61 72  er does not guar
1a3f0 61 6e 74 65 65 20 74 68 61 74 20 69 74 20 77 69  antee that it wi
1a400 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a  ll be invoked.**
1a410 20 77 68 65 6e 20 74 68 65 72 65 20 69 73 20 6c   when there is l
1a420 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20  ock contention. 
1a430 5e 49 66 20 53 51 4c 69 74 65 20 64 65 74 65 72  ^If SQLite deter
1a440 6d 69 6e 65 73 20 74 68 61 74 20 69 6e 76 6f 6b  mines that invok
1a450 69 6e 67 20 74 68 65 20 62 75 73 79 0a 2a 2a 20  ing the busy.** 
1a460 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20 72 65  handler could re
1a470 73 75 6c 74 20 69 6e 20 61 20 64 65 61 64 6c 6f  sult in a deadlo
1a480 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67 6f 20 61  ck, it will go a
1a490 68 65 61 64 20 61 6e 64 20 72 65 74 75 72 6e 20  head and return 
1a4a0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a  [SQLITE_BUSY].**
1a4b0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52   or [SQLITE_IOER
1a4c0 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 6e 73 74 65  R_BLOCKED] inste
1a4d0 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20 74  ad of invoking t
1a4e0 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e  he busy handler.
1a4f0 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20 61 20 73  .** Consider a s
1a500 63 65 6e 61 72 69 6f 20 77 68 65 72 65 20 6f 6e  cenario where on
1a510 65 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c  e process is hol
1a520 64 69 6e 67 20 61 20 72 65 61 64 20 6c 6f 63 6b  ding a read lock
1a530 20 74 68 61 74 0a 2a 2a 20 69 74 20 69 73 20 74   that.** it is t
1a540 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d 6f 74 65  rying to promote
1a550 20 74 6f 20 61 20 72 65 73 65 72 76 65 64 20 6c   to a reserved l
1a560 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 73 65 63  ock and.** a sec
1a570 6f 6e 64 20 70 72 6f 63 65 73 73 20 69 73 20 68  ond process is h
1a580 6f 6c 64 69 6e 67 20 61 20 72 65 73 65 72 76 65  olding a reserve
1a590 64 20 6c 6f 63 6b 20 74 68 61 74 20 69 74 20 69  d lock that it i
1a5a0 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74 6f 20 70  s trying.** to p
1a5b0 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 65 78 63  romote to an exc
1a5c0 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20 20 54 68  lusive lock.  Th
1a5d0 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 20  e first process 
1a5e0 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65 64 0a 2a  cannot proceed.*
1a5f0 2a 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20  * because it is 
1a600 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 73  blocked by the s
1a610 65 63 6f 6e 64 20 61 6e 64 20 74 68 65 20 73 65  econd and the se
1a620 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 63 61 6e  cond process can
1a630 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 64 20 62  not.** proceed b
1a640 65 63 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f  ecause it is blo
1a650 63 6b 65 64 20 62 79 20 74 68 65 20 66 69 72 73  cked by the firs
1a660 74 2e 20 20 49 66 20 62 6f 74 68 20 70 72 6f 63  t.  If both proc
1a670 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20  esses.** invoke 
1a680 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
1a690 73 2c 20 6e 65 69 74 68 65 72 20 77 69 6c 6c 20  s, neither will 
1a6a0 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67 72 65 73  make any progres
1a6b0 73 2e 20 20 54 68 65 72 65 66 6f 72 65 2c 0a 2a  s.  Therefore,.*
1a6c0 2a 20 53 51 4c 69 74 65 20 72 65 74 75 72 6e 73  * SQLite returns
1a6d0 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 66   [SQLITE_BUSY] f
1a6e0 6f 72 20 74 68 65 20 66 69 72 73 74 20 70 72 6f  or the first pro
1a6f0 63 65 73 73 2c 20 68 6f 70 69 6e 67 20 74 68 61  cess, hoping tha
1a700 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c 6c 20 69  t this.** will i
1a710 6e 64 75 63 65 20 74 68 65 20 66 69 72 73 74 20  nduce the first 
1a720 70 72 6f 63 65 73 73 20 74 6f 20 72 65 6c 65 61  process to relea
1a730 73 65 20 69 74 73 20 72 65 61 64 20 6c 6f 63 6b  se its read lock
1a740 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68   and allow.** th
1a750 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73  e second process
1a760 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a   to proceed..**.
1a770 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20  ** ^The default 
1a780 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73  busy callback is
1a790 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   NULL..**.** ^Th
1a7a0 65 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  e [SQLITE_BUSY] 
1a7b0 65 72 72 6f 72 20 69 73 20 63 6f 6e 76 65 72 74  error is convert
1a7c0 65 64 20 74 6f 20 5b 53 51 4c 49 54 45 5f 49 4f  ed to [SQLITE_IO
1a7d0 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20  ERR_BLOCKED].** 
1a7e0 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 69  when SQLite is i
1a7f0 6e 20 74 68 65 20 6d 69 64 64 6c 65 20 6f 66 20  n the middle of 
1a800 61 20 6c 61 72 67 65 20 74 72 61 6e 73 61 63 74  a large transact
1a810 69 6f 6e 20 77 68 65 72 65 20 61 6c 6c 20 74 68  ion where all th
1a820 65 0a 2a 2a 20 63 68 61 6e 67 65 73 20 77 69 6c  e.** changes wil
1a830 6c 20 6e 6f 74 20 66 69 74 20 69 6e 74 6f 20 74  l not fit into t
1a840 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 20 63 61 63  he in-memory cac
1a850 68 65 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c  he.  SQLite will
1a860 0a 2a 2a 20 61 6c 72 65 61 64 79 20 68 6f 6c 64  .** already hold
1a870 20 61 20 52 45 53 45 52 56 45 44 20 6c 6f 63 6b   a RESERVED lock
1a880 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65   on the database
1a890 20 66 69 6c 65 2c 20 62 75 74 20 69 74 20 6e 65   file, but it ne
1a8a0 65 64 73 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74  eds.** to promot
1a8b0 65 20 74 68 69 73 20 6c 6f 63 6b 20 74 6f 20 45  e this lock to E
1a8c0 58 43 4c 55 53 49 56 45 20 73 6f 20 74 68 61 74  XCLUSIVE so that
1a8d0 20 69 74 20 63 61 6e 20 73 70 69 6c 6c 20 63 61   it can spill ca
1a8e0 63 68 65 0a 2a 2a 20 70 61 67 65 73 20 69 6e 74  che.** pages int
1a8f0 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  o the database f
1a900 69 6c 65 20 77 69 74 68 6f 75 74 20 68 61 72 6d  ile without harm
1a910 20 74 6f 20 63 6f 6e 63 75 72 72 65 6e 74 0a 2a   to concurrent.*
1a920 2a 20 72 65 61 64 65 72 73 2e 20 20 5e 49 66 20  * readers.  ^If 
1a930 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  it is unable to 
1a940 70 72 6f 6d 6f 74 65 20 74 68 65 20 6c 6f 63 6b  promote the lock
1a950 2c 20 74 68 65 6e 20 74 68 65 20 69 6e 2d 6d 65  , then the in-me
1a960 6d 6f 72 79 0a 2a 2a 20 63 61 63 68 65 20 77 69  mory.** cache wi
1a970 6c 6c 20 62 65 20 6c 65 66 74 20 69 6e 20 61 6e  ll be left in an
1a980 20 69 6e 63 6f 6e 73 69 73 74 65 6e 74 20 73 74   inconsistent st
1a990 61 74 65 20 61 6e 64 20 73 6f 20 74 68 65 20 65  ate and so the e
1a9a0 72 72 6f 72 0a 2a 2a 20 63 6f 64 65 20 69 73 20  rror.** code is 
1a9b0 70 72 6f 6d 6f 74 65 64 20 66 72 6f 6d 20 74 68  promoted from th
1a9c0 65 20 72 65 6c 61 74 69 76 65 6c 79 20 62 65 6e  e relatively ben
1a9d0 69 67 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  ign [SQLITE_BUSY
1a9e0 5d 20 74 6f 0a 2a 2a 20 74 68 65 20 6d 6f 72 65  ] to.** the more
1a9f0 20 73 65 76 65 72 65 20 5b 53 51 4c 49 54 45 5f   severe [SQLITE_
1aa00 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 20  IOERR_BLOCKED]. 
1aa10 20 5e 54 68 69 73 20 65 72 72 6f 72 20 63 6f 64   ^This error cod
1aa20 65 20 70 72 6f 6d 6f 74 69 6f 6e 0a 2a 2a 20 66  e promotion.** f
1aa30 6f 72 63 65 73 20 61 6e 20 61 75 74 6f 6d 61 74  orces an automat
1aa40 69 63 20 72 6f 6c 6c 62 61 63 6b 20 6f 66 20 74  ic rollback of t
1aa50 68 65 20 63 68 61 6e 67 65 73 2e 20 20 53 65 65  he changes.  See
1aa60 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d   the.** <a href=
1aa70 22 2f 63 76 73 74 72 61 63 2f 77 69 6b 69 3f 70  "/cvstrac/wiki?p
1aa80 3d 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f  =CorruptionFollo
1aa90 77 69 6e 67 42 75 73 79 45 72 72 6f 72 22 3e 0a  wingBusyError">.
1aaa0 2a 2a 20 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c  ** CorruptionFol
1aab0 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72 3c  lowingBusyError<
1aac0 2f 61 3e 20 77 69 6b 69 20 70 61 67 65 20 66 6f  /a> wiki page fo
1aad0 72 20 61 20 64 69 73 63 75 73 73 69 6f 6e 20 6f  r a discussion o
1aae0 66 20 77 68 79 0a 2a 2a 20 74 68 69 73 20 69 73  f why.** this is
1aaf0 20 69 6d 70 6f 72 74 61 6e 74 2e 0a 2a 2a 0a 2a   important..**.*
1ab00 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e  * ^(There can on
1ab10 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62  ly be a single b
1ab20 75 73 79 20 68 61 6e 64 6c 65 72 20 64 65 66 69  usy handler defi
1ab30 6e 65 64 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20  ned for each.** 
1ab40 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1ab50 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69 6e 67 20  tion].  Setting 
1ab60 61 20 6e 65 77 20 62 75 73 79 20 68 61 6e 64 6c  a new busy handl
1ab70 65 72 20 63 6c 65 61 72 73 20 61 6e 79 0a 2a 2a  er clears any.**
1ab80 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74 20   previously set 
1ab90 68 61 6e 64 6c 65 72 2e 29 5e 20 20 5e 4e 6f 74  handler.)^  ^Not
1aba0 65 20 74 68 61 74 20 63 61 6c 6c 69 6e 67 20 5b  e that calling [
1abb0 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d  sqlite3_busy_tim
1abc0 65 6f 75 74 28 29 5d 0a 2a 2a 20 77 69 6c 6c 20  eout()].** will 
1abd0 61 6c 73 6f 20 73 65 74 20 6f 72 20 63 6c 65 61  also set or clea
1abe0 72 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  r the busy handl
1abf0 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62 75  er..**.** The bu
1ac00 73 79 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75  sy callback shou
1ac10 6c 64 20 6e 6f 74 20 74 61 6b 65 20 61 6e 79 20  ld not take any 
1ac20 61 63 74 69 6f 6e 73 20 77 68 69 63 68 20 6d 6f  actions which mo
1ac30 64 69 66 79 20 74 68 65 0a 2a 2a 20 64 61 74 61  dify the.** data
1ac40 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
1ac50 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65  that invoked the
1ac60 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 20 20   busy handler.  
1ac70 41 6e 79 20 73 75 63 68 20 61 63 74 69 6f 6e 73  Any such actions
1ac80 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e 20 75 6e  .** result in un
1ac90 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72  defined behavior
1aca0 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75 73 79 20  ..** .** A busy 
1acb0 68 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e 6f 74  handler must not
1acc0 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62   close the datab
1acd0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
1ace0 2a 20 6f 72 20 5b 70 72 65 70 61 72 65 64 20 73  * or [prepared s
1acf0 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69  tatement] that i
1ad00 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20  nvoked the busy 
1ad10 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 53 51 4c 49  handler..*/.SQLI
1ad20 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
1ad30 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28  e3_busy_handler(
1ad40 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29  sqlite3*, int(*)
1ad50 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 20 76 6f 69  (void*,int), voi
1ad60 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d*);../*.** CAPI
1ad70 33 52 45 46 3a 20 53 65 74 20 41 20 42 75 73 79  3REF: Set A Busy
1ad80 20 54 69 6d 65 6f 75 74 0a 2a 2a 0a 2a 2a 20 5e   Timeout.**.** ^
1ad90 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74  This routine set
1ada0 73 20 61 20 5b 73 71 6c 69 74 65 33 5f 62 75 73  s a [sqlite3_bus
1adb0 79 5f 68 61 6e 64 6c 65 72 20 7c 20 62 75 73 79  y_handler | busy
1adc0 20 68 61 6e 64 6c 65 72 5d 20 74 68 61 74 20 73   handler] that s
1add0 6c 65 65 70 73 0a 2a 2a 20 66 6f 72 20 61 20 73  leeps.** for a s
1ade0 70 65 63 69 66 69 65 64 20 61 6d 6f 75 6e 74 20  pecified amount 
1adf0 6f 66 20 74 69 6d 65 20 77 68 65 6e 20 61 20 74  of time when a t
1ae00 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65 64 2e 20  able is locked. 
1ae10 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 0a 2a 2a   ^The handler.**
1ae20 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d 75 6c 74   will sleep mult
1ae30 69 70 6c 65 20 74 69 6d 65 73 20 75 6e 74 69 6c  iple times until
1ae40 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d   at least "ms" m
1ae50 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73  illiseconds of s
1ae60 6c 65 65 70 69 6e 67 0a 2a 2a 20 68 61 76 65 20  leeping.** have 
1ae70 61 63 63 75 6d 75 6c 61 74 65 64 2e 20 20 5e 41  accumulated.  ^A
1ae80 66 74 65 72 20 61 74 20 6c 65 61 73 74 20 22 6d  fter at least "m
1ae90 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  s" milliseconds 
1aea0 6f 66 20 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20  of sleeping,.** 
1aeb0 74 68 65 20 68 61 6e 64 6c 65 72 20 72 65 74 75  the handler retu
1aec0 72 6e 73 20 30 20 77 68 69 63 68 20 63 61 75 73  rns 0 which caus
1aed0 65 73 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  es [sqlite3_step
1aee0 28 29 5d 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a  ()] to return.**
1aef0 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f   [SQLITE_BUSY] o
1af00 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  r [SQLITE_IOERR_
1af10 42 4c 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a 20  BLOCKED]..**.** 
1af20 5e 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f  ^Calling this ro
1af30 75 74 69 6e 65 20 77 69 74 68 20 61 6e 20 61 72  utine with an ar
1af40 67 75 6d 65 6e 74 20 6c 65 73 73 20 74 68 61 6e  gument less than
1af50 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72   or equal to zer
1af60 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20 61  o.** turns off a
1af70 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73  ll busy handlers
1af80 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20  ..**.** ^(There 
1af90 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69  can only be a si
1afa0 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65  ngle busy handle
1afb0 72 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c  r for a particul
1afc0 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  ar.** [database 
1afd0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 79 20  connection] any 
1afe0 61 6e 79 20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74  any given moment
1aff0 2e 20 20 49 66 20 61 6e 6f 74 68 65 72 20 62 75  .  If another bu
1b000 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 61  sy handler.** wa
1b010 73 20 64 65 66 69 6e 65 64 20 20 28 75 73 69 6e  s defined  (usin
1b020 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  g [sqlite3_busy_
1b030 68 61 6e 64 6c 65 72 28 29 5d 29 20 70 72 69 6f  handler()]) prio
1b040 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20  r to calling.** 
1b050 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 74 68  this routine, th
1b060 61 74 20 6f 74 68 65 72 20 62 75 73 79 20 68 61  at other busy ha
1b070 6e 64 6c 65 72 20 69 73 20 63 6c 65 61 72 65 64  ndler is cleared
1b080 2e 29 5e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  .)^.*/.SQLITE_AP
1b090 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75  I int sqlite3_bu
1b0a0 73 79 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69 74  sy_timeout(sqlit
1b0b0 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f  e3*, int ms);../
1b0c0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
1b0d0 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f 75 74 69  onvenience Routi
1b0e0 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20  nes For Running 
1b0f0 51 75 65 72 69 65 73 0a 2a 2a 0a 2a 2a 20 54 68  Queries.**.** Th
1b100 69 73 20 69 73 20 61 20 6c 65 67 61 63 79 20 69  is is a legacy i
1b110 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 69 73  nterface that is
1b120 20 70 72 65 73 65 72 76 65 64 20 66 6f 72 20 62   preserved for b
1b130 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69  ackwards compati
1b140 62 69 6c 69 74 79 2e 0a 2a 2a 20 55 73 65 20 6f  bility..** Use o
1b150 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  f this interface
1b160 20 69 73 20 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e   is not recommen
1b170 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e  ded..**.** Defin
1b180 69 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75  ition: A <b>resu
1b190 6c 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20  lt table</b> is 
1b1a0 6d 65 6d 6f 72 79 20 64 61 74 61 20 73 74 72 75  memory data stru
1b1b0 63 74 75 72 65 20 63 72 65 61 74 65 64 20 62 79  cture created by
1b1c0 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
1b1d0 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e  _get_table()] in
1b1e0 74 65 72 66 61 63 65 2e 20 20 41 20 72 65 73 75  terface.  A resu
1b1f0 6c 74 20 74 61 62 6c 65 20 72 65 63 6f 72 64 73  lt table records
1b200 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65   the.** complete
1b210 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 20 66   query results f
1b220 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  rom one or more 
1b230 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54  queries..**.** T
1b240 68 65 20 74 61 62 6c 65 20 63 6f 6e 63 65 70 74  he table concept
1b250 75 61 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d 62  ually has a numb
1b260 65 72 20 6f 66 20 72 6f 77 73 20 61 6e 64 20 63  er of rows and c
1b270 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20  olumns.  But.** 
1b280 74 68 65 73 65 20 6e 75 6d 62 65 72 73 20 61 72  these numbers ar
1b290 65 20 6e 6f 74 20 70 61 72 74 20 6f 66 20 74 68  e not part of th
1b2a0 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69  e result table i
1b2b0 74 73 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a  tself.  These.**
1b2c0 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6f 62 74   numbers are obt
1b2d0 61 69 6e 65 64 20 73 65 70 61 72 61 74 65 6c 79  ained separately
1b2e0 2e 20 20 4c 65 74 20 4e 20 62 65 20 74 68 65 20  .  Let N be the 
1b2f0 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a  number of rows.*
1b300 2a 20 61 6e 64 20 4d 20 62 65 20 74 68 65 20 6e  * and M be the n
1b310 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
1b320 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74  ..**.** A result
1b330 20 74 61 62 6c 65 20 69 73 20 61 6e 20 61 72 72   table is an arr
1b340 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74  ay of pointers t
1b350 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  o zero-terminate
1b360 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73 2e  d UTF-8 strings.
1b370 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 28 4e  .** There are (N
1b380 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69  +1)*M elements i
1b390 6e 20 74 68 65 20 61 72 72 61 79 2e 20 20 54 68  n the array.  Th
1b3a0 65 20 66 69 72 73 74 20 4d 20 70 6f 69 6e 74 65  e first M pointe
1b3b0 72 73 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a  rs point.** to z
1b3c0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73  ero-terminated s
1b3d0 74 72 69 6e 67 73 20 74 68 61 74 20 20 63 6f 6e  trings that  con
1b3e0 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f  tain the names o
1b3f0 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a  f the columns..*
1b400 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20  * The remaining 
1b410 65 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e  entries all poin
1b420 74 20 74 6f 20 71 75 65 72 79 20 72 65 73 75 6c  t to query resul
1b430 74 73 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73  ts.  NULL values
1b440 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55   result.** in NU
1b450 4c 4c 20 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c  LL pointers.  Al
1b460 6c 20 6f 74 68 65 72 20 76 61 6c 75 65 73 20 61  l other values a
1b470 72 65 20 69 6e 20 74 68 65 69 72 20 55 54 46 2d  re in their UTF-
1b480 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  8 zero-terminate
1b490 64 0a 2a 2a 20 73 74 72 69 6e 67 20 72 65 70 72  d.** string repr
1b4a0 65 73 65 6e 74 61 74 69 6f 6e 20 61 73 20 72 65  esentation as re
1b4b0 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
1b4c0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
1b4d0 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c  ]..**.** A resul
1b4e0 74 20 74 61 62 6c 65 20 6d 69 67 68 74 20 63 6f  t table might co
1b4f0 6e 73 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20  nsist of one or 
1b500 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  more memory allo
1b510 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69  cations..** It i
1b520 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 70 61  s not safe to pa
1b530 73 73 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c  ss a result tabl
1b540 65 20 64 69 72 65 63 74 6c 79 20 74 6f 20 5b 73  e directly to [s
1b550 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a  qlite3_free()]..
1b560 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c  ** A result tabl
1b570 65 20 73 68 6f 75 6c 64 20 62 65 20 64 65 61 6c  e should be deal
1b580 6c 6f 63 61 74 65 64 20 75 73 69 6e 67 20 5b 73  located using [s
1b590 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c  qlite3_free_tabl
1b5a0 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73  e()]..**.** ^(As
1b5b0 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 74   an example of t
1b5c0 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  he result table 
1b5d0 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73 65 20  format, suppose 
1b5e0 61 20 71 75 65 72 79 20 72 65 73 75 6c 74 0a 2a  a query result.*
1b5f0 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a  * is as follows:
1b600 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
1b610 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20  te><pre>.**     
1b620 20 20 20 4e 61 6d 65 20 20 20 20 20 20 20 20 7c     Name        |
1b630 20 41 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d   Age.**        -
1b640 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
1b650 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20  ------.**       
1b660 20 41 6c 69 63 65 20 20 20 20 20 20 20 7c 20 34   Alice       | 4
1b670 33 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f 62 20  3.**        Bob 
1b680 20 20 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20          | 28.** 
1b690 20 20 20 20 20 20 20 43 69 6e 64 79 20 20 20 20         Cindy    
1b6a0 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65     | 21.** </pre
1b6b0 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
1b6c0 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74  *.** There are t
1b6d0 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29  wo column (M==2)
1b6e0 20 61 6e 64 20 74 68 72 65 65 20 72 6f 77 73 20   and three rows 
1b6f0 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20 74 68  (N==3).  Thus th
1b700 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61 62 6c  e.** result tabl
1b710 65 20 68 61 73 20 38 20 65 6e 74 72 69 65 73 2e  e has 8 entries.
1b720 20 20 53 75 70 70 6f 73 65 20 74 68 65 20 72 65    Suppose the re
1b730 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 73 74  sult table is st
1b740 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72  ored.** in an ar
1b750 72 61 79 20 6e 61 6d 65 73 20 61 7a 52 65 73 75  ray names azResu
1b760 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52 65 73 75  lt.  Then azResu
1b770 6c 74 20 68 6f 6c 64 73 20 74 68 69 73 20 63 6f  lt holds this co
1b780 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  ntent:.**.** <bl
1b790 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
1b7a0 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
1b7b0 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65  t&#91;0] = "Name
1b7c0 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
1b7d0 65 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22  esult&#91;1] = "
1b7e0 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  Age";.**        
1b7f0 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 32 5d 20  azResult&#91;2] 
1b800 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20  = "Alice";.**   
1b810 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
1b820 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20  1;3] = "43";.** 
1b830 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
1b840 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a  #91;4] = "Bob";.
1b850 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
1b860 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22 32 38 22  lt&#91;5] = "28"
1b870 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
1b880 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22 43  sult&#91;6] = "C
1b890 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20  indy";.**       
1b8a0 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 37 5d   azResult&#91;7]
1b8b0 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72   = "21";.** </pr
1b8c0 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29  e></blockquote>)
1b8d0 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ^.**.** ^The sql
1b8e0 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
1b8f0 20 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61   function evalua
1b900 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a  tes one or more.
1b910 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70  ** semicolon-sep
1b920 61 72 61 74 65 64 20 53 51 4c 20 73 74 61 74 65  arated SQL state
1b930 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 7a 65 72  ments in the zer
1b940 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
1b950 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20  -8.** string of 
1b960 69 74 73 20 32 6e 64 20 70 61 72 61 6d 65 74 65  its 2nd paramete
1b970 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20  r and returns a 
1b980 72 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20  result table to 
1b990 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67  the.** pointer g
1b9a0 69 76 65 6e 20 69 6e 20 69 74 73 20 33 72 64 20  iven in its 3rd 
1b9b0 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
1b9c0 20 41 66 74 65 72 20 74 68 65 20 61 70 70 6c 69   After the appli
1b9d0 63 61 74 69 6f 6e 20 68 61 73 20 66 69 6e 69 73  cation has finis
1b9e0 68 65 64 20 77 69 74 68 20 74 68 65 20 72 65 73  hed with the res
1b9f0 75 6c 74 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ult from sqlite3
1ba00 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a  _get_table(),.**
1ba10 20 69 74 20 6d 75 73 74 20 70 61 73 73 20 74 68   it must pass th
1ba20 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 70  e result table p
1ba30 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ointer to sqlite
1ba40 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 20 69  3_free_table() i
1ba50 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65  n order to.** re
1ba60 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79  lease the memory
1ba70 20 74 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63   that was malloc
1ba80 65 64 2e 20 20 42 65 63 61 75 73 65 20 6f 66 20  ed.  Because of 
1ba90 74 68 65 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b  the way the.** [
1baa0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1bab0 5d 20 68 61 70 70 65 6e 73 20 77 69 74 68 69 6e  ] happens within
1bac0 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
1bad0 6c 65 28 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e  le(), the callin
1bae0 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75  g.** function mu
1baf0 73 74 20 6e 6f 74 20 74 72 79 20 74 6f 20 63 61  st not try to ca
1bb00 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ll [sqlite3_free
1bb10 28 29 5d 20 64 69 72 65 63 74 6c 79 2e 20 20 4f  ()] directly.  O
1bb20 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  nly.** [sqlite3_
1bb30 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 20 69 73  free_table()] is
1bb40 20 61 62 6c 65 20 74 6f 20 72 65 6c 65 61 73 65   able to release
1bb50 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70   the memory prop
1bb60 65 72 6c 79 20 61 6e 64 20 73 61 66 65 6c 79 2e  erly and safely.
1bb70 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
1bb80 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 69  e3_get_table() i
1bb90 6e 74 65 72 66 61 63 65 20 69 73 20 69 6d 70 6c  nterface is impl
1bba0 65 6d 65 6e 74 65 64 20 61 73 20 61 20 77 72 61  emented as a wra
1bbb0 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b  pper around.** [
1bbc0 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2e  sqlite3_exec()].
1bbd0 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65    The sqlite3_ge
1bbe0 74 5f 74 61 62 6c 65 28 29 20 72 6f 75 74 69 6e  t_table() routin
1bbf0 65 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20  e does not have 
1bc00 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79  access.** to any
1bc10 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 20 73   internal data s
1bc20 74 72 75 63 74 75 72 65 73 20 6f 66 20 53 51 4c  tructures of SQL
1bc30 69 74 65 2e 20 20 49 74 20 75 73 65 73 20 6f 6e  ite.  It uses on
1bc40 6c 79 20 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a  ly the public.**
1bc50 20 69 6e 74 65 72 66 61 63 65 20 64 65 66 69 6e   interface defin
1bc60 65 64 20 68 65 72 65 2e 20 20 41 73 20 61 20 63  ed here.  As a c
1bc70 6f 6e 73 65 71 75 65 6e 63 65 2c 20 65 72 72 6f  onsequence, erro
1bc80 72 73 20 74 68 61 74 20 6f 63 63 75 72 20 69 6e  rs that occur in
1bc90 20 74 68 65 0a 2a 2a 20 77 72 61 70 70 65 72 20   the.** wrapper 
1bca0 6c 61 79 65 72 20 6f 75 74 73 69 64 65 20 6f 66  layer outside of
1bcb0 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73   the internal [s
1bcc0 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 63  qlite3_exec()] c
1bcd0 61 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72  all are not.** r
1bce0 65 66 6c 65 63 74 65 64 20 69 6e 20 73 75 62 73  eflected in subs
1bcf0 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20  equent calls to 
1bd00 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65  [sqlite3_errcode
1bd10 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
1bd20 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f  e3_errmsg()]..*/
1bd30 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
1bd40 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
1bd50 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  e(.  sqlite3 *db
1bd60 2c 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e  ,          /* An
1bd70 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a   open database *
1bd80 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
1bd90 7a 53 71 6c 2c 20 20 20 20 20 2f 2a 20 53 51 4c  zSql,     /* SQL
1bda0 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64   to be evaluated
1bdb0 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 2a 70 61   */.  char ***pa
1bdc0 7a 52 65 73 75 6c 74 2c 20 20 20 20 2f 2a 20 52  zResult,    /* R
1bdd0 65 73 75 6c 74 73 20 6f 66 20 74 68 65 20 71 75  esults of the qu
1bde0 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e  ery */.  int *pn
1bdf0 52 6f 77 2c 20 20 20 20 20 20 20 20 20 20 20 2f  Row,           /
1be00 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75  * Number of resu
1be10 6c 74 20 72 6f 77 73 20 77 72 69 74 74 65 6e 20  lt rows written 
1be20 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70  here */.  int *p
1be30 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20  nColumn,        
1be40 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73  /* Number of res
1be50 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74  ult columns writ
1be60 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 63 68  ten here */.  ch
1be70 61 72 20 2a 2a 70 7a 45 72 72 6d 73 67 20 20 20  ar **pzErrmsg   
1be80 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67      /* Error msg
1be90 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f   written here */
1bea0 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  .);.SQLITE_API v
1beb0 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65  oid sqlite3_free
1bec0 5f 74 61 62 6c 65 28 63 68 61 72 20 2a 2a 72 65  _table(char **re
1bed0 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  sult);../*.** CA
1bee0 50 49 33 52 45 46 3a 20 46 6f 72 6d 61 74 74 65  PI3REF: Formatte
1bef0 64 20 53 74 72 69 6e 67 20 50 72 69 6e 74 69 6e  d String Printin
1bf00 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a  g Functions.**.*
1bf10 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
1bf20 20 61 72 65 20 77 6f 72 6b 2d 61 6c 69 6b 65 73   are work-alikes
1bf30 20 6f 66 20 74 68 65 20 22 70 72 69 6e 74 66 28   of the "printf(
1bf40 29 22 20 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e  )" family of fun
1bf50 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74  ctions.** from t
1bf60 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  he standard C li
1bf70 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  brary..**.** ^Th
1bf80 65 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74  e sqlite3_mprint
1bf90 66 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  f() and sqlite3_
1bfa0 76 6d 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69  vmprintf() routi
1bfb0 6e 65 73 20 77 72 69 74 65 20 74 68 65 69 72 0a  nes write their.
1bfc0 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 6f 20  ** results into 
1bfd0 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20  memory obtained 
1bfe0 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
1bff0 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68 65 20  lloc()]..** The 
1c000 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64  strings returned
1c010 20 62 79 20 74 68 65 73 65 20 74 77 6f 20 72 6f   by these two ro
1c020 75 74 69 6e 65 73 20 73 68 6f 75 6c 64 20 62 65  utines should be
1c030 0a 2a 2a 20 72 65 6c 65 61 73 65 64 20 62 79 20  .** released by 
1c040 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
1c050 2e 20 20 5e 42 6f 74 68 20 72 6f 75 74 69 6e 65  .  ^Both routine
1c060 73 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 4e 55  s return a.** NU
1c070 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 5b 73  LL pointer if [s
1c080 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
1c090 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c   is unable to al
1c0a0 6c 6f 63 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a  locate enough.**
1c0b0 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20   memory to hold 
1c0c0 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74  the resulting st
1c0d0 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  ring..**.** ^(Th
1c0e0 65 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e  e sqlite3_snprin
1c0f0 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20  tf() routine is 
1c100 73 69 6d 69 6c 61 72 20 74 6f 20 22 73 6e 70 72  similar to "snpr
1c110 69 6e 74 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20  intf()" from.** 
1c120 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c  the standard C l
1c130 69 62 72 61 72 79 2e 20 20 54 68 65 20 72 65 73  ibrary.  The res
1c140 75 6c 74 20 69 73 20 77 72 69 74 74 65 6e 20 69  ult is written i
1c150 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 75 66 66 65  nto the.** buffe
1c160 72 20 73 75 70 70 6c 69 65 64 20 61 73 20 74 68  r supplied as th
1c170 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
1c180 65 72 20 77 68 6f 73 65 20 73 69 7a 65 20 69 73  er whose size is
1c190 20 67 69 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65   given by.** the
1c1a0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
1c1b0 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20  . Note that the 
1c1c0 6f 72 64 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20  order of the.** 
1c1d0 66 69 72 73 74 20 74 77 6f 20 70 61 72 61 6d 65  first two parame
1c1e0 74 65 72 73 20 69 73 20 72 65 76 65 72 73 65 64  ters is reversed
1c1f0 20 66 72 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29   from snprintf()
1c200 2e 29 5e 20 20 54 68 69 73 20 69 73 20 61 6e 0a  .)^  This is an.
1c210 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c 20 61 63  ** historical ac
1c220 63 69 64 65 6e 74 20 74 68 61 74 20 63 61 6e 6e  cident that cann
1c230 6f 74 20 62 65 20 66 69 78 65 64 20 77 69 74 68  ot be fixed with
1c240 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20  out breaking.** 
1c250 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
1c260 69 62 69 6c 69 74 79 2e 20 20 5e 28 4e 6f 74 65  ibility.  ^(Note
1c270 20 61 6c 73 6f 20 74 68 61 74 20 73 71 6c 69 74   also that sqlit
1c280 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a  e3_snprintf().**
1c290 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
1c2a0 65 72 20 74 6f 20 69 74 73 20 62 75 66 66 65 72  er to its buffer
1c2b0 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20   instead of the 
1c2c0 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61  number of.** cha
1c2d0 72 61 63 74 65 72 73 20 61 63 74 75 61 6c 6c 79  racters actually
1c2e0 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68   written into th
1c2f0 65 20 62 75 66 66 65 72 2e 29 5e 20 20 57 65 20  e buffer.)^  We 
1c300 61 64 6d 69 74 20 74 68 61 74 0a 2a 2a 20 74 68  admit that.** th
1c310 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72  e number of char
1c320 61 63 74 65 72 73 20 77 72 69 74 74 65 6e 20 77  acters written w
1c330 6f 75 6c 64 20 62 65 20 61 20 6d 6f 72 65 20 75  ould be a more u
1c340 73 65 66 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20  seful return.** 
1c350 76 61 6c 75 65 20 62 75 74 20 77 65 20 63 61 6e  value but we can
1c360 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 69  not change the i
1c370 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
1c380 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
1c390 66 28 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f  f().** now witho
1c3a0 75 74 20 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70  ut breaking comp
1c3b0 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a  atibility..**.**
1c3c0 20 5e 41 73 20 6c 6f 6e 67 20 61 73 20 74 68 65   ^As long as the
1c3d0 20 62 75 66 66 65 72 20 73 69 7a 65 20 69 73 20   buffer size is 
1c3e0 67 72 65 61 74 65 72 20 74 68 61 6e 20 7a 65 72  greater than zer
1c3f0 6f 2c 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  o, sqlite3_snpri
1c400 6e 74 66 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74  ntf().** guarant
1c410 65 65 73 20 74 68 61 74 20 74 68 65 20 62 75 66  ees that the buf
1c420 66 65 72 20 69 73 20 61 6c 77 61 79 73 20 7a 65  fer is always ze
1c430 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20  ro-terminated.  
1c440 5e 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61  ^The first.** pa
1c450 72 61 6d 65 74 65 72 20 22 6e 22 20 69 73 20 74  rameter "n" is t
1c460 68 65 20 74 6f 74 61 6c 20 73 69 7a 65 20 6f 66  he total size of
1c470 20 74 68 65 20 62 75 66 66 65 72 2c 20 69 6e 63   the buffer, inc
1c480 6c 75 64 69 6e 67 20 73 70 61 63 65 20 66 6f 72  luding space for
1c490 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 20 74 65 72  .** the zero ter
1c4a0 6d 69 6e 61 74 6f 72 2e 20 20 53 6f 20 74 68 65  minator.  So the
1c4b0 20 6c 6f 6e 67 65 73 74 20 73 74 72 69 6e 67 20   longest string 
1c4c0 74 68 61 74 20 63 61 6e 20 62 65 20 63 6f 6d 70  that can be comp
1c4d0 6c 65 74 65 6c 79 0a 2a 2a 20 77 72 69 74 74 65  letely.** writte
1c4e0 6e 20 77 69 6c 6c 20 62 65 20 6e 2d 31 20 63 68  n will be n-1 ch
1c4f0 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  aracters..**.** 
1c500 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 73 6e  ^The sqlite3_vsn
1c510 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65  printf() routine
1c520 20 69 73 20 61 20 76 61 72 61 72 67 73 20 76 65   is a varargs ve
1c530 72 73 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33  rsion of sqlite3
1c540 5f 73 6e 70 72 69 6e 74 66 28 29 2e 0a 2a 2a 0a  _snprintf()..**.
1c550 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
1c560 73 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 20  s all implement 
1c570 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c 20  some additional 
1c580 66 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f 70  formatting.** op
1c590 74 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 75  tions that are u
1c5a0 73 65 66 75 6c 20 66 6f 72 20 63 6f 6e 73 74 72  seful for constr
1c5b0 75 63 74 69 6e 67 20 53 51 4c 20 73 74 61 74 65  ucting SQL state
1c5c0 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66  ments..** All of
1c5d0 20 74 68 65 20 75 73 75 61 6c 20 70 72 69 6e 74   the usual print
1c5e0 66 28 29 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f  f() formatting o
1c5f0 70 74 69 6f 6e 73 20 61 70 70 6c 79 2e 20 20 49  ptions apply.  I
1c600 6e 20 61 64 64 69 74 69 6f 6e 2c 20 74 68 65 72  n addition, ther
1c610 65 0a 2a 2a 20 69 73 20 61 72 65 20 22 25 71 22  e.** is are "%q"
1c620 2c 20 22 25 51 22 2c 20 61 6e 64 20 22 25 7a 22  , "%Q", and "%z"
1c630 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20   options..**.** 
1c640 5e 28 54 68 65 20 25 71 20 6f 70 74 69 6f 6e 20  ^(The %q option 
1c650 77 6f 72 6b 73 20 6c 69 6b 65 20 25 73 20 69 6e  works like %s in
1c660 20 74 68 61 74 20 69 74 20 73 75 62 73 74 69 74   that it substit
1c670 75 74 65 73 20 61 20 6e 75 6c 6c 2d 74 65 72 6d  utes a null-term
1c680 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67  inated.** string
1c690 20 66 72 6f 6d 20 74 68 65 20 61 72 67 75 6d 65   from the argume
1c6a0 6e 74 20 6c 69 73 74 2e 20 20 42 75 74 20 25 71  nt list.  But %q
1c6b0 20 61 6c 73 6f 20 64 6f 75 62 6c 65 73 20 65 76   also doubles ev
1c6c0 65 72 79 20 27 5c 27 27 20 63 68 61 72 61 63 74  ery '\'' charact
1c6d0 65 72 2e 0a 2a 2a 20 25 71 20 69 73 20 64 65 73  er..** %q is des
1c6e0 69 67 6e 65 64 20 66 6f 72 20 75 73 65 20 69 6e  igned for use in
1c6f0 73 69 64 65 20 61 20 73 74 72 69 6e 67 20 6c 69  side a string li
1c700 74 65 72 61 6c 2e 29 5e 20 20 42 79 20 64 6f 75  teral.)^  By dou
1c710 62 6c 69 6e 67 20 65 61 63 68 20 27 5c 27 27 0a  bling each '\''.
1c720 2a 2a 20 63 68 61 72 61 63 74 65 72 20 69 74 20  ** character it 
1c730 65 73 63 61 70 65 73 20 74 68 61 74 20 63 68 61  escapes that cha
1c740 72 61 63 74 65 72 20 61 6e 64 20 61 6c 6c 6f 77  racter and allow
1c750 73 20 69 74 20 74 6f 20 62 65 20 69 6e 73 65 72  s it to be inser
1c760 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20  ted into.** the 
1c770 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f  string..**.** Fo
1c780 72 20 65 78 61 6d 70 6c 65 2c 20 61 73 73 75 6d  r example, assum
1c790 65 20 74 68 65 20 73 74 72 69 6e 67 20 76 61 72  e the string var
1c7a0 69 61 62 6c 65 20 7a 54 65 78 74 20 63 6f 6e 74  iable zText cont
1c7b0 61 69 6e 73 20 74 65 78 74 20 61 73 20 66 6f 6c  ains text as fol
1c7c0 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lows:.**.** <blo
1c7d0 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
1c7e0 20 20 63 68 61 72 20 2a 7a 54 65 78 74 20 3d 20    char *zText = 
1c7f0 22 49 74 27 73 20 61 20 68 61 70 70 79 20 64 61  "It's a happy da
1c800 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  y!";.** </pre></
1c810 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
1c820 2a 20 4f 6e 65 20 63 61 6e 20 75 73 65 20 74 68  * One can use th
1c830 69 73 20 74 65 78 74 20 69 6e 20 61 6e 20 53 51  is text in an SQ
1c840 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20 66  L statement as f
1c850 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ollows:.**.** <b
1c860 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
1c870 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d  **  char *zSQL =
1c880 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66   sqlite3_mprintf
1c890 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61  ("INSERT INTO ta
1c8a0 62 6c 65 20 56 41 4c 55 45 53 28 27 25 71 27 29  ble VALUES('%q')
1c8b0 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73  ", zText);.**  s
1c8c0 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20  qlite3_exec(db, 
1c8d0 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a  zSQL, 0, 0, 0);.
1c8e0 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65  **  sqlite3_free
1c8f0 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65  (zSQL);.** </pre
1c900 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
1c910 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65  *.** Because the
1c920 20 25 71 20 66 6f 72 6d 61 74 20 73 74 72 69 6e   %q format strin
1c930 67 20 69 73 20 75 73 65 64 2c 20 74 68 65 20 27  g is used, the '
1c940 5c 27 27 20 63 68 61 72 61 63 74 65 72 20 69 6e  \'' character in
1c950 20 7a 54 65 78 74 0a 2a 2a 20 69 73 20 65 73 63   zText.** is esc
1c960 61 70 65 64 20 61 6e 64 20 74 68 65 20 53 51 4c  aped and the SQL
1c970 20 67 65 6e 65 72 61 74 65 64 20 69 73 20 61 73   generated is as
1c980 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20   follows:.**.** 
1c990 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
1c9a0 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54  >.**  INSERT INT
1c9b0 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28  O table1 VALUES(
1c9c0 27 49 74 27 27 73 20 61 20 68 61 70 70 79 20 64  'It''s a happy d
1c9d0 61 79 21 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  ay!').** </pre><
1c9e0 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
1c9f0 2a 2a 20 54 68 69 73 20 69 73 20 63 6f 72 72 65  ** This is corre
1ca00 63 74 2e 20 20 48 61 64 20 77 65 20 75 73 65 64  ct.  Had we used
1ca10 20 25 73 20 69 6e 73 74 65 61 64 20 6f 66 20 25   %s instead of %
1ca20 71 2c 20 74 68 65 20 67 65 6e 65 72 61 74 65 64  q, the generated
1ca30 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68 61   SQL.** would ha
1ca40 76 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20 74  ve looked like t
1ca50 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  his:.**.** <bloc
1ca60 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
1ca70 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62   INSERT INTO tab
1ca80 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 73  le1 VALUES('It's
1ca90 20 61 20 68 61 70 70 79 20 64 61 79 21 27 29 3b   a happy day!');
1caa0 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
1cab0 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68  kquote>.**.** Th
1cac0 69 73 20 73 65 63 6f 6e 64 20 65 78 61 6d 70 6c  is second exampl
1cad0 65 20 69 73 20 61 6e 20 53 51 4c 20 73 79 6e 74  e is an SQL synt
1cae0 61 78 20 65 72 72 6f 72 2e 20 20 41 73 20 61 20  ax error.  As a 
1caf0 67 65 6e 65 72 61 6c 20 72 75 6c 65 20 79 6f 75  general rule you
1cb00 20 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77 61 79   should.** alway
1cb10 73 20 75 73 65 20 25 71 20 69 6e 73 74 65 61 64  s use %q instead
1cb20 20 6f 66 20 25 73 20 77 68 65 6e 20 69 6e 73 65   of %s when inse
1cb30 72 74 69 6e 67 20 74 65 78 74 20 69 6e 74 6f 20  rting text into 
1cb40 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c  a string literal
1cb50 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 51  ..**.** ^(The %Q
1cb60 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69   option works li
1cb70 6b 65 20 25 71 20 65 78 63 65 70 74 20 69 74 20  ke %q except it 
1cb80 61 6c 73 6f 20 61 64 64 73 20 73 69 6e 67 6c 65  also adds single
1cb90 20 71 75 6f 74 65 73 20 61 72 6f 75 6e 64 0a 2a   quotes around.*
1cba0 2a 20 74 68 65 20 6f 75 74 73 69 64 65 20 6f 66  * the outside of
1cbb0 20 74 68 65 20 74 6f 74 61 6c 20 73 74 72 69 6e   the total strin
1cbc0 67 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79  g.  Additionally
1cbd0 2c 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74  , if the paramet
1cbe0 65 72 20 69 6e 20 74 68 65 0a 2a 2a 20 61 72 67  er in the.** arg
1cbf0 75 6d 65 6e 74 20 6c 69 73 74 20 69 73 20 61 20  ument list is a 
1cc00 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 25 51  NULL pointer, %Q
1cc10 20 73 75 62 73 74 69 74 75 74 65 73 20 74 68 65   substitutes the
1cc20 20 74 65 78 74 20 22 4e 55 4c 4c 22 20 28 77 69   text "NULL" (wi
1cc30 74 68 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c 65 20  thout.** single 
1cc40 71 75 6f 74 65 73 29 2e 29 5e 20 20 53 6f 2c 20  quotes).)^  So, 
1cc50 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 6f 6e 65  for example, one
1cc60 20 63 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a   could say:.**.*
1cc70 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
1cc80 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53  re>.**  char *zS
1cc90 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72  QL = sqlite3_mpr
1cca0 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54  intf("INSERT INT
1ccb0 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28 25  O table VALUES(%
1ccc0 51 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20  Q)", zText);.** 
1ccd0 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62   sqlite3_exec(db
1cce0 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29  , zSQL, 0, 0, 0)
1ccf0 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72  ;.**  sqlite3_fr
1cd00 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70  ee(zSQL);.** </p
1cd10 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
1cd20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20  .**.** The code 
1cd30 61 62 6f 76 65 20 77 69 6c 6c 20 72 65 6e 64 65  above will rende
1cd40 72 20 61 20 63 6f 72 72 65 63 74 20 53 51 4c 20  r a correct SQL 
1cd50 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65  statement in the
1cd60 20 7a 53 51 4c 0a 2a 2a 20 76 61 72 69 61 62 6c   zSQL.** variabl
1cd70 65 20 65 76 65 6e 20 69 66 20 74 68 65 20 7a 54  e even if the zT
1cd80 65 78 74 20 76 61 72 69 61 62 6c 65 20 69 73 20  ext variable is 
1cd90 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
1cda0 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 22 25 7a 22  **.** ^(The "%z"
1cdb0 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69   formatting opti
1cdc0 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 22 25  on works like "%
1cdd0 73 22 20 62 75 74 20 77 69 74 68 20 74 68 65 0a  s" but with the.
1cde0 2a 2a 20 61 64 64 69 74 69 6f 6e 20 74 68 61 74  ** addition that
1cdf0 20 61 66 74 65 72 20 74 68 65 20 73 74 72 69 6e   after the strin
1ce00 67 20 68 61 73 20 62 65 65 6e 20 72 65 61 64 20  g has been read 
1ce10 61 6e 64 20 63 6f 70 69 65 64 20 69 6e 74 6f 0a  and copied into.
1ce20 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 2c 20 5b  ** the result, [
1ce30 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
1ce40 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65  is called on the
1ce50 20 69 6e 70 75 74 20 73 74 72 69 6e 67 2e 29 5e   input string.)^
1ce60 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  .*/.SQLITE_API c
1ce70 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6d 70 72  har *sqlite3_mpr
1ce80 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a  intf(const char*
1ce90 2c 2e 2e 2e 29 3b 0a 53 51 4c 49 54 45 5f 41 50  ,...);.SQLITE_AP
1cea0 49 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  I char *sqlite3_
1ceb0 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63  vmprintf(const c
1cec0 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a  har*, va_list);.
1ced0 53 51 4c 49 54 45 5f 41 50 49 20 63 68 61 72 20  SQLITE_API char 
1cee0 2a 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  *sqlite3_snprint
1cef0 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73  f(int,char*,cons
1cf00 74 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 53  t char*, ...);.S
1cf10 51 4c 49 54 45 5f 41 50 49 20 63 68 61 72 20 2a  QLITE_API char *
1cf20 73 71 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74  sqlite3_vsnprint
1cf30 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73  f(int,char*,cons
1cf40 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74  t char*, va_list
1cf50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1cf60 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63  EF: Memory Alloc
1cf70 61 74 69 6f 6e 20 53 75 62 73 79 73 74 65 6d 0a  ation Subsystem.
1cf80 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65  **.** The SQLite
1cf90 20 63 6f 72 65 20 75 73 65 73 20 74 68 65 73 65   core uses these
1cfa0 20 74 68 72 65 65 20 72 6f 75 74 69 6e 65 73 20   three routines 
1cfb0 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f  for all of its o
1cfc0 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d  wn.** internal m
1cfd0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
1cfe0 20 6e 65 65 64 73 2e 20 22 43 6f 72 65 22 20 69   needs. "Core" i
1cff0 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 73  n the previous s
1d000 65 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 20  entence.** does 
1d010 6e 6f 74 20 69 6e 63 6c 75 64 65 20 6f 70 65 72  not include oper
1d020 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65  ating-system spe
1d030 63 69 66 69 63 20 56 46 53 20 69 6d 70 6c 65 6d  cific VFS implem
1d040 65 6e 74 61 74 69 6f 6e 2e 20 20 54 68 65 0a 2a  entation.  The.*
1d050 2a 20 57 69 6e 64 6f 77 73 20 56 46 53 20 75 73  * Windows VFS us
1d060 65 73 20 6e 61 74 69 76 65 20 6d 61 6c 6c 6f 63  es native malloc
1d070 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 66 6f  () and free() fo
1d080 72 20 73 6f 6d 65 20 6f 70 65 72 61 74 69 6f 6e  r some operation
1d090 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  s..**.** ^The sq
1d0a0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72  lite3_malloc() r
1d0b0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61  outine returns a
1d0c0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 62 6c   pointer to a bl
1d0d0 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79  ock.** of memory
1d0e0 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65   at least N byte
1d0f0 73 20 69 6e 20 6c 65 6e 67 74 68 2c 20 77 68 65  s in length, whe
1d100 72 65 20 4e 20 69 73 20 74 68 65 20 70 61 72 61  re N is the para
1d110 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 73 71  meter..** ^If sq
1d120 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69  lite3_malloc() i
1d130 73 20 75 6e 61 62 6c 65 20 74 6f 20 6f 62 74 61  s unable to obta
1d140 69 6e 20 73 75 66 66 69 63 69 65 6e 74 20 66 72  in sufficient fr
1d150 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 74  ee.** memory, it
1d160 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20   returns a NULL 
1d170 70 6f 69 6e 74 65 72 2e 20 20 5e 49 66 20 74 68  pointer.  ^If th
1d180 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20 74 6f  e parameter N to
1d190 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  .** sqlite3_mall
1d1a0 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 20  oc() is zero or 
1d1b0 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 73 71  negative then sq
1d1c0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72  lite3_malloc() r
1d1d0 65 74 75 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c  eturns.** a NULL
1d1e0 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
1d1f0 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33  ^Calling sqlite3
1d200 5f 66 72 65 65 28 29 20 77 69 74 68 20 61 20 70  _free() with a p
1d210 6f 69 6e 74 65 72 20 70 72 65 76 69 6f 75 73 6c  ointer previousl
1d220 79 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79  y returned.** by
1d230 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1d240 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61  ) or sqlite3_rea
1d250 6c 6c 6f 63 28 29 20 72 65 6c 65 61 73 65 73 20  lloc() releases 
1d260 74 68 61 74 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a  that memory so.*
1d270 2a 20 74 68 61 74 20 69 74 20 6d 69 67 68 74 20  * that it might 
1d280 62 65 20 72 65 75 73 65 64 2e 20 20 5e 54 68 65  be reused.  ^The
1d290 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
1d2a0 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a 20 61 20  routine is.** a 
1d2b0 6e 6f 2d 6f 70 20 69 66 20 69 73 20 63 61 6c 6c  no-op if is call
1d2c0 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70  ed with a NULL p
1d2d0 6f 69 6e 74 65 72 2e 20 20 50 61 73 73 69 6e 67  ointer.  Passing
1d2e0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a   a NULL pointer.
1d2f0 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72  ** to sqlite3_fr
1d300 65 65 28 29 20 69 73 20 68 61 72 6d 6c 65 73 73  ee() is harmless
1d310 2e 20 20 41 66 74 65 72 20 62 65 69 6e 67 20 66  .  After being f
1d320 72 65 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20  reed, memory.** 
1d330 73 68 6f 75 6c 64 20 6e 65 69 74 68 65 72 20 62  should neither b
1d340 65 20 72 65 61 64 20 6e 6f 72 20 77 72 69 74 74  e read nor writt
1d350 65 6e 2e 20 20 45 76 65 6e 20 72 65 61 64 69 6e  en.  Even readin
1d360 67 20 70 72 65 76 69 6f 75 73 6c 79 20 66 72 65  g previously fre
1d370 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69 67  ed.** memory mig
1d380 68 74 20 72 65 73 75 6c 74 20 69 6e 20 61 20 73  ht result in a s
1d390 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c  egmentation faul
1d3a0 74 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72  t or other sever
1d3b0 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f  e error..** Memo
1d3c0 72 79 20 63 6f 72 72 75 70 74 69 6f 6e 2c 20 61  ry corruption, a
1d3d0 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61   segmentation fa
1d3e0 75 6c 74 2c 20 6f 72 20 6f 74 68 65 72 20 73 65  ult, or other se
1d3f0 76 65 72 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 69  vere error.** mi
1d400 67 68 74 20 72 65 73 75 6c 74 20 69 66 20 73 71  ght result if sq
1d410 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 73 20  lite3_free() is 
1d420 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 6e 6f  called with a no
1d430 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  n-NULL pointer t
1d440 68 61 74 0a 2a 2a 20 77 61 73 20 6e 6f 74 20 6f  hat.** was not o
1d450 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c  btained from sql
1d460 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72  ite3_malloc() or
1d470 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1d480 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  ()..**.** ^(The 
1d490 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1d4a0 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65  ) interface atte
1d4b0 6d 70 74 73 20 74 6f 20 72 65 73 69 7a 65 20 61  mpts to resize a
1d4c0 0a 2a 2a 20 70 72 69 6f 72 20 6d 65 6d 6f 72 79  .** prior memory
1d4d0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62   allocation to b
1d4e0 65 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74  e at least N byt
1d4f0 65 73 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74  es, where N is t
1d500 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72  he.** second par
1d510 61 6d 65 74 65 72 2e 20 20 54 68 65 20 6d 65 6d  ameter.  The mem
1d520 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74  ory allocation t
1d530 6f 20 62 65 20 72 65 73 69 7a 65 64 20 69 73 20  o be resized is 
1d540 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72  the first.** par
1d550 61 6d 65 74 65 72 2e 29 5e 20 5e 20 49 66 20 74  ameter.)^ ^ If t
1d560 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
1d570 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65  er to sqlite3_re
1d580 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 20  alloc().** is a 
1d590 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65  NULL pointer the
1d5a0 6e 20 69 74 73 20 62 65 68 61 76 69 6f 72 20 69  n its behavior i
1d5b0 73 20 69 64 65 6e 74 69 63 61 6c 20 74 6f 20 63  s identical to c
1d5c0 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65  alling.** sqlite
1d5d0 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 77 68 65 72  3_malloc(N) wher
1d5e0 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e  e N is the secon
1d5f0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
1d600 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1d610 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 65 63  ..** ^If the sec
1d620 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ond parameter to
1d630 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1d640 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a  () is zero or.**
1d650 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 74   negative then t
1d660 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 65  he behavior is e
1d670 78 61 63 74 6c 79 20 74 68 65 20 73 61 6d 65 20  xactly the same 
1d680 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71  as calling.** sq
1d690 6c 69 74 65 33 5f 66 72 65 65 28 50 29 20 77 68  lite3_free(P) wh
1d6a0 65 72 65 20 50 20 69 73 20 74 68 65 20 66 69 72  ere P is the fir
1d6b0 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
1d6c0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1d6d0 29 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f 72  )..** ^sqlite3_r
1d6e0 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73  ealloc() returns
1d6f0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
1d700 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
1d710 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74  n.** of at least
1d720 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65   N bytes in size
1d730 20 6f 72 20 4e 55 4c 4c 20 69 66 20 73 75 66 66   or NULL if suff
1d740 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 69 73  icient memory is
1d750 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a   unavailable..**
1d760 20 5e 49 66 20 4d 20 69 73 20 74 68 65 20 73 69   ^If M is the si
1d770 7a 65 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20  ze of the prior 
1d780 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e  allocation, then
1d790 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73 0a   min(N,M) bytes.
1d7a0 2a 2a 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20  ** of the prior 
1d7b0 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20 63  allocation are c
1d7c0 6f 70 69 65 64 20 69 6e 74 6f 20 74 68 65 20 62  opied into the b
1d7d0 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66 66  eginning of buff
1d7e0 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62  er returned.** b
1d7f0 79 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  y sqlite3_reallo
1d800 63 28 29 20 61 6e 64 20 74 68 65 20 70 72 69 6f  c() and the prio
1d810 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20  r allocation is 
1d820 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 73 71  freed..** ^If sq
1d830 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20  lite3_realloc() 
1d840 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2c 20 74 68  returns NULL, th
1d850 65 6e 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c  en the prior all
1d860 6f 63 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6e 6f  ocation.** is no
1d870 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  t freed..**.** ^
1d880 54 68 65 20 6d 65 6d 6f 72 79 20 72 65 74 75 72  The memory retur
1d890 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d  ned by sqlite3_m
1d8a0 61 6c 6c 6f 63 28 29 20 61 6e 64 20 73 71 6c 69  alloc() and sqli
1d8b0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a  te3_realloc().**
1d8c0 20 69 73 20 61 6c 77 61 79 73 20 61 6c 69 67 6e   is always align
1d8d0 65 64 20 74 6f 20 61 74 20 6c 65 61 73 74 20 61  ed to at least a
1d8e0 6e 20 38 20 62 79 74 65 20 62 6f 75 6e 64 61 72  n 8 byte boundar
1d8f0 79 2c 20 6f 72 20 74 6f 20 61 0a 2a 2a 20 34 20  y, or to a.** 4 
1d900 62 79 74 65 20 62 6f 75 6e 64 61 72 79 20 69 66  byte boundary if
1d910 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 34 5f 42   the [SQLITE_4_B
1d920 59 54 45 5f 41 4c 49 47 4e 45 44 5f 4d 41 4c 4c  YTE_ALIGNED_MALL
1d930 4f 43 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  OC] compile-time
1d940 0a 2a 2a 20 6f 70 74 69 6f 6e 20 69 73 20 75 73  .** option is us
1d950 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c  ed..**.** In SQL
1d960 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e  ite version 3.5.
1d970 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74 20  0 and 3.5.1, it 
1d980 77 61 73 20 70 6f 73 73 69 62 6c 65 20 74 6f 20  was possible to 
1d990 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53 51  define.** the SQ
1d9a0 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59  LITE_OMIT_MEMORY
1d9b0 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69 63  _ALLOCATION whic
1d9c0 68 20 77 6f 75 6c 64 20 63 61 75 73 65 20 74 68  h would cause th
1d9d0 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d  e built-in.** im
1d9e0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
1d9f0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74  these routines t
1da00 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e 20 20 54  o be omitted.  T
1da10 68 61 74 20 63 61 70 61 62 69 6c 69 74 79 0a 2a  hat capability.*
1da20 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 70  * is no longer p
1da30 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20 62  rovided.  Only b
1da40 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61  uilt-in memory a
1da50 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20 62 65  llocators can be
1da60 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   used..**.** The
1da70 20 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65   Windows OS inte
1da80 72 66 61 63 65 20 6c 61 79 65 72 20 63 61 6c 6c  rface layer call
1da90 73 0a 2a 2a 20 74 68 65 20 73 79 73 74 65 6d 20  s.** the system 
1daa0 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65  malloc() and fre
1dab0 65 28 29 20 64 69 72 65 63 74 6c 79 20 77 68 65  e() directly whe
1dac0 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a 20  n converting.** 
1dad0 66 69 6c 65 6e 61 6d 65 73 20 62 65 74 77 65 65  filenames betwee
1dae0 6e 20 74 68 65 20 55 54 46 2d 38 20 65 6e 63 6f  n the UTF-8 enco
1daf0 64 69 6e 67 20 75 73 65 64 20 62 79 20 53 51 4c  ding used by SQL
1db00 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74 65  ite.** and whate
1db10 76 65 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e 63  ver filename enc
1db20 6f 64 69 6e 67 20 69 73 20 75 73 65 64 20 62 79  oding is used by
1db30 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20   the particular 
1db40 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 61  Windows.** insta
1db50 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79  llation.  Memory
1db60 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f   allocation erro
1db70 72 73 20 61 72 65 20 64 65 74 65 63 74 65 64 2c  rs are detected,
1db80 20 62 75 74 0a 2a 2a 20 74 68 65 79 20 61 72 65   but.** they are
1db90 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 20 61   reported back a
1dba0 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  s [SQLITE_CANTOP
1dbb0 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54  EN] or.** [SQLIT
1dbc0 45 5f 49 4f 45 52 52 5d 20 72 61 74 68 65 72 20  E_IOERR] rather 
1dbd0 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d  than [SQLITE_NOM
1dbe0 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70  EM]..**.** The p
1dbf0 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 73  ointer arguments
1dc00 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65   to [sqlite3_fre
1dc10 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
1dc20 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20  3_realloc()].** 
1dc30 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20 4e  must be either N
1dc40 55 4c 4c 20 6f 72 20 65 6c 73 65 20 70 6f 69 6e  ULL or else poin
1dc50 74 65 72 73 20 6f 62 74 61 69 6e 65 64 20 66 72  ters obtained fr
1dc60 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a 20 69 6e  om a prior.** in
1dc70 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c  vocation of [sql
1dc80 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f  ite3_malloc()] o
1dc90 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  r [sqlite3_reall
1dca0 6f 63 28 29 5d 20 74 68 61 74 20 68 61 76 65 0a  oc()] that have.
1dcb0 2a 2a 20 6e 6f 74 20 79 65 74 20 62 65 65 6e 20  ** not yet been 
1dcc0 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20  released..**.** 
1dcd0 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
1dce0 6d 75 73 74 20 6e 6f 74 20 72 65 61 64 20 6f 72  must not read or
1dcf0 20 77 72 69 74 65 20 61 6e 79 20 70 61 72 74 20   write any part 
1dd00 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f 66  of.** a block of
1dd10 20 6d 65 6d 6f 72 79 20 61 66 74 65 72 20 69 74   memory after it
1dd20 20 68 61 73 20 62 65 65 6e 20 72 65 6c 65 61 73   has been releas
1dd30 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  ed using.** [sql
1dd40 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 72 20  ite3_free()] or 
1dd50 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
1dd60 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ()]..*/.SQLITE_A
1dd70 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  PI void *sqlite3
1dd80 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 53 51  _malloc(int);.SQ
1dd90 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73  LITE_API void *s
1dda0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76  qlite3_realloc(v
1ddb0 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49  oid*, int);.SQLI
1ddc0 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69  TE_API void sqli
1ddd0 74 65 33 5f 66 72 65 65 28 76 6f 69 64 2a 29 3b  te3_free(void*);
1dde0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1ddf0 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74  : Memory Allocat
1de00 6f 72 20 53 74 61 74 69 73 74 69 63 73 0a 2a 2a  or Statistics.**
1de10 0a 2a 2a 20 53 51 4c 69 74 65 20 70 72 6f 76 69  .** SQLite provi
1de20 64 65 73 20 74 68 65 73 65 20 74 77 6f 20 69 6e  des these two in
1de30 74 65 72 66 61 63 65 73 20 66 6f 72 20 72 65 70  terfaces for rep
1de40 6f 72 74 69 6e 67 20 6f 6e 20 74 68 65 20 73 74  orting on the st
1de50 61 74 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  atus.** of the [
1de60 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1de70 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ], [sqlite3_free
1de80 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ()], and [sqlite
1de90 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20  3_realloc()].** 
1dea0 72 6f 75 74 69 6e 65 73 2c 20 77 68 69 63 68 20  routines, which 
1deb0 66 6f 72 6d 20 74 68 65 20 62 75 69 6c 74 2d 69  form the built-i
1dec0 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  n memory allocat
1ded0 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a 2a  ion subsystem..*
1dee0 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74  *.** ^The [sqlit
1def0 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
1df00 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ] routine return
1df10 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
1df20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f  bytes.** of memo
1df30 72 79 20 63 75 72 72 65 6e 74 6c 79 20 6f 75 74  ry currently out
1df40 73 74 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63  standing (malloc
1df50 65 64 20 62 75 74 20 6e 6f 74 20 66 72 65 65 64  ed but not freed
1df60 29 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69  )..** ^The [sqli
1df70 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
1df80 61 74 65 72 28 29 5d 20 72 6f 75 74 69 6e 65 20  ater()] routine 
1df90 72 65 74 75 72 6e 73 20 74 68 65 20 6d 61 78 69  returns the maxi
1dfa0 6d 75 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20  mum.** value of 
1dfb0 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
1dfc0 75 73 65 64 28 29 5d 20 73 69 6e 63 65 20 74 68  used()] since th
1dfd0 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72  e high-water mar
1dfe0 6b 0a 2a 2a 20 77 61 73 20 6c 61 73 74 20 72 65  k.** was last re
1dff0 73 65 74 2e 20 20 5e 54 68 65 20 76 61 6c 75 65  set.  ^The value
1e000 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  s returned by [s
1e010 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
1e020 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71  ed()] and.** [sq
1e030 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
1e040 68 77 61 74 65 72 28 29 5d 20 69 6e 63 6c 75 64  hwater()] includ
1e050 65 20 61 6e 79 20 6f 76 65 72 68 65 61 64 0a 2a  e any overhead.*
1e060 2a 20 61 64 64 65 64 20 62 79 20 53 51 4c 69 74  * added by SQLit
1e070 65 20 69 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65  e in its impleme
1e080 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69  ntation of [sqli
1e090 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a  te3_malloc()],.*
1e0a0 2a 20 62 75 74 20 6e 6f 74 20 6f 76 65 72 68 65  * but not overhe
1e0b0 61 64 20 61 64 64 65 64 20 62 79 20 74 68 65 20  ad added by the 
1e0c0 61 6e 79 20 75 6e 64 65 72 6c 79 69 6e 67 20 73  any underlying s
1e0d0 79 73 74 65 6d 20 6c 69 62 72 61 72 79 0a 2a 2a  ystem library.**
1e0e0 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 5b   routines that [
1e0f0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1e100 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a  ] may call..**.*
1e110 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 68 69  * ^The memory hi
1e120 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 20 69 73  gh-water mark is
1e130 20 72 65 73 65 74 20 74 6f 20 74 68 65 20 63 75   reset to the cu
1e140 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a  rrent value of.*
1e150 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  * [sqlite3_memor
1e160 79 5f 75 73 65 64 28 29 5d 20 69 66 20 61 6e 64  y_used()] if and
1e170 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 70 61 72   only if the par
1e180 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71  ameter to.** [sq
1e190 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
1e1a0 68 77 61 74 65 72 28 29 5d 20 69 73 20 74 72 75  hwater()] is tru
1e1b0 65 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 20 72  e.  ^The value r
1e1c0 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 5b 73  eturned.** by [s
1e1d0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
1e1e0 67 68 77 61 74 65 72 28 31 29 5d 20 69 73 20 74  ghwater(1)] is t
1e1f0 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61  he high-water ma
1e200 72 6b 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 74  rk.** prior to t
1e210 68 65 20 72 65 73 65 74 2e 0a 2a 2f 0a 53 51 4c  he reset..*/.SQL
1e220 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f  ITE_API sqlite3_
1e230 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65  int64 sqlite3_me
1e240 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69 64 29 3b  mory_used(void);
1e250 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69  .SQLITE_API sqli
1e260 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
1e270 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
1e280 65 72 28 69 6e 74 20 72 65 73 65 74 46 6c 61 67  er(int resetFlag
1e290 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1e2a0 45 46 3a 20 50 73 65 75 64 6f 2d 52 61 6e 64 6f  EF: Pseudo-Rando
1e2b0 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65 72 61 74  m Number Generat
1e2c0 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  or.**.** SQLite 
1e2d0 63 6f 6e 74 61 69 6e 73 20 61 20 68 69 67 68 2d  contains a high-
1e2e0 71 75 61 6c 69 74 79 20 70 73 65 75 64 6f 2d 72  quality pseudo-r
1e2f0 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67 65 6e  andom number gen
1e300 65 72 61 74 6f 72 20 28 50 52 4e 47 29 20 75 73  erator (PRNG) us
1e310 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63 74 20  ed to.** select 
1e320 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 44 20 7c 20  random [ROWID | 
1e330 52 4f 57 49 44 73 5d 20 77 68 65 6e 20 69 6e 73  ROWIDs] when ins
1e340 65 72 74 69 6e 67 20 6e 65 77 20 72 65 63 6f 72  erting new recor
1e350 64 73 20 69 6e 74 6f 20 61 20 74 61 62 6c 65 20  ds into a table 
1e360 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20  that.** already 
1e370 75 73 65 73 20 74 68 65 20 6c 61 72 67 65 73 74  uses the largest
1e380 20 70 6f 73 73 69 62 6c 65 20 5b 52 4f 57 49 44   possible [ROWID
1e390 5d 2e 20 20 54 68 65 20 50 52 4e 47 20 69 73 20  ].  The PRNG is 
1e3a0 61 6c 73 6f 20 75 73 65 64 20 66 6f 72 0a 2a 2a  also used for.**
1e3b0 20 74 68 65 20 62 75 69 6c 64 2d 69 6e 20 72 61   the build-in ra
1e3c0 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61 6e 64 6f  ndom() and rando
1e3d0 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66 75 6e 63  mblob() SQL func
1e3e0 74 69 6f 6e 73 2e 20 20 54 68 69 73 20 69 6e 74  tions.  This int
1e3f0 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 0a 2a 2a  erface allows.**
1e400 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 6f   applications to
1e410 20 61 63 63 65 73 73 20 74 68 65 20 73 61 6d 65   access the same
1e420 20 50 52 4e 47 20 66 6f 72 20 6f 74 68 65 72 20   PRNG for other 
1e430 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20  purposes..**.** 
1e440 5e 41 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20  ^A call to this 
1e450 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20 4e  routine stores N
1e460 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d   bytes of random
1e470 6e 65 73 73 20 69 6e 74 6f 20 62 75 66 66 65 72  ness into buffer
1e480 20 50 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66   P..**.** ^The f
1e490 69 72 73 74 20 74 69 6d 65 20 74 68 69 73 20 72  irst time this r
1e4a0 6f 75 74 69 6e 65 20 69 73 20 69 6e 76 6f 6b 65  outine is invoke
1e4b0 64 20 28 65 69 74 68 65 72 20 69 6e 74 65 72 6e  d (either intern
1e4c0 61 6c 6c 79 20 6f 72 20 62 79 0a 2a 2a 20 74 68  ally or by.** th
1e4d0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 29 20 74  e application) t
1e4e0 68 65 20 50 52 4e 47 20 69 73 20 73 65 65 64 65  he PRNG is seede
1e4f0 64 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65  d using randomne
1e500 73 73 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66  ss obtained.** f
1e510 72 6f 6d 20 74 68 65 20 78 52 61 6e 64 6f 6d 6e  rom the xRandomn
1e520 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68  ess method of th
1e530 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74  e default [sqlit
1e540 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a  e3_vfs] object..
1e550 2a 2a 20 5e 4f 6e 20 61 6c 6c 20 73 75 62 73 65  ** ^On all subse
1e560 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e  quent invocation
1e570 73 2c 20 74 68 65 20 70 73 65 75 64 6f 2d 72 61  s, the pseudo-ra
1e580 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67 65 6e 65  ndomness is gene
1e590 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65 72 6e 61  rated.** interna
1e5a0 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f 75 74 20  lly and without 
1e5b0 72 65 63 6f 75 72 73 65 20 74 6f 20 74 68 65 20  recourse to the 
1e5c0 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 52  [sqlite3_vfs] xR
1e5d0 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74  andomness.** met
1e5e0 68 6f 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  hod..*/.SQLITE_A
1e5f0 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  PI void sqlite3_
1e600 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e 74 20 4e  randomness(int N
1e610 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a  , void *P);../*.
1e620 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d  ** CAPI3REF: Com
1e630 70 69 6c 65 2d 54 69 6d 65 20 41 75 74 68 6f 72  pile-Time Author
1e640 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b  ization Callback
1e650 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f  s.**.** ^This ro
1e660 75 74 69 6e 65 20 72 65 67 69 73 74 65 72 73 20  utine registers 
1e670 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  an authorizer ca
1e680 6c 6c 62 61 63 6b 20 77 69 74 68 20 61 20 70 61  llback with a pa
1e690 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74  rticular.** [dat
1e6a0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1e6b0 5d 2c 20 73 75 70 70 6c 69 65 64 20 69 6e 20 74  ], supplied in t
1e6c0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
1e6d0 74 2e 0a 2a 2a 20 5e 54 68 65 20 61 75 74 68 6f  t..** ^The autho
1e6e0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
1e6f0 73 20 69 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c  s invoked as SQL
1e700 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20   statements are 
1e710 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a  being compiled.*
1e720 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72  * by [sqlite3_pr
1e730 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20  epare()] or its 
1e740 76 61 72 69 61 6e 74 73 20 5b 73 71 6c 69 74 65  variants [sqlite
1e750 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c  3_prepare_v2()],
1e760 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
1e770 70 61 72 65 31 36 28 29 5d 20 61 6e 64 20 5b 73  pare16()] and [s
1e780 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
1e790 5f 76 32 28 29 5d 2e 20 20 5e 41 74 20 76 61 72  _v2()].  ^At var
1e7a0 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64  ious.** points d
1e7b0 75 72 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c  uring the compil
1e7c0 61 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61  ation process, a
1e7d0 73 20 6c 6f 67 69 63 20 69 73 20 62 65 69 6e 67  s logic is being
1e7e0 20 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70   created.** to p
1e7f0 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 61  erform various a
1e800 63 74 69 6f 6e 73 2c 20 74 68 65 20 61 75 74 68  ctions, the auth
1e810 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1e820 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a  is invoked to.**
1e830 20 73 65 65 20 69 66 20 74 68 6f 73 65 20 61 63   see if those ac
1e840 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65  tions are allowe
1e850 64 2e 20 20 5e 54 68 65 20 61 75 74 68 6f 72 69  d.  ^The authori
1e860 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f  zer callback sho
1e870 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53  uld.** return [S
1e880 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c  QLITE_OK] to all
1e890 6f 77 20 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b  ow the action, [
1e8a0 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74  SQLITE_IGNORE] t
1e8b0 6f 20 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a  o disallow the.*
1e8c0 2a 20 73 70 65 63 69 66 69 63 20 61 63 74 69 6f  * specific actio
1e8d0 6e 20 62 75 74 20 61 6c 6c 6f 77 20 74 68 65 20  n but allow the 
1e8e0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  SQL statement to
1e8f0 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a   continue to be.
1e900 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20  ** compiled, or 
1e910 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f  [SQLITE_DENY] to
1e920 20 63 61 75 73 65 20 74 68 65 20 65 6e 74 69 72   cause the entir
1e930 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
1e940 74 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65  to be.** rejecte
1e950 64 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e  d with an error.
1e960 20 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72    ^If the author
1e970 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65  izer callback re
1e980 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c  turns.** any val
1e990 75 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  ue other than [S
1e9a0 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b  QLITE_IGNORE], [
1e9b0 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b  SQLITE_OK], or [
1e9c0 53 51 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20  SQLITE_DENY].** 
1e9d0 74 68 65 6e 20 74 68 65 20 5b 73 71 6c 69 74 65  then the [sqlite
1e9e0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
1e9f0 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61  or equivalent ca
1ea00 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65  ll that triggere
1ea10 64 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69  d.** the authori
1ea20 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69  zer will fail wi
1ea30 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73  th an error mess
1ea40 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  age..**.** When 
1ea50 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
1ea60 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  urns [SQLITE_OK]
1ea70 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65  , that means the
1ea80 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65   operation.** re
1ea90 71 75 65 73 74 65 64 20 69 73 20 6f 6b 2e 20 20  quested is ok.  
1eaa0 5e 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61  ^When the callba
1eab0 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ck returns [SQLI
1eac0 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a  TE_DENY], the.**
1ead0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1eae0 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76  e_v2()] or equiv
1eaf0 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20  alent call that 
1eb00 74 72 69 67 67 65 72 65 64 20 74 68 65 0a 2a 2a  triggered the.**
1eb10 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c   authorizer will
1eb20 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72   fail with an er
1eb30 72 6f 72 20 6d 65 73 73 61 67 65 20 65 78 70 6c  ror message expl
1eb40 61 69 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61  aining that.** a
1eb50 63 63 65 73 73 20 69 73 20 64 65 6e 69 65 64 2e  ccess is denied.
1eb60 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72   .**.** ^The fir
1eb70 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
1eb80 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
1eb90 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70  allback is a cop
1eba0 79 20 6f 66 20 74 68 65 20 74 68 69 72 64 0a 2a  y of the third.*
1ebb0 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  * parameter to t
1ebc0 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  he sqlite3_set_a
1ebd0 75 74 68 6f 72 69 7a 65 72 28 29 20 69 6e 74 65  uthorizer() inte
1ebe0 72 66 61 63 65 2e 20 5e 54 68 65 20 73 65 63 6f  rface. ^The seco
1ebf0 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  nd parameter.** 
1ec00 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  to the callback 
1ec10 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 5b 53  is an integer [S
1ec20 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74  QLITE_COPY | act
1ec30 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73  ion code] that s
1ec40 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20  pecifies.** the 
1ec50 70 61 72 74 69 63 75 6c 61 72 20 61 63 74 69 6f  particular actio
1ec60 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a  n to be authoriz
1ec70 65 64 2e 20 5e 54 68 65 20 74 68 69 72 64 20 74  ed. ^The third t
1ec80 68 72 6f 75 67 68 20 73 69 78 74 68 20 70 61 72  hrough sixth par
1ec90 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68  ameters.** to th
1eca0 65 20 63 61 6c 6c 62 61 63 6b 20 61 72 65 20 7a  e callback are z
1ecb0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73  ero-terminated s
1ecc0 74 72 69 6e 67 73 20 74 68 61 74 20 63 6f 6e 74  trings that cont
1ecd0 61 69 6e 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  ain additional.*
1ece0 2a 20 64 65 74 61 69 6c 73 20 61 62 6f 75 74 20  * details about 
1ecf0 74 68 65 20 61 63 74 69 6f 6e 20 74 6f 20 62 65  the action to be
1ed00 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a   authorized..**.
1ed10 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f  ** ^If the actio
1ed20 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54  n code is [SQLIT
1ed30 45 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74  E_READ].** and t
1ed40 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
1ed50 72 6e 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  rns [SQLITE_IGNO
1ed60 52 45 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20  RE] then the.** 
1ed70 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
1ed80 65 6e 74 5d 20 73 74 61 74 65 6d 65 6e 74 20 69  ent] statement i
1ed90 73 20 63 6f 6e 73 74 72 75 63 74 65 64 20 74 6f  s constructed to
1eda0 20 73 75 62 73 74 69 74 75 74 65 0a 2a 2a 20 61   substitute.** a
1edb0 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70   NULL value in p
1edc0 6c 61 63 65 20 6f 66 20 74 68 65 20 74 61 62 6c  lace of the tabl
1edd0 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f  e column that wo
1ede0 75 6c 64 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e  uld have.** been
1edf0 20 72 65 61 64 20 69 66 20 5b 53 51 4c 49 54 45   read if [SQLITE
1ee00 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e 20 72 65  _OK] had been re
1ee10 74 75 72 6e 65 64 2e 20 20 54 68 65 20 5b 53 51  turned.  The [SQ
1ee20 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20  LITE_IGNORE].** 
1ee30 72 65 74 75 72 6e 20 63 61 6e 20 62 65 20 75 73  return can be us
1ee40 65 64 20 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e  ed to deny an un
1ee50 74 72 75 73 74 65 64 20 75 73 65 72 20 61 63 63  trusted user acc
1ee60 65 73 73 20 74 6f 20 69 6e 64 69 76 69 64 75 61  ess to individua
1ee70 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20  l.** columns of 
1ee80 61 20 74 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20  a table..** ^If 
1ee90 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20  the action code 
1eea0 69 73 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54  is [SQLITE_DELET
1eeb0 45 5d 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62  E] and the callb
1eec0 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b  ack returns.** [
1eed0 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74  SQLITE_IGNORE] t
1eee0 68 65 6e 20 74 68 65 20 5b 44 45 4c 45 54 45 5d  hen the [DELETE]
1eef0 20 6f 70 65 72 61 74 69 6f 6e 20 70 72 6f 63 65   operation proce
1ef00 65 64 73 20 62 75 74 20 74 68 65 0a 2a 2a 20 5b  eds but the.** [
1ef10 74 72 75 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a  truncate optimiz
1ef20 61 74 69 6f 6e 5d 20 69 73 20 64 69 73 61 62 6c  ation] is disabl
1ef30 65 64 20 61 6e 64 20 61 6c 6c 20 72 6f 77 73 20  ed and all rows 
1ef40 61 72 65 20 64 65 6c 65 74 65 64 20 69 6e 64 69  are deleted indi
1ef50 76 69 64 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20  vidually..**.** 
1ef60 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73  An authorizer is
1ef70 20 75 73 65 64 20 77 68 65 6e 20 5b 73 71 6c 69   used when [sqli
1ef80 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72  te3_prepare | pr
1ef90 65 70 61 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20  eparing].** SQL 
1efa0 73 74 61 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20  statements from 
1efb0 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75  an untrusted sou
1efc0 72 63 65 2c 20 74 6f 20 65 6e 73 75 72 65 20 74  rce, to ensure t
1efd0 68 61 74 20 74 68 65 20 53 51 4c 20 73 74 61 74  hat the SQL stat
1efe0 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74  ements.** do not
1eff0 20 74 72 79 20 74 6f 20 61 63 63 65 73 73 20 64   try to access d
1f000 61 74 61 20 74 68 65 79 20 61 72 65 20 6e 6f 74  ata they are not
1f010 20 61 6c 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c   allowed to see,
1f020 20 6f 72 20 74 68 61 74 20 74 68 65 79 20 64 6f   or that they do
1f030 20 6e 6f 74 0a 2a 2a 20 74 72 79 20 74 6f 20 65   not.** try to e
1f040 78 65 63 75 74 65 20 6d 61 6c 69 63 69 6f 75 73  xecute malicious
1f050 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74   statements that
1f060 20 64 61 6d 61 67 65 20 74 68 65 20 64 61 74 61   damage the data
1f070 62 61 73 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78  base.  For.** ex
1f080 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63  ample, an applic
1f090 61 74 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20  ation may allow 
1f0a0 61 20 75 73 65 72 20 74 6f 20 65 6e 74 65 72 20  a user to enter 
1f0b0 61 72 62 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c  arbitrary.** SQL
1f0c0 20 71 75 65 72 69 65 73 20 66 6f 72 20 65 76 61   queries for eva
1f0d0 6c 75 61 74 69 6f 6e 20 62 79 20 61 20 64 61 74  luation by a dat
1f0e0 61 62 61 73 65 2e 20 20 42 75 74 20 74 68 65 20  abase.  But the 
1f0f0 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73  application does
1f100 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74 68 65  .** not want the
1f110 20 75 73 65 72 20 74 6f 20 62 65 20 61 62 6c 65   user to be able
1f120 20 74 6f 20 6d 61 6b 65 20 61 72 62 69 74 72 61   to make arbitra
1f130 72 79 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68  ry changes to th
1f140 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20  e.** database.  
1f150 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f  An authorizer co
1f160 75 6c 64 20 74 68 65 6e 20 62 65 20 70 75 74 20  uld then be put 
1f170 69 6e 20 70 6c 61 63 65 20 77 68 69 6c 65 20 74  in place while t
1f180 68 65 0a 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72  he.** user-enter
1f190 65 64 20 53 51 4c 20 69 73 20 62 65 69 6e 67 20  ed SQL is being 
1f1a0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1f1b0 20 7c 20 70 72 65 70 61 72 65 64 5d 20 74 68 61   | prepared] tha
1f1c0 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f 77 73 20 65  t.** disallows e
1f1d0 76 65 72 79 74 68 69 6e 67 20 65 78 63 65 70 74  verything except
1f1e0 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
1f1f0 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c  ents..**.** Appl
1f200 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6e 65  ications that ne
1f210 65 64 20 74 6f 20 70 72 6f 63 65 73 73 20 53 51  ed to process SQ
1f220 4c 20 66 72 6f 6d 20 75 6e 74 72 75 73 74 65 64  L from untrusted
1f230 20 73 6f 75 72 63 65 73 0a 2a 2a 20 6d 69 67 68   sources.** migh
1f240 74 20 61 6c 73 6f 20 63 6f 6e 73 69 64 65 72 20  t also consider 
1f250 6c 6f 77 65 72 69 6e 67 20 72 65 73 6f 75 72 63  lowering resourc
1f260 65 20 6c 69 6d 69 74 73 20 75 73 69 6e 67 20 5b  e limits using [
1f270 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d  sqlite3_limit()]
1f280 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69 74 69 6e 67  .** and limiting
1f290 20 64 61 74 61 62 61 73 65 20 73 69 7a 65 20 75   database size u
1f2a0 73 69 6e 67 20 74 68 65 20 5b 6d 61 78 5f 70 61  sing the [max_pa
1f2b0 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d  ge_count] [PRAGM
1f2c0 41 5d 0a 2a 2a 20 69 6e 20 61 64 64 69 74 69 6f  A].** in additio
1f2d0 6e 20 74 6f 20 75 73 69 6e 67 20 61 6e 20 61 75  n to using an au
1f2e0 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20  thorizer..**.** 
1f2f0 5e 28 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20  ^(Only a single 
1f300 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6e 20 62  authorizer can b
1f310 65 20 69 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20  e in place on a 
1f320 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1f330 69 6f 6e 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65  ion.** at a time
1f340 2e 20 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20  .  Each call to 
1f350 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
1f360 6f 72 69 7a 65 72 20 6f 76 65 72 72 69 64 65 73  orizer overrides
1f370 20 74 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73   the.** previous
1f380 20 63 61 6c 6c 2e 29 5e 20 20 5e 44 69 73 61 62   call.)^  ^Disab
1f390 6c 65 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  le the authorize
1f3a0 72 20 62 79 20 69 6e 73 74 61 6c 6c 69 6e 67 20  r by installing 
1f3b0 61 20 4e 55 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e  a NULL callback.
1f3c0 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a  .** The authoriz
1f3d0 65 72 20 69 73 20 64 69 73 61 62 6c 65 64 20 62  er is disabled b
1f3e0 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a  y default..**.**
1f3f0 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   The authorizer 
1f400 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f  callback must no
1f410 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68  t do anything th
1f420 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a  at will modify.*
1f430 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  * the database c
1f440 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69  onnection that i
1f450 6e 76 6f 6b 65 64 20 74 68 65 20 61 75 74 68 6f  nvoked the autho
1f460 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 2e 0a  rizer callback..
1f470 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71  ** Note that [sq
1f480 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1f490 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
1f4a0 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f  _step()] both mo
1f4b0 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61  dify their.** da
1f4c0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1f4d0 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69  ns for the meani
1f4e0 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69  ng of "modify" i
1f4f0 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68  n this paragraph
1f500 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 5b 73  ..**.** ^When [s
1f510 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1f520 32 28 29 5d 20 69 73 20 75 73 65 64 20 74 6f 20  2()] is used to 
1f530 70 72 65 70 61 72 65 20 61 20 73 74 61 74 65 6d  prepare a statem
1f540 65 6e 74 2c 20 74 68 65 0a 2a 2a 20 73 74 61 74  ent, the.** stat
1f550 65 6d 65 6e 74 20 6d 69 67 68 74 20 62 65 20 72  ement might be r
1f560 65 2d 70 72 65 70 61 72 65 64 20 64 75 72 69 6e  e-prepared durin
1f570 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  g [sqlite3_step(
1f580 29 5d 20 64 75 65 20 74 6f 20 61 20 0a 2a 2a 20  )] due to a .** 
1f590 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 20 20  schema change.  
1f5a0 48 65 6e 63 65 2c 20 74 68 65 20 61 70 70 6c 69  Hence, the appli
1f5b0 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 65 6e  cation should en
1f5c0 73 75 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a  sure that the.**
1f5d0 20 63 6f 72 72 65 63 74 20 61 75 74 68 6f 72 69   correct authori
1f5e0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 6d  zer callback rem
1f5f0 61 69 6e 73 20 69 6e 20 70 6c 61 63 65 20 64 75  ains in place du
1f600 72 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65  ring the [sqlite
1f610 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a  3_step()]..**.**
1f620 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20   ^Note that the 
1f630 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1f640 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f  ack is invoked o
1f650 6e 6c 79 20 64 75 72 69 6e 67 0a 2a 2a 20 5b 73  nly during.** [s
1f660 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
1f670 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74  ] or its variant
1f680 73 2e 20 20 41 75 74 68 6f 72 69 7a 61 74 69 6f  s.  Authorizatio
1f690 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 66  n is not.** perf
1f6a0 6f 72 6d 65 64 20 64 75 72 69 6e 67 20 73 74 61  ormed during sta
1f6b0 74 65 6d 65 6e 74 20 65 76 61 6c 75 61 74 69 6f  tement evaluatio
1f6c0 6e 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74  n in [sqlite3_st
1f6d0 65 70 28 29 5d 2c 20 75 6e 6c 65 73 73 0a 2a 2a  ep()], unless.**
1f6e0 20 61 73 20 73 74 61 74 65 64 20 69 6e 20 74 68   as stated in th
1f6f0 65 20 70 72 65 76 69 6f 75 73 20 70 61 72 61 67  e previous parag
1f700 72 61 70 68 2c 20 73 71 6c 69 74 65 33 5f 73 74  raph, sqlite3_st
1f710 65 70 28 29 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20  ep() invokes.** 
1f720 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1f730 76 32 28 29 20 74 6f 20 72 65 70 72 65 70 61 72  v2() to reprepar
1f740 65 20 61 20 73 74 61 74 65 6d 65 6e 74 20 61 66  e a statement af
1f750 74 65 72 20 61 20 73 63 68 65 6d 61 20 63 68 61  ter a schema cha
1f760 6e 67 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  nge..*/.SQLITE_A
1f770 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  PI int sqlite3_s
1f780 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a 20  et_authorizer(. 
1f790 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74   sqlite3*,.  int
1f7a0 20 28 2a 78 41 75 74 68 29 28 76 6f 69 64 2a 2c   (*xAuth)(void*,
1f7b0 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  int,const char*,
1f7c0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73  const char*,cons
1f7d0 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68  t char*,const ch
1f7e0 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55  ar*),.  void *pU
1f7f0 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a  serData.);../*.*
1f800 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68  * CAPI3REF: Auth
1f810 6f 72 69 7a 65 72 20 52 65 74 75 72 6e 20 43 6f  orizer Return Co
1f820 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73  des.**.** The [s
1f830 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
1f840 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a  rizer | authoriz
1f850 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  er callback func
1f860 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65  tion] must.** re
1f870 74 75 72 6e 20 65 69 74 68 65 72 20 5b 53 51 4c  turn either [SQL
1f880 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f  ITE_OK] or one o
1f890 66 20 74 68 65 73 65 20 74 77 6f 20 63 6f 6e 73  f these two cons
1f8a0 74 61 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a  tants in order.*
1f8b0 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69  * to signal SQLi
1f8c0 74 65 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  te whether or no
1f8d0 74 20 74 68 65 20 61 63 74 69 6f 6e 20 69 73 20  t the action is 
1f8e0 70 65 72 6d 69 74 74 65 64 2e 20 20 53 65 65 20  permitted.  See 
1f8f0 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
1f900 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c  set_authorizer |
1f910 20 61 75 74 68 6f 72 69 7a 65 72 20 64 6f 63 75   authorizer docu
1f920 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61  mentation] for a
1f930 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66  dditional.** inf
1f940 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  ormation..**.** 
1f950 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 49 54 45  Note that SQLITE
1f960 5f 49 47 4e 4f 52 45 20 69 73 20 61 6c 73 6f 20  _IGNORE is also 
1f970 75 73 65 64 20 61 73 20 61 20 5b 53 51 4c 49 54  used as a [SQLIT
1f980 45 5f 52 4f 4c 4c 42 41 43 4b 20 7c 20 72 65 74  E_ROLLBACK | ret
1f990 75 72 6e 20 63 6f 64 65 5d 0a 2a 2a 20 66 72 6f  urn code].** fro
1f9a0 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  m the [sqlite3_v
1f9b0 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28  tab_on_conflict(
1f9c0 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f  )] interface..*/
1f9d0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1f9e0 44 45 4e 59 20 20 20 31 20 20 20 2f 2a 20 41 62  DENY   1   /* Ab
1f9f0 6f 72 74 20 74 68 65 20 53 51 4c 20 73 74 61 74  ort the SQL stat
1fa00 65 6d 65 6e 74 20 77 69 74 68 20 61 6e 20 65 72  ement with an er
1fa10 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ror */.#define S
1fa20 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32 20 20  QLITE_IGNORE 2  
1fa30 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20   /* Don't allow 
1fa40 61 63 63 65 73 73 2c 20 62 75 74 20 64 6f 6e 27  access, but don'
1fa50 74 20 67 65 6e 65 72 61 74 65 20 61 6e 20 65 72  t generate an er
1fa60 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  ror */../*.** CA
1fa70 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a  PI3REF: Authoriz
1fa80 65 72 20 41 63 74 69 6f 6e 20 43 6f 64 65 73 0a  er Action Codes.
1fa90 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74  **.** The [sqlit
1faa0 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
1fab0 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  r()] interface r
1fac0 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62  egisters a callb
1fad0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ack function.** 
1fae0 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20  that is invoked 
1faf0 74 6f 20 61 75 74 68 6f 72 69 7a 65 20 63 65 72  to authorize cer
1fb00 74 61 69 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  tain SQL stateme
1fb10 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20 54 68 65  nt actions.  The
1fb20 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  .** second param
1fb30 65 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c  eter to the call
1fb40 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67  back is an integ
1fb50 65 72 20 63 6f 64 65 20 74 68 61 74 20 73 70 65  er code that spe
1fb60 63 69 66 69 65 73 0a 2a 2a 20 77 68 61 74 20 61  cifies.** what a
1fb70 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 61  ction is being a
1fb80 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 73  uthorized.  Thes
1fb90 65 20 61 72 65 20 74 68 65 20 69 6e 74 65 67 65  e are the intege
1fba0 72 20 61 63 74 69 6f 6e 20 63 6f 64 65 73 20 74  r action codes t
1fbb0 68 61 74 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f  hat.** the autho
1fbc0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d  rizer callback m
1fbd0 61 79 20 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a  ay be passed..**
1fbe0 0a 2a 2a 20 54 68 65 73 65 20 61 63 74 69 6f 6e  .** These action
1fbf0 20 63 6f 64 65 20 76 61 6c 75 65 73 20 73 69 67   code values sig
1fc00 6e 69 66 79 20 77 68 61 74 20 6b 69 6e 64 20 6f  nify what kind o
1fc10 66 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 74  f operation is t
1fc20 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a  o be.** authoriz
1fc30 65 64 2e 20 20 54 68 65 20 33 72 64 20 61 6e 64  ed.  The 3rd and
1fc40 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 73 20   4th parameters 
1fc50 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 61  to the authoriza
1fc60 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  tion.** callback
1fc70 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62   function will b
1fc80 65 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20  e parameters or 
1fc90 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f  NULL depending o
1fca0 6e 20 77 68 69 63 68 20 6f 66 20 74 68 65 73 65  n which of these
1fcb0 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20 75 73 65  .** codes is use
1fcc0 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  d as the second 
1fcd0 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 28 54 68  parameter.  ^(Th
1fce0 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 5th parameter 
1fcf0 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72  to the.** author
1fd00 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
1fd10 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
1fd20 20 64 61 74 61 62 61 73 65 20 28 22 6d 61 69 6e   database ("main
1fd30 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 74  ", "temp",.** et
1fd40 63 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62 6c  c.) if applicabl
1fd50 65 2e 29 5e 20 20 5e 54 68 65 20 36 74 68 20 70  e.)^  ^The 6th p
1fd60 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
1fd70 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1fd80 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61  ack.** is the na
1fd90 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d  me of the inner-
1fda0 6d 6f 73 74 20 74 72 69 67 67 65 72 20 6f 72 20  most trigger or 
1fdb0 76 69 65 77 20 74 68 61 74 20 69 73 20 72 65 73  view that is res
1fdc0 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20  ponsible for.** 
1fdd0 74 68 65 20 61 63 63 65 73 73 20 61 74 74 65 6d  the access attem
1fde0 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68  pt or NULL if th
1fdf0 69 73 20 61 63 63 65 73 73 20 61 74 74 65 6d 70  is access attemp
1fe00 74 20 69 73 20 64 69 72 65 63 74 6c 79 20 66 72  t is directly fr
1fe10 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20  om.** top-level 
1fe20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a  SQL code..*/./**
1fe30 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1fe40 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1fe50 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a  ********* 3rd **
1fe60 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a  ********** 4th *
1fe70 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66  **********/.#def
1fe80 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
1fe90 45 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20  E_INDEX         
1fea0 20 31 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61   1   /* Index Na
1feb0 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61  me      Table Na
1fec0 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
1fed0 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
1fee0 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20  _TABLE          
1fef0 32 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  2   /* Table Nam
1ff00 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
1ff10 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1ff20 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
1ff30 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 33  TEMP_INDEX     3
1ff40 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65     /* Index Name
1ff50 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65        Table Name
1ff60 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1ff70 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
1ff80 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 34 20  EMP_TABLE     4 
1ff90 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
1ffa0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1ffb0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1ffc0 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45  SQLITE_CREATE_TE
1ffd0 4d 50 5f 54 52 49 47 47 45 52 20 20 20 35 20 20  MP_TRIGGER   5  
1ffe0 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65   /* Trigger Name
1fff0 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
20000 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
20010 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d  QLITE_CREATE_TEM
20020 50 5f 56 49 45 57 20 20 20 20 20 20 36 20 20 20  P_VIEW      6   
20030 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20  /* View Name    
20040 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
20050 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
20060 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 52 49 47  LITE_CREATE_TRIG
20070 47 45 52 20 20 20 20 20 20 20 20 37 20 20 20 2f  GER        7   /
20080 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20  * Trigger Name  
20090 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
200a0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
200b0 49 54 45 5f 43 52 45 41 54 45 5f 56 49 45 57 20  ITE_CREATE_VIEW 
200c0 20 20 20 20 20 20 20 20 20 20 38 20 20 20 2f 2a            8   /*
200d0 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20   View Name      
200e0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
200f0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
20100 54 45 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20  TE_DELETE       
20110 20 20 20 20 20 20 20 20 20 39 20 20 20 2f 2a 20           9   /* 
20120 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
20130 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
20140 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
20150 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20 20 20  E_DROP_INDEX    
20160 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 49         10   /* I
20170 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54  ndex Name      T
20180 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
20190 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
201a0 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20 20 20 20  _DROP_TABLE     
201b0 20 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 61        11   /* Ta
201c0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
201d0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
201e0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
201f0 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20  DROP_TEMP_INDEX 
20200 20 20 20 20 20 31 32 20 20 20 2f 2a 20 49 6e 64       12   /* Ind
20210 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62  ex Name      Tab
20220 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
20230 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
20240 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20  ROP_TEMP_TABLE  
20250 20 20 20 20 31 33 20 20 20 2f 2a 20 54 61 62 6c      13   /* Tabl
20260 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
20270 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
20280 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
20290 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20  OP_TEMP_TRIGGER 
202a0 20 20 20 31 34 20 20 20 2f 2a 20 54 72 69 67 67     14   /* Trigg
202b0 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65  er Name    Table
202c0 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
202d0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
202e0 50 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20  P_TEMP_VIEW     
202f0 20 20 31 35 20 20 20 2f 2a 20 56 69 65 77 20 4e    15   /* View N
20300 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  ame       NULL  
20310 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
20320 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
20330 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20  _TRIGGER        
20340 20 31 36 20 20 20 2f 2a 20 54 72 69 67 67 65 72   16   /* Trigger
20350 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e   Name    Table N
20360 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
20370 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
20380 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20 20  VIEW            
20390 31 37 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d  17   /* View Nam
203a0 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  e       NULL    
203b0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
203c0 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53 45 52 54  ne SQLITE_INSERT
203d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
203e0 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  8   /* Table Nam
203f0 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
20400 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
20410 65 20 53 51 4c 49 54 45 5f 50 52 41 47 4d 41 20  e SQLITE_PRAGMA 
20420 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 39                19
20430 20 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d     /* Pragma Nam
20440 65 20 20 20 20 20 31 73 74 20 61 72 67 20 6f 72  e     1st arg or
20450 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65   NULL */.#define
20460 20 53 51 4c 49 54 45 5f 52 45 41 44 20 20 20 20   SQLITE_READ    
20470 20 20 20 20 20 20 20 20 20 20 20 20 20 32 30 20               20 
20480 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
20490 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65       Column Name
204a0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
204b0 53 51 4c 49 54 45 5f 53 45 4c 45 43 54 20 20 20  SQLITE_SELECT   
204c0 20 20 20 20 20 20 20 20 20 20 20 20 32 31 20 20              21  
204d0 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20   /* NULL        
204e0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
204f0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
20500 51 4c 49 54 45 5f 54 52 41 4e 53 41 43 54 49 4f  QLITE_TRANSACTIO
20510 4e 20 20 20 20 20 20 20 20 20 20 32 32 20 20 20  N          22   
20520 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20  /* Operation    
20530 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
20540 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
20550 4c 49 54 45 5f 55 50 44 41 54 45 20 20 20 20 20  LITE_UPDATE     
20560 20 20 20 20 20 20 20 20 20 20 32 33 20 20 20 2f            23   /
20570 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
20580 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20    Column Name   
20590 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
205a0 49 54 45 5f 41 54 54 41 43 48 20 20 20 20 20 20  ITE_ATTACH      
205b0 20 20 20 20 20 20 20 20 20 32 34 20 20 20 2f 2a           24   /*
205c0 20 46 69 6c 65 6e 61 6d 65 20 20 20 20 20 20 20   Filename       
205d0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
205e0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
205f0 54 45 5f 44 45 54 41 43 48 20 20 20 20 20 20 20  TE_DETACH       
20600 20 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20          25   /* 
20610 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20  Database Name   
20620 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
20630 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
20640 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20 20 20  E_ALTER_TABLE   
20650 20 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 44         26   /* D
20660 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 54  atabase Name   T
20670 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
20680 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
20690 5f 52 45 49 4e 44 45 58 20 20 20 20 20 20 20 20  _REINDEX        
206a0 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20 49 6e        27   /* In
206b0 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  dex Name      NU
206c0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
206d0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
206e0 41 4e 41 4c 59 5a 45 20 20 20 20 20 20 20 20 20  ANALYZE         
206f0 20 20 20 20 20 32 38 20 20 20 2f 2a 20 54 61 62       28   /* Tab
20700 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
20710 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
20720 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
20730 52 45 41 54 45 5f 56 54 41 42 4c 45 20 20 20 20  REATE_VTABLE    
20740 20 20 20 20 32 39 20 20 20 2f 2a 20 54 61 62 6c      29   /* Tabl
20750 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75  e Name      Modu
20760 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23  le Name     */.#
20770 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
20780 4f 50 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20  OP_VTABLE       
20790 20 20 20 33 30 20 20 20 2f 2a 20 54 61 62 6c 65     30   /* Table
207a0 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c   Name      Modul
207b0 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64  e Name     */.#d
207c0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e  efine SQLITE_FUN
207d0 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 20  CTION           
207e0 20 20 33 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20    31   /* NULL  
207f0 20 20 20 20 20 20 20 20 20 20 46 75 6e 63 74 69            Functi
20800 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a 23 64 65  on Name   */.#de
20810 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 41 56 45  fine SQLITE_SAVE
20820 50 4f 49 4e 54 20 20 20 20 20 20 20 20 20 20 20  POINT           
20830 20 33 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69   32   /* Operati
20840 6f 6e 20 20 20 20 20 20 20 53 61 76 65 70 6f 69  on       Savepoi
20850 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a 23 64 65 66  nt Name  */.#def
20860 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50 59 20  ine SQLITE_COPY 
20870 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
20880 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65   0   /* No longe
20890 72 20 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  r used */../*.**
208a0 20 43 41 50 49 33 52 45 46 3a 20 54 72 61 63 69   CAPI3REF: Traci
208b0 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67  ng And Profiling
208c0 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a   Functions.**.**
208d0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
208e0 72 65 67 69 73 74 65 72 20 63 61 6c 6c 62 61 63  register callbac
208f0 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74  k functions that
20900 20 63 61 6e 20 62 65 20 75 73 65 64 20 66 6f 72   can be used for
20910 0a 2a 2a 20 74 72 61 63 69 6e 67 20 61 6e 64 20  .** tracing and 
20920 70 72 6f 66 69 6c 69 6e 67 20 74 68 65 20 65 78  profiling the ex
20930 65 63 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73  ecution of SQL s
20940 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a  tatements..**.**
20950 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66   ^The callback f
20960 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72  unction register
20970 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74 72  ed by sqlite3_tr
20980 61 63 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ace() is invoked
20990 20 61 74 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74   at.** various t
209a0 69 6d 65 73 20 77 68 65 6e 20 61 6e 20 53 51 4c  imes when an SQL
209b0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 62 65   statement is be
209c0 69 6e 67 20 72 75 6e 20 62 79 20 5b 73 71 6c 69  ing run by [sqli
209d0 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20  te3_step()]..** 
209e0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74 72 61  ^The sqlite3_tra
209f0 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73  ce() callback is
20a00 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 20   invoked with a 
20a10 55 54 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 20  UTF-8 rendering 
20a20 6f 66 20 74 68 65 0a 2a 2a 20 53 51 4c 20 73 74  of the.** SQL st
20a30 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61 73 20  atement text as 
20a40 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66 69  the statement fi
20a50 72 73 74 20 62 65 67 69 6e 73 20 65 78 65 63 75  rst begins execu
20a60 74 69 6e 67 2e 0a 2a 2a 20 5e 28 41 64 64 69 74  ting..** ^(Addit
20a70 69 6f 6e 61 6c 20 73 71 6c 69 74 65 33 5f 74 72  ional sqlite3_tr
20a80 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 73 20  ace() callbacks 
20a90 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 61  might occur.** a
20aa0 73 20 65 61 63 68 20 74 72 69 67 67 65 72 65 64  s each triggered
20ab0 20 73 75 62 70 72 6f 67 72 61 6d 20 69 73 20 65   subprogram is e
20ac0 6e 74 65 72 65 64 2e 20 20 54 68 65 20 63 61 6c  ntered.  The cal
20ad0 6c 62 61 63 6b 73 20 66 6f 72 20 74 72 69 67 67  lbacks for trigg
20ae0 65 72 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61  ers.** contain a
20af0 20 55 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65   UTF-8 SQL comme
20b00 6e 74 20 74 68 61 74 20 69 64 65 6e 74 69 66 69  nt that identifi
20b10 65 73 20 74 68 65 20 74 72 69 67 67 65 72 2e 29  es the trigger.)
20b20 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c  ^.**.** ^The cal
20b30 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72  lback function r
20b40 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c  egistered by sql
20b50 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 69  ite3_profile() i
20b60 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20  s invoked.** as 
20b70 65 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65  each SQL stateme
20b80 6e 74 20 66 69 6e 69 73 68 65 73 2e 20 20 5e 54  nt finishes.  ^T
20b90 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62  he profile callb
20ba0 61 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20  ack contains.** 
20bb0 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61  the original sta
20bc0 74 65 6d 65 6e 74 20 74 65 78 74 20 61 6e 64 20  tement text and 
20bd0 61 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20 77  an estimate of w
20be0 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a  all-clock time.*
20bf0 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74 68  * of how long th
20c00 61 74 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f  at statement too
20c10 6b 20 74 6f 20 72 75 6e 2e 20 20 5e 54 68 65 20  k to run.  ^The 
20c20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b  profile callback
20c30 0a 2a 2a 20 74 69 6d 65 20 69 73 20 69 6e 20 75  .** time is in u
20c40 6e 69 74 73 20 6f 66 20 6e 61 6e 6f 73 65 63 6f  nits of nanoseco
20c50 6e 64 73 2c 20 68 6f 77 65 76 65 72 20 74 68 65  nds, however the
20c60 20 63 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65   current impleme
20c70 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6f 6e  ntation.** is on
20c80 6c 79 20 63 61 70 61 62 6c 65 20 6f 66 20 6d 69  ly capable of mi
20c90 6c 6c 69 73 65 63 6f 6e 64 20 72 65 73 6f 6c 75  llisecond resolu
20ca0 74 69 6f 6e 20 73 6f 20 74 68 65 20 73 69 78 20  tion so the six 
20cb0 6c 65 61 73 74 20 73 69 67 6e 69 66 69 63 61 6e  least significan
20cc0 74 0a 2a 2a 20 64 69 67 69 74 73 20 69 6e 20 74  t.** digits in t
20cd0 68 65 20 74 69 6d 65 20 61 72 65 20 6d 65 61 6e  he time are mean
20ce0 69 6e 67 6c 65 73 73 2e 20 20 46 75 74 75 72 65  ingless.  Future
20cf0 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
20d00 69 74 65 0a 2a 2a 20 6d 69 67 68 74 20 70 72 6f  ite.** might pro
20d10 76 69 64 65 20 67 72 65 61 74 65 72 20 72 65 73  vide greater res
20d20 6f 6c 75 74 69 6f 6e 20 6f 6e 20 74 68 65 20 70  olution on the p
20d30 72 6f 66 69 6c 65 72 20 63 61 6c 6c 62 61 63 6b  rofiler callback
20d40 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65  .  The.** sqlite
20d50 33 5f 70 72 6f 66 69 6c 65 28 29 20 66 75 6e 63  3_profile() func
20d60 74 69 6f 6e 20 69 73 20 63 6f 6e 73 69 64 65 72  tion is consider
20d70 65 64 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20  ed experimental 
20d80 61 6e 64 20 69 73 0a 2a 2a 20 73 75 62 6a 65 63  and is.** subjec
20d90 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e 20 66  t to change in f
20da0 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
20db0 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 53 51 4c  f SQLite..*/.SQL
20dc0 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71  ITE_API void *sq
20dd0 6c 69 74 65 33 5f 74 72 61 63 65 28 73 71 6c 69  lite3_trace(sqli
20de0 74 65 33 2a 2c 20 76 6f 69 64 28 2a 78 54 72 61  te3*, void(*xTra
20df0 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20  ce)(void*,const 
20e00 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a  char*), void*);.
20e10 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54  SQLITE_API SQLIT
20e20 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 76  E_EXPERIMENTAL v
20e30 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 70 72 6f  oid *sqlite3_pro
20e40 66 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20  file(sqlite3*,. 
20e50 20 20 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65    void(*xProfile
20e60 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68  )(void*,const ch
20e70 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74  ar*,sqlite3_uint
20e80 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a  64), void*);../*
20e90 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 51 75  .** CAPI3REF: Qu
20ea0 65 72 79 20 50 72 6f 67 72 65 73 73 20 43 61 6c  ery Progress Cal
20eb0 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  lbacks.**.** ^Th
20ec0 65 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65  e sqlite3_progre
20ed0 73 73 5f 68 61 6e 64 6c 65 72 28 44 2c 4e 2c 58  ss_handler(D,N,X
20ee0 2c 50 29 20 69 6e 74 65 72 66 61 63 65 20 63 61  ,P) interface ca
20ef0 75 73 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63  uses the callbac
20f00 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 58 20  k.** function X 
20f10 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 65  to be invoked pe
20f20 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 72 69 6e  riodically durin
20f30 67 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67 20 63  g long running c
20f40 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  alls to.** [sqli
20f50 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71  te3_exec()], [sq
20f60 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 61 6e  lite3_step()] an
20f70 64 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  d [sqlite3_get_t
20f80 61 62 6c 65 28 29 5d 20 66 6f 72 0a 2a 2a 20 64  able()] for.** d
20f90 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
20fa0 6f 6e 20 44 2e 20 20 41 6e 20 65 78 61 6d 70 6c  on D.  An exampl
20fb0 65 20 75 73 65 20 66 6f 72 20 74 68 69 73 0a 2a  e use for this.*
20fc0 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74  * interface is t
20fd0 6f 20 6b 65 65 70 20 61 20 47 55 49 20 75 70 64  o keep a GUI upd
20fe0 61 74 65 64 20 64 75 72 69 6e 67 20 61 20 6c 61  ated during a la
20ff0 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a  rge query..**.**
21000 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 20   ^The parameter 
21010 50 20 69 73 20 70 61 73 73 65 64 20 74 68 72 6f  P is passed thro
21020 75 67 68 20 61 73 20 74 68 65 20 6f 6e 6c 79 20  ugh as the only 
21030 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
21040 20 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75   .** callback fu
21050 6e 63 74 69 6f 6e 20 58 2e 20 20 5e 54 68 65 20  nction X.  ^The 
21060 70 61 72 61 6d 65 74 65 72 20 4e 20 69 73 20 74  parameter N is t
21070 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 0a 2a 2a  he number of .**
21080 20 5b 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e   [virtual machin
21090 65 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 5d 20  e instructions] 
210a0 74 68 61 74 20 61 72 65 20 65 76 61 6c 75 61 74  that are evaluat
210b0 65 64 20 62 65 74 77 65 65 6e 20 73 75 63 63 65  ed between succe
210c0 73 73 69 76 65 0a 2a 2a 20 69 6e 76 6f 63 61 74  ssive.** invocat
210d0 69 6f 6e 73 20 6f 66 20 74 68 65 20 63 61 6c 6c  ions of the call
210e0 62 61 63 6b 20 58 2e 0a 2a 2a 0a 2a 2a 20 5e 4f  back X..**.** ^O
210f0 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 70 72 6f  nly a single pro
21100 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 6d 61  gress handler ma
21110 79 20 62 65 20 64 65 66 69 6e 65 64 20 61 74 20  y be defined at 
21120 6f 6e 65 20 74 69 6d 65 20 70 65 72 0a 2a 2a 20  one time per.** 
21130 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
21140 74 69 6f 6e 5d 3b 20 73 65 74 74 69 6e 67 20 61  tion]; setting a
21150 20 6e 65 77 20 70 72 6f 67 72 65 73 73 20 68 61   new progress ha
21160 6e 64 6c 65 72 20 63 61 6e 63 65 6c 73 20 74 68  ndler cancels th
21170 65 0a 2a 2a 20 6f 6c 64 20 6f 6e 65 2e 20 20 5e  e.** old one.  ^
21180 53 65 74 74 69 6e 67 20 70 61 72 61 6d 65 74 65  Setting paramete
21190 72 20 58 20 74 6f 20 4e 55 4c 4c 20 64 69 73 61  r X to NULL disa
211a0 62 6c 65 73 20 74 68 65 20 70 72 6f 67 72 65 73  bles the progres
211b0 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 5e 54  s handler..** ^T
211c0 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64  he progress hand
211d0 6c 65 72 20 69 73 20 61 6c 73 6f 20 64 69 73 61  ler is also disa
211e0 62 6c 65 64 20 62 79 20 73 65 74 74 69 6e 67 20  bled by setting 
211f0 4e 20 74 6f 20 61 20 76 61 6c 75 65 20 6c 65 73  N to a value les
21200 73 0a 2a 2a 20 74 68 61 6e 20 31 2e 0a 2a 2a 0a  s.** than 1..**.
21210 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 6f 67 72  ** ^If the progr
21220 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  ess callback ret
21230 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  urns non-zero, t
21240 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a  he operation is.
21250 2a 2a 20 69 6e 74 65 72 72 75 70 74 65 64 2e 20  ** interrupted. 
21260 20 54 68 69 73 20 66 65 61 74 75 72 65 20 63 61   This feature ca
21270 6e 20 62 65 20 75 73 65 64 20 74 6f 20 69 6d 70  n be used to imp
21280 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e  lement a.** "Can
21290 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61  cel" button on a
212a0 20 47 55 49 20 70 72 6f 67 72 65 73 73 20 64 69   GUI progress di
212b0 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20  alog box..**.** 
212c0 54 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e  The progress han
212d0 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75  dler callback mu
212e0 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69  st not do anythi
212f0 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64  ng that will mod
21300 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  ify.** the datab
21310 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
21320 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20  hat invoked the 
21330 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
21340 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b  ..** Note that [
21350 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
21360 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  v2()] and [sqlit
21370 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20  e3_step()] both 
21380 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20  modify their.** 
21390 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
213a0 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61  ions for the mea
213b0 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22  ning of "modify"
213c0 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61   in this paragra
213d0 70 68 2e 0a 2a 2a 0a 2a 2f 0a 53 51 4c 49 54 45  ph..**.*/.SQLITE
213e0 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65  _API void sqlite
213f0 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c  3_progress_handl
21400 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  er(sqlite3*, int
21410 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c  , int(*)(void*),
21420 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20   void*);../*.** 
21430 43 41 50 49 33 52 45 46 3a 20 4f 70 65 6e 69 6e  CAPI3REF: Openin
21440 67 20 41 20 4e 65 77 20 44 61 74 61 62 61 73 65  g A New Database
21450 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a   Connection.**.*
21460 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
21470 73 20 6f 70 65 6e 20 61 6e 20 53 51 4c 69 74 65  s open an SQLite
21480 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 61   database file a
21490 73 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74  s specified by t
214a0 68 65 20 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20  he .** filename 
214b0 61 72 67 75 6d 65 6e 74 2e 20 5e 54 68 65 20 66  argument. ^The f
214c0 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74  ilename argument
214d0 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20   is interpreted 
214e0 61 73 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20  as UTF-8 for.** 
214f0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61  sqlite3_open() a
21500 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  nd sqlite3_open_
21510 76 32 28 29 20 61 6e 64 20 61 73 20 55 54 46 2d  v2() and as UTF-
21520 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65  16 in the native
21530 20 62 79 74 65 0a 2a 2a 20 6f 72 64 65 72 20 66   byte.** order f
21540 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  or sqlite3_open1
21550 36 28 29 2e 20 5e 28 41 20 5b 64 61 74 61 62 61  6(). ^(A [databa
21560 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68  se connection] h
21570 61 6e 64 6c 65 20 69 73 20 75 73 75 61 6c 6c 79  andle is usually
21580 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 6e 20  .** returned in 
21590 2a 70 70 44 62 2c 20 65 76 65 6e 20 69 66 20 61  *ppDb, even if a
215a0 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20  n error occurs. 
215b0 20 54 68 65 20 6f 6e 6c 79 20 65 78 63 65 70 74   The only except
215c0 69 6f 6e 20 69 73 20 74 68 61 74 0a 2a 2a 20 69  ion is that.** i
215d0 66 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62  f SQLite is unab
215e0 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d  le to allocate m
215f0 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68  emory to hold th
21600 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65  e [sqlite3] obje
21610 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69  ct,.** a NULL wi
21620 6c 6c 20 62 65 20 77 72 69 74 74 65 6e 20 69 6e  ll be written in
21630 74 6f 20 2a 70 70 44 62 20 69 6e 73 74 65 61 64  to *ppDb instead
21640 20 6f 66 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   of a pointer to
21650 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a   the [sqlite3].*
21660 2a 20 6f 62 6a 65 63 74 2e 29 5e 20 5e 28 49 66  * object.)^ ^(If
21670 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
21680 20 6f 70 65 6e 65 64 20 28 61 6e 64 2f 6f 72 20   opened (and/or 
21690 63 72 65 61 74 65 64 29 20 73 75 63 63 65 73 73  created) success
216a0 66 75 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b  fully, then.** [
216b0 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65  SQLITE_OK] is re
216c0 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69  turned.  Otherwi
216d0 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64  se an [error cod
216e0 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29  e] is returned.)
216f0 5e 20 5e 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ^ ^The.** [sqlit
21700 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72 20  e3_errmsg()] or 
21710 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31  [sqlite3_errmsg1
21720 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 63 61  6()] routines ca
21730 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74  n be used to obt
21740 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73  ain.** an Englis
21750 68 20 6c 61 6e 67 75 61 67 65 20 64 65 73 63 72  h language descr
21760 69 70 74 69 6f 6e 20 6f 66 20 74 68 65 20 65 72  iption of the er
21770 72 6f 72 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20  ror following a 
21780 66 61 69 6c 75 72 65 20 6f 66 20 61 6e 79 0a 2a  failure of any.*
21790 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  * of the sqlite3
217a0 5f 6f 70 65 6e 28 29 20 72 6f 75 74 69 6e 65 73  _open() routines
217b0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66  ..**.** ^The def
217c0 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f  ault encoding fo
217d0 72 20 74 68 65 20 64 61 74 61 62 61 73 65 20 77  r the database w
217e0 69 6c 6c 20 62 65 20 55 54 46 2d 38 20 69 66 0a  ill be UTF-8 if.
217f0 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ** sqlite3_open(
21800 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65  ) or sqlite3_ope
21810 6e 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65 64  n_v2() is called
21820 20 61 6e 64 0a 2a 2a 20 55 54 46 2d 31 36 20 69   and.** UTF-16 i
21830 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74  n the native byt
21840 65 20 6f 72 64 65 72 20 69 66 20 73 71 6c 69 74  e order if sqlit
21850 65 33 5f 6f 70 65 6e 31 36 28 29 20 69 73 20 75  e3_open16() is u
21860 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68  sed..**.** Wheth
21870 65 72 20 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72  er or not an err
21880 6f 72 20 6f 63 63 75 72 73 20 77 68 65 6e 20 69  or occurs when i
21890 74 20 69 73 20 6f 70 65 6e 65 64 2c 20 72 65 73  t is opened, res
218a0 6f 75 72 63 65 73 0a 2a 2a 20 61 73 73 6f 63 69  ources.** associ
218b0 61 74 65 64 20 77 69 74 68 20 74 68 65 20 5b 64  ated with the [d
218c0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
218d0 6f 6e 5d 20 68 61 6e 64 6c 65 20 73 68 6f 75 6c  on] handle shoul
218e0 64 20 62 65 20 72 65 6c 65 61 73 65 64 20 62 79  d be released by
218f0 0a 2a 2a 20 70 61 73 73 69 6e 67 20 69 74 20 74  .** passing it t
21900 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  o [sqlite3_close
21910 28 29 5d 20 77 68 65 6e 20 69 74 20 69 73 20 6e  ()] when it is n
21920 6f 20 6c 6f 6e 67 65 72 20 72 65 71 75 69 72 65  o longer require
21930 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  d..**.** The sql
21940 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
21950 6e 74 65 72 66 61 63 65 20 77 6f 72 6b 73 20 6c  nterface works l
21960 69 6b 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ike sqlite3_open
21970 28 29 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61  ().** except tha
21980 74 20 69 74 20 61 63 63 65 70 74 73 20 74 77 6f  t it accepts two
21990 20 61 64 64 69 74 69 6f 6e 61 6c 20 70 61 72 61   additional para
219a0 6d 65 74 65 72 73 20 66 6f 72 20 61 64 64 69 74  meters for addit
219b0 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a  ional control.**
219c0 20 6f 76 65 72 20 74 68 65 20 6e 65 77 20 64 61   over the new da
219d0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
219e0 6e 2e 20 20 5e 28 54 68 65 20 66 6c 61 67 73 20  n.  ^(The flags 
219f0 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
21a00 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
21a10 29 20 63 61 6e 20 74 61 6b 65 20 6f 6e 65 20 6f  ) can take one o
21a20 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69  f.** the followi
21a30 6e 67 20 74 68 72 65 65 20 76 61 6c 75 65 73 2c  ng three values,
21a40 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62   optionally comb
21a50 69 6e 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a  ined with the .*
21a60 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e  * [SQLITE_OPEN_N
21a70 4f 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45  OMUTEX], [SQLITE
21a80 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d  _OPEN_FULLMUTEX]
21a90 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53  , [SQLITE_OPEN_S
21aa0 48 41 52 45 44 43 41 43 48 45 5d 2c 0a 2a 2a 20  HAREDCACHE],.** 
21ab0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49  [SQLITE_OPEN_PRI
21ac0 56 41 54 45 43 41 43 48 45 5d 2c 20 61 6e 64 2f  VATECACHE], and/
21ad0 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  or [SQLITE_OPEN_
21ae0 55 52 49 5d 20 66 6c 61 67 73 3a 29 5e 0a 2a 2a  URI] flags:)^.**
21af0 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64  .** <dl>.** ^(<d
21b00 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  t>[SQLITE_OPEN_R
21b10 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a  EADONLY]</dt>.**
21b20 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73   <dd>The databas
21b30 65 20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 72  e is opened in r
21b40 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20  ead-only mode.  
21b50 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  If the database 
21b60 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65  does not.** alre
21b70 61 64 79 20 65 78 69 73 74 2c 20 61 6e 20 65 72  ady exist, an er
21b80 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ror is returned.
21b90 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28  </dd>)^.**.** ^(
21ba0 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  <dt>[SQLITE_OPEN
21bb0 5f 52 45 41 44 57 52 49 54 45 5d 3c 2f 64 74 3e  _READWRITE]</dt>
21bc0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61  .** <dd>The data
21bd0 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66  base is opened f
21be0 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77  or reading and w
21bf0 72 69 74 69 6e 67 20 69 66 20 70 6f 73 73 69 62  riting if possib
21c00 6c 65 2c 20 6f 72 20 72 65 61 64 69 6e 67 0a 2a  le, or reading.*
21c10 2a 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 66 69  * only if the fi
21c20 6c 65 20 69 73 20 77 72 69 74 65 20 70 72 6f 74  le is write prot
21c30 65 63 74 65 64 20 62 79 20 74 68 65 20 6f 70 65  ected by the ope
21c40 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20  rating system.  
21c50 49 6e 20 65 69 74 68 65 72 0a 2a 2a 20 63 61 73  In either.** cas
21c60 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6d  e the database m
21c70 75 73 74 20 61 6c 72 65 61 64 79 20 65 78 69 73  ust already exis
21c80 74 2c 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20  t, otherwise an 
21c90 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65  error is returne
21ca0 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  d.</dd>)^.**.** 
21cb0 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50  ^(<dt>[SQLITE_OP
21cc0 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20  EN_READWRITE] | 
21cd0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45  [SQLITE_OPEN_CRE
21ce0 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ATE]</dt>.** <dd
21cf0 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73  >The database is
21d00 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64   opened for read
21d10 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 2c  ing and writing,
21d20 20 61 6e 64 20 69 73 20 63 72 65 61 74 65 64 20   and is created 
21d30 69 66 0a 2a 2a 20 69 74 20 64 6f 65 73 20 6e 6f  if.** it does no
21d40 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2e  t already exist.
21d50 20 54 68 69 73 20 69 73 20 74 68 65 20 62 65 68   This is the beh
21d60 61 76 69 6f 72 20 74 68 61 74 20 69 73 20 61 6c  avior that is al
21d70 77 61 79 73 20 75 73 65 64 20 66 6f 72 0a 2a 2a  ways used for.**
21d80 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
21d90 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  and sqlite3_open
21da0 31 36 28 29 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20  16().</dd>)^.** 
21db0 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  </dl>.**.** If t
21dc0 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  he 3rd parameter
21dd0 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
21de0 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65  _v2() is not one
21df0 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 69   of the.** combi
21e00 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62  nations shown ab
21e10 6f 76 65 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63  ove optionally c
21e20 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 6f 74 68  ombined with oth
21e30 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  er.** [SQLITE_OP
21e40 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 53 51  EN_READONLY | SQ
21e50 4c 49 54 45 5f 4f 50 45 4e 5f 2a 20 62 69 74 73  LITE_OPEN_* bits
21e60 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 62 65  ].** then the be
21e70 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69  havior is undefi
21e80 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ned..**.** ^If t
21e90 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
21ea0 4e 4f 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73  NOMUTEX] flag is
21eb0 20 73 65 74 2c 20 74 68 65 6e 20 74 68 65 20 64   set, then the d
21ec0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
21ed0 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e 20 74  on.** opens in t
21ee0 68 65 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 20  he multi-thread 
21ef0 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
21f00 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20   as long as the 
21f10 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 0a 2a 2a  single-thread.**
21f20 20 6d 6f 64 65 20 68 61 73 20 6e 6f 74 20 62 65   mode has not be
21f30 65 6e 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c  en set at compil
21f40 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d  e-time or start-
21f50 74 69 6d 65 2e 20 20 5e 49 66 20 74 68 65 0a 2a  time.  ^If the.*
21f60 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46  * [SQLITE_OPEN_F
21f70 55 4c 4c 4d 55 54 45 58 5d 20 66 6c 61 67 20 69  ULLMUTEX] flag i
21f80 73 20 73 65 74 20 74 68 65 6e 20 74 68 65 20 64  s set then the d
21f90 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
21fa0 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20 74  on opens.** in t
21fb0 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74  he serialized [t
21fc0 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 75  hreading mode] u
21fd0 6e 6c 65 73 73 20 73 69 6e 67 6c 65 2d 74 68 72  nless single-thr
21fe0 65 61 64 20 77 61 73 0a 2a 2a 20 70 72 65 76 69  ead was.** previ
21ff0 6f 75 73 6c 79 20 73 65 6c 65 63 74 65 64 20 61  ously selected a
22000 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  t compile-time o
22010 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a  r start-time..**
22020 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50   ^The [SQLITE_OP
22030 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d 20  EN_SHAREDCACHE] 
22040 66 6c 61 67 20 63 61 75 73 65 73 20 74 68 65 20  flag causes the 
22050 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
22060 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 65 6c 69  ion to be.** eli
22070 67 69 62 6c 65 20 74 6f 20 75 73 65 20 5b 73 68  gible to use [sh
22080 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d  ared cache mode]
22090 2c 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20  , regardless of 
220a0 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73  whether or not s
220b0 68 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 69  hared.** cache i
220c0 73 20 65 6e 61 62 6c 65 64 20 75 73 69 6e 67 20  s enabled using 
220d0 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f  [sqlite3_enable_
220e0 73 68 61 72 65 64 5f 63 61 63 68 65 28 29 5d 2e  shared_cache()].
220f0 20 20 5e 54 68 65 0a 2a 2a 20 5b 53 51 4c 49 54    ^The.** [SQLIT
22100 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41  E_OPEN_PRIVATECA
22110 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73  CHE] flag causes
22120 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
22130 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 6e 6f 74 0a  nnection to not.
22140 2a 2a 20 70 61 72 74 69 63 69 70 61 74 65 20 69  ** participate i
22150 6e 20 5b 73 68 61 72 65 64 20 63 61 63 68 65 20  n [shared cache 
22160 6d 6f 64 65 5d 20 65 76 65 6e 20 69 66 20 69 74  mode] even if it
22170 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a   is enabled..**.
22180 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70  ** ^The fourth p
22190 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
221a0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73  te3_open_v2() is
221b0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
221c0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  .** [sqlite3_vfs
221d0 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65  ] object that de
221e0 66 69 6e 65 73 20 74 68 65 20 6f 70 65 72 61 74  fines the operat
221f0 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72  ing system inter
22200 66 61 63 65 20 74 68 61 74 0a 2a 2a 20 74 68 65  face that.** the
22210 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f   new database co
22220 6e 6e 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20  nnection should 
22230 75 73 65 2e 20 20 5e 49 66 20 74 68 65 20 66 6f  use.  ^If the fo
22240 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  urth parameter i
22250 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  s.** a NULL poin
22260 74 65 72 20 74 68 65 6e 20 74 68 65 20 64 65 66  ter then the def
22270 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66  ault [sqlite3_vf
22280 73 5d 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65  s] object is use
22290 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  d..**.** ^If the
222a0 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d   filename is ":m
222b0 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61 20  emory:", then a 
222c0 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61  private, tempora
222d0 72 79 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74  ry in-memory dat
222e0 61 62 61 73 65 0a 2a 2a 20 69 73 20 63 72 65 61  abase.** is crea
222f0 74 65 64 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e  ted for the conn
22300 65 63 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 69  ection.  ^This i
22310 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73  n-memory databas
22320 65 20 77 69 6c 6c 20 76 61 6e 69 73 68 20 77 68  e will vanish wh
22330 65 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  en.** the databa
22340 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
22350 20 63 6c 6f 73 65 64 2e 20 20 46 75 74 75 72 65   closed.  Future
22360 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
22370 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b  ite might.** mak
22380 65 20 75 73 65 20 6f 66 20 61 64 64 69 74 69 6f  e use of additio
22390 6e 61 6c 20 73 70 65 63 69 61 6c 20 66 69 6c 65  nal special file
223a0 6e 61 6d 65 73 20 74 68 61 74 20 62 65 67 69 6e  names that begin
223b0 20 77 69 74 68 20 74 68 65 20 22 3a 22 20 63 68   with the ":" ch
223c0 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49 74 20 69  aracter..** It i
223d0 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68  s recommended th
223e0 61 74 20 77 68 65 6e 20 61 20 64 61 74 61 62 61  at when a databa
223f0 73 65 20 66 69 6c 65 6e 61 6d 65 20 61 63 74 75  se filename actu
22400 61 6c 6c 79 20 64 6f 65 73 20 62 65 67 69 6e 20  ally does begin 
22410 77 69 74 68 0a 2a 2a 20 61 20 22 3a 22 20 63 68  with.** a ":" ch
22420 61 72 61 63 74 65 72 20 79 6f 75 20 73 68 6f 75  aracter you shou
22430 6c 64 20 70 72 65 66 69 78 20 74 68 65 20 66 69  ld prefix the fi
22440 6c 65 6e 61 6d 65 20 77 69 74 68 20 61 20 70 61  lename with a pa
22450 74 68 6e 61 6d 65 20 73 75 63 68 20 61 73 0a 2a  thname such as.*
22460 2a 20 22 2e 2f 22 20 74 6f 20 61 76 6f 69 64 20  * "./" to avoid 
22470 61 6d 62 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a  ambiguity..**.**
22480 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d   ^If the filenam
22490 65 20 69 73 20 61 6e 20 65 6d 70 74 79 20 73 74  e is an empty st
224a0 72 69 6e 67 2c 20 74 68 65 6e 20 61 20 70 72 69  ring, then a pri
224b0 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 0a  vate, temporary.
224c0 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62  ** on-disk datab
224d0 61 73 65 20 77 69 6c 6c 20 62 65 20 63 72 65 61  ase will be crea
224e0 74 65 64 2e 20 20 5e 54 68 69 73 20 70 72 69 76  ted.  ^This priv
224f0 61 74 65 20 64 61 74 61 62 61 73 65 20 77 69 6c  ate database wil
22500 6c 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69  l be.** automati
22510 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 61 73  cally deleted as
22520 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 64 61 74   soon as the dat
22530 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
22540 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a   is closed..**.*
22550 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65  * [[URI filename
22560 73 20 69 6e 20 73 71 6c 69 74 65 33 5f 6f 70 65  s in sqlite3_ope
22570 6e 28 29 5d 5d 20 3c 68 33 3e 55 52 49 20 46 69  n()]] <h3>URI Fi
22580 6c 65 6e 61 6d 65 73 3c 2f 68 33 3e 0a 2a 2a 0a  lenames</h3>.**.
22590 2a 2a 20 5e 49 66 20 5b 55 52 49 20 66 69 6c 65  ** ^If [URI file
225a0 6e 61 6d 65 5d 20 69 6e 74 65 72 70 72 65 74 61  name] interpreta
225b0 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2c  tion is enabled,
225c0 20 61 6e 64 20 74 68 65 20 66 69 6c 65 6e 61 6d   and the filenam
225d0 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 62 65  e argument.** be
225e0 67 69 6e 73 20 77 69 74 68 20 22 66 69 6c 65 3a  gins with "file:
225f0 22 2c 20 74 68 65 6e 20 74 68 65 20 66 69 6c 65  ", then the file
22600 6e 61 6d 65 20 69 73 20 69 6e 74 65 72 70 72 65  name is interpre
22610 74 65 64 20 61 73 20 61 20 55 52 49 2e 20 5e 55  ted as a URI. ^U
22620 52 49 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69  RI.** filename i
22630 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73  nterpretation is
22640 20 65 6e 61 62 6c 65 64 20 69 66 20 74 68 65 20   enabled if the 
22650 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49  [SQLITE_OPEN_URI
22660 5d 20 66 6c 61 67 20 69 73 0a 2a 2a 20 73 65 74  ] flag is.** set
22670 20 69 6e 20 74 68 65 20 66 6f 75 72 74 68 20 61   in the fourth a
22680 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
22690 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2c 20 6f 72  e3_open_v2(), or
226a0 20 69 66 20 69 74 20 68 61 73 0a 2a 2a 20 62 65   if it has.** be
226b0 65 6e 20 65 6e 61 62 6c 65 64 20 67 6c 6f 62 61  en enabled globa
226c0 6c 6c 79 20 75 73 69 6e 67 20 74 68 65 20 5b 53  lly using the [S
226d0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49  QLITE_CONFIG_URI
226e0 5d 20 6f 70 74 69 6f 6e 20 77 69 74 68 20 74 68  ] option with th
226f0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  e.** [sqlite3_co
22700 6e 66 69 67 28 29 5d 20 6d 65 74 68 6f 64 20 6f  nfig()] method o
22710 72 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45  r by the [SQLITE
22720 5f 55 53 45 5f 55 52 49 5d 20 63 6f 6d 70 69 6c  _USE_URI] compil
22730 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a  e-time option..*
22740 2a 20 41 73 20 6f 66 20 53 51 4c 69 74 65 20 76  * As of SQLite v
22750 65 72 73 69 6f 6e 20 33 2e 37 2e 37 2c 20 55 52  ersion 3.7.7, UR
22760 49 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72  I filename inter
22770 70 72 65 74 61 74 69 6f 6e 20 69 73 20 74 75 72  pretation is tur
22780 6e 65 64 20 6f 66 66 0a 2a 2a 20 62 79 20 64 65  ned off.** by de
22790 66 61 75 6c 74 2c 20 62 75 74 20 66 75 74 75 72  fault, but futur
227a0 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51  e releases of SQ
227b0 4c 69 74 65 20 6d 69 67 68 74 20 65 6e 61 62 6c  Lite might enabl
227c0 65 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 0a 2a  e URI filename.*
227d0 2a 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e  * interpretation
227e0 20 62 79 20 64 65 66 61 75 6c 74 2e 20 20 53 65   by default.  Se
227f0 65 20 22 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65  e "[URI filename
22800 73 5d 22 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  s]" for addition
22810 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  al.** informatio
22820 6e 2e 0a 2a 2a 0a 2a 2a 20 55 52 49 20 66 69 6c  n..**.** URI fil
22830 65 6e 61 6d 65 73 20 61 72 65 20 70 61 72 73 65  enames are parse
22840 64 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 52  d according to R
22850 46 43 20 33 39 38 36 2e 20 5e 49 66 20 74 68 65  FC 3986. ^If the
22860 20 55 52 49 20 63 6f 6e 74 61 69 6e 73 20 61 6e   URI contains an
22870 0a 2a 2a 20 61 75 74 68 6f 72 69 74 79 2c 20 74  .** authority, t
22880 68 65 6e 20 69 74 20 6d 75 73 74 20 62 65 20 65  hen it must be e
22890 69 74 68 65 72 20 61 6e 20 65 6d 70 74 79 20 73  ither an empty s
228a0 74 72 69 6e 67 20 6f 72 20 74 68 65 20 73 74 72  tring or the str
228b0 69 6e 67 20 0a 2a 2a 20 22 6c 6f 63 61 6c 68 6f  ing .** "localho
228c0 73 74 22 2e 20 5e 49 66 20 74 68 65 20 61 75 74  st". ^If the aut
228d0 68 6f 72 69 74 79 20 69 73 20 6e 6f 74 20 61 6e  hority is not an
228e0 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72   empty string or
228f0 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2c 20 61 6e   "localhost", an
22900 20 0a 2a 2a 20 65 72 72 6f 72 20 69 73 20 72 65   .** error is re
22910 74 75 72 6e 65 64 20 74 6f 20 74 68 65 20 63 61  turned to the ca
22920 6c 6c 65 72 2e 20 5e 54 68 65 20 66 72 61 67 6d  ller. ^The fragm
22930 65 6e 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66  ent component of
22940 20 61 20 55 52 49 2c 20 69 66 20 0a 2a 2a 20 70   a URI, if .** p
22950 72 65 73 65 6e 74 2c 20 69 73 20 69 67 6e 6f 72  resent, is ignor
22960 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74  ed..**.** ^SQLit
22970 65 20 75 73 65 73 20 74 68 65 20 70 61 74 68 20  e uses the path 
22980 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 74 68 65  component of the
22990 20 55 52 49 20 61 73 20 74 68 65 20 6e 61 6d 65   URI as the name
229a0 20 6f 66 20 74 68 65 20 64 69 73 6b 20 66 69 6c   of the disk fil
229b0 65 0a 2a 2a 20 77 68 69 63 68 20 63 6f 6e 74 61  e.** which conta
229c0 69 6e 73 20 74 68 65 20 64 61 74 61 62 61 73 65  ins the database
229d0 2e 20 5e 49 66 20 74 68 65 20 70 61 74 68 20 62  . ^If the path b
229e0 65 67 69 6e 73 20 77 69 74 68 20 61 20 27 2f 27  egins with a '/'
229f0 20 63 68 61 72 61 63 74 65 72 2c 20 0a 2a 2a 20   character, .** 
22a00 74 68 65 6e 20 69 74 20 69 73 20 69 6e 74 65 72  then it is inter
22a10 70 72 65 74 65 64 20 61 73 20 61 6e 20 61 62 73  preted as an abs
22a20 6f 6c 75 74 65 20 70 61 74 68 2e 20 5e 49 66 20  olute path. ^If 
22a30 74 68 65 20 70 61 74 68 20 64 6f 65 73 20 6e 6f  the path does no
22a40 74 20 62 65 67 69 6e 20 0a 2a 2a 20 77 69 74 68  t begin .** with
22a50 20 61 20 27 2f 27 20 28 6d 65 61 6e 69 6e 67 20   a '/' (meaning 
22a60 74 68 61 74 20 74 68 65 20 61 75 74 68 6f 72 69  that the authori
22a70 74 79 20 73 65 63 74 69 6f 6e 20 69 73 20 6f 6d  ty section is om
22a80 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 55  itted from the U
22a90 52 49 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  RI).** then the 
22aa0 70 61 74 68 20 69 73 20 69 6e 74 65 72 70 72 65  path is interpre
22ab0 74 65 64 20 61 73 20 61 20 72 65 6c 61 74 69 76  ted as a relativ
22ac0 65 20 70 61 74 68 2e 20 0a 2a 2a 20 5e 4f 6e 20  e path. .** ^On 
22ad0 77 69 6e 64 6f 77 73 2c 20 74 68 65 20 66 69 72  windows, the fir
22ae0 73 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20  st component of 
22af0 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 74 68  an absolute path
22b00 20 0a 2a 2a 20 69 73 20 61 20 64 72 69 76 65 20   .** is a drive 
22b10 73 70 65 63 69 66 69 63 61 74 69 6f 6e 20 28 65  specification (e
22b20 2e 67 2e 20 22 43 3a 22 29 2e 0a 2a 2a 0a 2a 2a  .g. "C:")..**.**
22b30 20 5b 5b 63 6f 72 65 20 55 52 49 20 71 75 65 72   [[core URI quer
22b40 79 20 70 61 72 61 6d 65 74 65 72 73 5d 5d 0a 2a  y parameters]].*
22b50 2a 20 54 68 65 20 71 75 65 72 79 20 63 6f 6d 70  * The query comp
22b60 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20 6d  onent of a URI m
22b70 61 79 20 63 6f 6e 74 61 69 6e 20 70 61 72 61 6d  ay contain param
22b80 65 74 65 72 73 20 74 68 61 74 20 61 72 65 20 69  eters that are i
22b90 6e 74 65 72 70 72 65 74 65 64 0a 2a 2a 20 65 69  nterpreted.** ei
22ba0 74 68 65 72 20 62 79 20 53 51 4c 69 74 65 20 69  ther by SQLite i
22bb0 74 73 65 6c 66 2c 20 6f 72 20 62 79 20 61 20 5b  tself, or by a [
22bc0 56 46 53 20 7c 20 63 75 73 74 6f 6d 20 56 46 53  VFS | custom VFS
22bd0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 5d   implementation]
22be0 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65  ..** SQLite inte
22bf0 72 70 72 65 74 73 20 74 68 65 20 66 6f 6c 6c 6f  rprets the follo
22c00 77 69 6e 67 20 74 68 72 65 65 20 71 75 65 72 79  wing three query
22c10 20 70 61 72 61 6d 65 74 65 72 73 3a 0a 2a 2a 0a   parameters:.**.
22c20 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69  ** <ul>.**   <li
22c30 3e 20 3c 62 3e 76 66 73 3c 2f 62 3e 3a 20 5e 54  > <b>vfs</b>: ^T
22c40 68 65 20 22 76 66 73 22 20 70 61 72 61 6d 65 74  he "vfs" paramet
22c50 65 72 20 6d 61 79 20 62 65 20 75 73 65 64 20 74  er may be used t
22c60 6f 20 73 70 65 63 69 66 79 20 74 68 65 20 6e 61  o specify the na
22c70 6d 65 20 6f 66 0a 2a 2a 20 20 20 20 20 61 20 56  me of.**     a V
22c80 46 53 20 6f 62 6a 65 63 74 20 74 68 61 74 20 70  FS object that p
22c90 72 6f 76 69 64 65 73 20 74 68 65 20 6f 70 65 72  rovides the oper
22ca0 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74  ating system int
22cb0 65 72 66 61 63 65 20 74 68 61 74 20 73 68 6f 75  erface that shou
22cc0 6c 64 0a 2a 2a 20 20 20 20 20 62 65 20 75 73 65  ld.**     be use
22cd0 64 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20  d to access the 
22ce0 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 6f 6e  database file on
22cf0 20 64 69 73 6b 2e 20 5e 49 66 20 74 68 69 73 20   disk. ^If this 
22d00 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f  option is set to
22d10 0a 2a 2a 20 20 20 20 20 61 6e 20 65 6d 70 74 79  .**     an empty
22d20 20 73 74 72 69 6e 67 20 74 68 65 20 64 65 66 61   string the defa
22d30 75 6c 74 20 56 46 53 20 6f 62 6a 65 63 74 20 69  ult VFS object i
22d40 73 20 75 73 65 64 2e 20 5e 53 70 65 63 69 66 79  s used. ^Specify
22d50 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a  ing an unknown.*
22d60 2a 20 20 20 20 20 56 46 53 20 69 73 20 61 6e 20  *     VFS is an 
22d70 65 72 72 6f 72 2e 20 5e 49 66 20 73 71 6c 69 74  error. ^If sqlit
22d80 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20  e3_open_v2() is 
22d90 75 73 65 64 20 61 6e 64 20 74 68 65 20 76 66 73  used and the vfs
22da0 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20   option is.**   
22db0 20 20 70 72 65 73 65 6e 74 2c 20 74 68 65 6e 20    present, then 
22dc0 74 68 65 20 56 46 53 20 73 70 65 63 69 66 69 65  the VFS specifie
22dd0 64 20 62 79 20 74 68 65 20 6f 70 74 69 6f 6e 20  d by the option 
22de0 74 61 6b 65 73 20 70 72 65 63 65 64 65 6e 63 65  takes precedence
22df0 20 6f 76 65 72 0a 2a 2a 20 20 20 20 20 74 68 65   over.**     the
22e00 20 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 73   value passed as
22e10 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
22e20 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
22e30 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a  _open_v2()..**.*
22e40 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 6d 6f 64 65  *   <li> <b>mode
22e50 3c 2f 62 3e 3a 20 5e 28 54 68 65 20 6d 6f 64 65  </b>: ^(The mode
22e60 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62   parameter may b
22e70 65 20 73 65 74 20 74 6f 20 65 69 74 68 65 72 20  e set to either 
22e80 22 72 6f 22 2c 20 22 72 77 22 20 6f 72 0a 2a 2a  "ro", "rw" or.**
22e90 20 20 20 20 20 22 72 77 63 22 2e 20 41 74 74 65       "rwc". Atte
22ea0 6d 70 74 69 6e 67 20 74 6f 20 73 65 74 20 69 74  mpting to set it
22eb0 20 74 6f 20 61 6e 79 20 6f 74 68 65 72 20 76 61   to any other va
22ec0 6c 75 65 20 69 73 20 61 6e 20 65 72 72 6f 72 29  lue is an error)
22ed0 5e 2e 20 0a 2a 2a 20 20 20 20 20 5e 49 66 20 22  ^. .**     ^If "
22ee0 72 6f 22 20 69 73 20 73 70 65 63 69 66 69 65 64  ro" is specified
22ef0 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  , then the datab
22f00 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f  ase is opened fo
22f10 72 20 72 65 61 64 2d 6f 6e 6c 79 20 0a 2a 2a 20  r read-only .** 
22f20 20 20 20 20 61 63 63 65 73 73 2c 20 6a 75 73 74      access, just
22f30 20 61 73 20 69 66 20 74 68 65 20 5b 53 51 4c 49   as if the [SQLI
22f40 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
22f50 5d 20 66 6c 61 67 20 68 61 64 20 62 65 65 6e 20  ] flag had been 
22f60 73 65 74 20 69 6e 20 74 68 65 20 0a 2a 2a 20 20  set in the .**  
22f70 20 20 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e     third argumen
22f80 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 70 72 65  t to sqlite3_pre
22f90 70 61 72 65 5f 76 32 28 29 2e 20 5e 49 66 20 74  pare_v2(). ^If t
22fa0 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69  he mode option i
22fb0 73 20 73 65 74 20 74 6f 20 0a 2a 2a 20 20 20 20  s set to .**    
22fc0 20 22 72 77 22 2c 20 74 68 65 6e 20 74 68 65 20   "rw", then the 
22fd0 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
22fe0 65 64 20 66 6f 72 20 72 65 61 64 2d 77 72 69 74  ed for read-writ
22ff0 65 20 28 62 75 74 20 6e 6f 74 20 63 72 65 61 74  e (but not creat
23000 65 29 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73  e) .**     acces
23010 73 2c 20 61 73 20 69 66 20 53 51 4c 49 54 45 5f  s, as if SQLITE_
23020 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 28  OPEN_READWRITE (
23030 62 75 74 20 6e 6f 74 20 53 51 4c 49 54 45 5f 4f  but not SQLITE_O
23040 50 45 4e 5f 43 52 45 41 54 45 29 20 68 61 64 20  PEN_CREATE) had 
23050 0a 2a 2a 20 20 20 20 20 62 65 65 6e 20 73 65 74  .**     been set
23060 2e 20 5e 56 61 6c 75 65 20 22 72 77 63 22 20 69  . ^Value "rwc" i
23070 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20  s equivalent to 
23080 73 65 74 74 69 6e 67 20 62 6f 74 68 20 0a 2a 2a  setting both .**
23090 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e       SQLITE_OPEN
230a0 5f 52 45 41 44 57 52 49 54 45 20 61 6e 64 20 53  _READWRITE and S
230b0 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
230c0 45 2e 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f  E. ^If sqlite3_o
230d0 70 65 6e 5f 76 32 28 29 20 69 73 20 0a 2a 2a 20  pen_v2() is .** 
230e0 20 20 20 20 75 73 65 64 2c 20 69 74 20 69 73 20      used, it is 
230f0 61 6e 20 65 72 72 6f 72 20 74 6f 20 73 70 65 63  an error to spec
23100 69 66 79 20 61 20 76 61 6c 75 65 20 66 6f 72 20  ify a value for 
23110 74 68 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74  the mode paramet
23120 65 72 20 74 68 61 74 20 69 73 20 0a 2a 2a 20 20  er that is .**  
23130 20 20 20 6c 65 73 73 20 72 65 73 74 72 69 63 74     less restrict
23140 69 76 65 20 74 68 61 6e 20 74 68 61 74 20 73 70  ive than that sp
23150 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 66  ecified by the f
23160 6c 61 67 73 20 70 61 73 73 65 64 20 61 73 20 74  lags passed as t
23170 68 65 20 74 68 69 72 64 20 0a 2a 2a 20 20 20 20  he third .**    
23180 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
23190 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 63 61 63 68  *   <li> <b>cach
231a0 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 63 61 63 68  e</b>: ^The cach
231b0 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  e parameter may 
231c0 62 65 20 73 65 74 20 74 6f 20 65 69 74 68 65 72  be set to either
231d0 20 22 73 68 61 72 65 64 22 20 6f 72 0a 2a 2a 20   "shared" or.** 
231e0 20 20 20 20 22 70 72 69 76 61 74 65 22 2e 20 5e      "private". ^
231f0 53 65 74 74 69 6e 67 20 69 74 20 74 6f 20 22 73  Setting it to "s
23200 68 61 72 65 64 22 20 69 73 20 65 71 75 69 76 61  hared" is equiva
23210 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20  lent to setting 
23220 74 68 65 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54  the.**     SQLIT
23230 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43  E_OPEN_SHAREDCAC
23240 48 45 20 62 69 74 20 69 6e 20 74 68 65 20 66 6c  HE bit in the fl
23250 61 67 73 20 61 72 67 75 6d 65 6e 74 20 70 61 73  ags argument pas
23260 73 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20 73 71  sed to.**     sq
23270 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e  lite3_open_v2().
23280 20 5e 53 65 74 74 69 6e 67 20 74 68 65 20 63 61   ^Setting the ca
23290 63 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f  che parameter to
232a0 20 22 70 72 69 76 61 74 65 22 20 69 73 20 0a 2a   "private" is .*
232b0 2a 20 20 20 20 20 65 71 75 69 76 61 6c 65 6e 74  *     equivalent
232c0 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65 20   to setting the 
232d0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56  SQLITE_OPEN_PRIV
232e0 41 54 45 43 41 43 48 45 20 62 69 74 2e 0a 2a 2a  ATECACHE bit..**
232f0 20 20 20 20 20 5e 49 66 20 73 71 6c 69 74 65 33       ^If sqlite3
23300 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73  _open_v2() is us
23310 65 64 20 61 6e 64 20 74 68 65 20 22 63 61 63 68  ed and the "cach
23320 65 22 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  e" parameter is 
23330 70 72 65 73 65 6e 74 20 69 6e 0a 2a 2a 20 20 20  present in.**   
23340 20 20 61 20 55 52 49 20 66 69 6c 65 6e 61 6d 65    a URI filename
23350 2c 20 69 74 73 20 76 61 6c 75 65 20 6f 76 65 72  , its value over
23360 72 69 64 65 73 20 61 6e 79 20 62 65 68 61 76 69  rides any behavi
23370 6f 75 72 20 72 65 71 75 65 73 74 65 64 20 62 79  our requested by
23380 20 73 65 74 74 69 6e 67 0a 2a 2a 20 20 20 20 20   setting.**     
23390 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56  SQLITE_OPEN_PRIV
233a0 41 54 45 43 41 43 48 45 20 6f 72 20 53 51 4c 49  ATECACHE or SQLI
233b0 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41  TE_OPEN_SHAREDCA
233c0 43 48 45 20 66 6c 61 67 2e 0a 2a 2a 20 3c 2f 75  CHE flag..** </u
233d0 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 53 70 65 63 69 66  l>.**.** ^Specif
233e0 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 20  ying an unknown 
233f0 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65  parameter in the
23400 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74   query component
23410 20 6f 66 20 61 20 55 52 49 20 69 73 20 6e 6f 74   of a URI is not
23420 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 2e 20 20 46   an.** error.  F
23430 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
23440 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 75  f SQLite might u
23450 6e 64 65 72 73 74 61 6e 64 20 61 64 64 69 74 69  nderstand additi
23460 6f 6e 61 6c 20 71 75 65 72 79 0a 2a 2a 20 70 61  onal query.** pa
23470 72 61 6d 65 74 65 72 73 2e 20 20 53 65 65 20 22  rameters.  See "
23480 5b 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72  [query parameter
23490 73 20 77 69 74 68 20 73 70 65 63 69 61 6c 20 6d  s with special m
234a0 65 61 6e 69 6e 67 20 74 6f 20 53 51 4c 69 74 65  eaning to SQLite
234b0 5d 22 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69  ]" for.** additi
234c0 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
234d0 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69  ..**.** [[URI fi
234e0 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73 5d  lename examples]
234f0 5d 20 3c 68 33 3e 55 52 49 20 66 69 6c 65 6e 61  ] <h3>URI filena
23500 6d 65 20 65 78 61 6d 70 6c 65 73 3c 2f 68 33 3e  me examples</h3>
23510 0a 2a 2a 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f  .**.** <table bo
23520 72 64 65 72 3d 22 31 22 20 61 6c 69 67 6e 3d 63  rder="1" align=c
23530 65 6e 74 65 72 20 63 65 6c 6c 70 61 64 64 69 6e  enter cellpaddin
23540 67 3d 35 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e  g=5>.** <tr><th>
23550 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 3c   URI filenames <
23560 74 68 3e 20 52 65 73 75 6c 74 73 0a 2a 2a 20 3c  th> Results.** <
23570 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74  tr><td> file:dat
23580 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20  a.db <td> .**   
23590 20 20 20 20 20 20 20 4f 70 65 6e 20 74 68 65 20         Open the 
235a0 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 69  file "data.db" i
235b0 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 69  n the current di
235c0 72 65 63 74 6f 72 79 2e 0a 2a 2a 20 3c 74 72 3e  rectory..** <tr>
235d0 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f  <td> file:/home/
235e0 66 72 65 64 2f 64 61 74 61 2e 64 62 3c 62 72 3e  fred/data.db<br>
235f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c  .**          fil
23600 65 3a 2f 2f 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  e:///home/fred/d
23610 61 74 61 2e 64 62 20 3c 62 72 3e 20 0a 2a 2a 20  ata.db <br> .** 
23620 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f           file://
23630 6c 6f 63 61 6c 68 6f 73 74 2f 68 6f 6d 65 2f 66  localhost/home/f
23640 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e  red/data.db <br>
23650 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20   <td> .**       
23660 20 20 20 4f 70 65 6e 20 74 68 65 20 64 61 74 61     Open the data
23670 62 61 73 65 20 66 69 6c 65 20 22 2f 68 6f 6d 65  base file "/home
23680 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 0a  /fred/data.db"..
23690 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65  ** <tr><td> file
236a0 3a 2f 2f 64 61 72 6b 73 74 61 72 2f 68 6f 6d 65  ://darkstar/home
236b0 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 74  /fred/data.db <t
236c0 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  d> .**          
236d0 41 6e 20 65 72 72 6f 72 2e 20 22 64 61 72 6b 73  An error. "darks
236e0 74 61 72 22 20 69 73 20 6e 6f 74 20 61 20 72 65  tar" is not a re
236f0 63 6f 67 6e 69 7a 65 64 20 61 75 74 68 6f 72 69  cognized authori
23700 74 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 20 73  ty..** <tr><td s
23710 74 79 6c 65 3d 22 77 68 69 74 65 2d 73 70 61 63  tyle="white-spac
23720 65 3a 6e 6f 77 72 61 70 22 3e 20 0a 2a 2a 20 20  e:nowrap"> .**  
23730 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f          file:///
23740 43 3a 2f 44 6f 63 75 6d 65 6e 74 73 25 32 30 61  C:/Documents%20a
23750 6e 64 25 32 30 53 65 74 74 69 6e 67 73 2f 66 72  nd%20Settings/fr
23760 65 64 2f 44 65 73 6b 74 6f 70 2f 64 61 74 61 2e  ed/Desktop/data.
23770 64 62 0a 2a 2a 20 20 20 20 20 3c 74 64 3e 20 57  db.**     <td> W
23780 69 6e 64 6f 77 73 20 6f 6e 6c 79 3a 20 4f 70 65  indows only: Ope
23790 6e 20 74 68 65 20 66 69 6c 65 20 22 64 61 74 61  n the file "data
237a0 2e 64 62 22 20 6f 6e 20 66 72 65 64 27 73 20 64  .db" on fred's d
237b0 65 73 6b 74 6f 70 20 6f 6e 20 64 72 69 76 65 0a  esktop on drive.
237c0 2a 2a 20 20 20 20 20 20 20 20 20 20 43 3a 2e 20  **          C:. 
237d0 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 25 32  Note that the %2
237e0 30 20 65 73 63 61 70 69 6e 67 20 69 6e 20 74 68  0 escaping in th
237f0 69 73 20 65 78 61 6d 70 6c 65 20 69 73 20 6e 6f  is example is no
23800 74 20 73 74 72 69 63 74 6c 79 20 0a 2a 2a 20 20  t strictly .**  
23810 20 20 20 20 20 20 20 20 6e 65 63 65 73 73 61 72          necessar
23820 79 20 2d 20 73 70 61 63 65 20 63 68 61 72 61 63  y - space charac
23830 74 65 72 73 20 63 61 6e 20 62 65 20 75 73 65 64  ters can be used
23840 20 6c 69 74 65 72 61 6c 6c 79 0a 2a 2a 20 20 20   literally.**   
23850 20 20 20 20 20 20 20 69 6e 20 55 52 49 20 66 69         in URI fi
23860 6c 65 6e 61 6d 65 73 2e 0a 2a 2a 20 3c 74 72 3e  lenames..** <tr>
23870 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64  <td> file:data.d
23880 62 3f 6d 6f 64 65 3d 72 6f 26 63 61 63 68 65 3d  b?mode=ro&cache=
23890 70 72 69 76 61 74 65 20 3c 74 64 3e 20 0a 2a 2a  private <td> .**
238a0 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 66            Open f
238b0 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 69 6e  ile "data.db" in
238c0 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 69 72   the current dir
238d0 65 63 74 6f 72 79 20 66 6f 72 20 72 65 61 64 2d  ectory for read-
238e0 6f 6e 6c 79 20 61 63 63 65 73 73 2e 0a 2a 2a 20  only access..** 
238f0 20 20 20 20 20 20 20 20 20 52 65 67 61 72 64 6c           Regardl
23900 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f  ess of whether o
23910 72 20 6e 6f 74 20 73 68 61 72 65 64 2d 63 61 63  r not shared-cac
23920 68 65 20 6d 6f 64 65 20 69 73 20 65 6e 61 62 6c  he mode is enabl
23930 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20  ed by.**        
23940 20 20 64 65 66 61 75 6c 74 2c 20 75 73 65 20 61    default, use a
23950 20 70 72 69 76 61 74 65 20 63 61 63 68 65 2e 0a   private cache..
23960 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65  ** <tr><td> file
23970 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61  :/home/fred/data
23980 2e 64 62 3f 76 66 73 3d 75 6e 69 78 2d 6e 6f 6c  .db?vfs=unix-nol
23990 6f 63 6b 20 3c 74 64 3e 0a 2a 2a 20 20 20 20 20  ock <td>.**     
239a0 20 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22       Open file "
239b0 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e  /home/fred/data.
239c0 64 62 22 2e 20 55 73 65 20 74 68 65 20 73 70 65  db". Use the spe
239d0 63 69 61 6c 20 56 46 53 20 22 75 6e 69 78 2d 6e  cial VFS "unix-n
239e0 6f 6c 6f 63 6b 22 2e 0a 2a 2a 20 3c 74 72 3e 3c  olock"..** <tr><
239f0 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62  td> file:data.db
23a00 3f 6d 6f 64 65 3d 72 65 61 64 6f 6e 6c 79 20 3c  ?mode=readonly <
23a10 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  td> .**         
23a20 20 41 6e 20 65 72 72 6f 72 2e 20 22 72 65 61 64   An error. "read
23a30 6f 6e 6c 79 22 20 69 73 20 6e 6f 74 20 61 20 76  only" is not a v
23a40 61 6c 69 64 20 6f 70 74 69 6f 6e 20 66 6f 72 20  alid option for 
23a50 74 68 65 20 22 6d 6f 64 65 22 20 70 61 72 61 6d  the "mode" param
23a60 65 74 65 72 2e 0a 2a 2a 20 3c 2f 74 61 62 6c 65  eter..** </table
23a70 3e 0a 2a 2a 0a 2a 2a 20 5e 55 52 49 20 68 65 78  >.**.** ^URI hex
23a80 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20  adecimal escape 
23a90 73 65 71 75 65 6e 63 65 73 20 28 25 48 48 29 20  sequences (%HH) 
23aa0 61 72 65 20 73 75 70 70 6f 72 74 65 64 20 77 69  are supported wi
23ab0 74 68 69 6e 20 74 68 65 20 70 61 74 68 20 61 6e  thin the path an
23ac0 64 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6d 70 6f  d.** query compo
23ad0 6e 65 6e 74 73 20 6f 66 20 61 20 55 52 49 2e 20  nents of a URI. 
23ae0 41 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73  A hexadecimal es
23af0 63 61 70 65 20 73 65 71 75 65 6e 63 65 20 63 6f  cape sequence co
23b00 6e 73 69 73 74 73 20 6f 66 20 61 0a 2a 2a 20 70  nsists of a.** p
23b10 65 72 63 65 6e 74 20 73 69 67 6e 20 2d 20 22 25  ercent sign - "%
23b20 22 20 2d 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  " - followed by 
23b30 65 78 61 63 74 6c 79 20 74 77 6f 20 68 65 78 61  exactly two hexa
23b40 64 65 63 69 6d 61 6c 20 64 69 67 69 74 73 20 0a  decimal digits .
23b50 2a 2a 20 73 70 65 63 69 66 79 69 6e 67 20 61 6e  ** specifying an
23b60 20 6f 63 74 65 74 20 76 61 6c 75 65 2e 20 5e 42   octet value. ^B
23b70 65 66 6f 72 65 20 74 68 65 20 70 61 74 68 20 6f  efore the path o
23b80 72 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e  r query componen
23b90 74 73 20 6f 66 20 61 0a 2a 2a 20 55 52 49 20 66  ts of a.** URI f
23ba0 69 6c 65 6e 61 6d 65 20 61 72 65 20 69 6e 74 65  ilename are inte
23bb0 72 70 72 65 74 65 64 2c 20 74 68 65 79 20 61 72  rpreted, they ar
23bc0 65 20 65 6e 63 6f 64 65 64 20 75 73 69 6e 67 20  e encoded using 
23bd0 55 54 46 2d 38 20 61 6e 64 20 61 6c 6c 20 0a 2a  UTF-8 and all .*
23be0 2a 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73  * hexadecimal es
23bf0 63 61 70 65 20 73 65 71 75 65 6e 63 65 73 20 72  cape sequences r
23c00 65 70 6c 61 63 65 64 20 62 79 20 61 20 73 69 6e  eplaced by a sin
23c10 67 6c 65 20 62 79 74 65 20 63 6f 6e 74 61 69 6e  gle byte contain
23c20 69 6e 67 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65  ing the.** corre
23c30 73 70 6f 6e 64 69 6e 67 20 6f 63 74 65 74 2e 20  sponding octet. 
23c40 49 66 20 74 68 69 73 20 70 72 6f 63 65 73 73 20  If this process 
23c50 67 65 6e 65 72 61 74 65 73 20 61 6e 20 69 6e 76  generates an inv
23c60 61 6c 69 64 20 55 54 46 2d 38 20 65 6e 63 6f 64  alid UTF-8 encod
23c70 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 72 65 73 75  ing,.** the resu
23c80 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65  lts are undefine
23c90 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65  d..**.** <b>Note
23ca0 20 74 6f 20 57 69 6e 64 6f 77 73 20 75 73 65 72   to Windows user
23cb0 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f  s:</b>  The enco
23cc0 64 69 6e 67 20 75 73 65 64 20 66 6f 72 20 74 68  ding used for th
23cd0 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d  e filename argum
23ce0 65 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65  ent.** of sqlite
23cf0 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c  3_open() and sql
23d00 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 6d  ite3_open_v2() m
23d10 75 73 74 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f  ust be UTF-8, no
23d20 74 20 77 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f  t whatever.** co
23d30 64 65 70 61 67 65 20 69 73 20 63 75 72 72 65 6e  depage is curren
23d40 74 6c 79 20 64 65 66 69 6e 65 64 2e 20 20 46 69  tly defined.  Fi
23d50 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69  lenames containi
23d60 6e 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c  ng international
23d70 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 6d  .** characters m
23d80 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64  ust be converted
23d90 20 74 6f 20 55 54 46 2d 38 20 70 72 69 6f 72 20   to UTF-8 prior 
23da0 74 6f 20 70 61 73 73 69 6e 67 20 74 68 65 6d 20  to passing them 
23db0 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  into.** sqlite3_
23dc0 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65  open() or sqlite
23dd0 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2f 0a  3_open_v2()..*/.
23de0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
23df0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63  qlite3_open(.  c
23e00 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e  onst char *filen
23e10 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61  ame,   /* Databa
23e20 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46  se filename (UTF
23e30 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  -8) */.  sqlite3
23e40 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20   **ppDb         
23e50 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20   /* OUT: SQLite 
23e60 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a  db handle */.);.
23e70 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
23e80 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20  qlite3_open16(. 
23e90 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c   const void *fil
23ea0 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61  ename,   /* Data
23eb0 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55  base filename (U
23ec0 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69  TF-16) */.  sqli
23ed0 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20  te3 **ppDb      
23ee0 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69      /* OUT: SQLi
23ef0 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a  te db handle */.
23f00 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
23f10 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  t sqlite3_open_v
23f20 32 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  2(.  const char 
23f30 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20  *filename,   /* 
23f40 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  Database filenam
23f50 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73  e (UTF-8) */.  s
23f60 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c 20 20  qlite3 **ppDb,  
23f70 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53         /* OUT: S
23f80 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20  QLite db handle 
23f90 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 20  */.  int flags, 
23fa0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
23fb0 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74  Flags */.  const
23fc0 20 63 68 61 72 20 2a 7a 56 66 73 20 20 20 20 20   char *zVfs     
23fd0 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46     /* Name of VF
23fe0 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65 20  S module to use 
23ff0 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.);../*.** CAP
24000 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 56 61  I3REF: Obtain Va
24010 6c 75 65 73 20 46 6f 72 20 55 52 49 20 50 61 72  lues For URI Par
24020 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 54 68  ameters.**.** Th
24030 69 73 20 69 73 20 61 20 75 74 69 6c 69 74 79 20  is is a utility 
24040 72 6f 75 74 69 6e 65 2c 20 75 73 65 66 75 6c 20  routine, useful 
24050 74 6f 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  to VFS implement
24060 61 74 69 6f 6e 73 2c 20 74 68 61 74 20 63 68 65  ations, that che
24070 63 6b 73 0a 2a 2a 20 74 6f 20 73 65 65 20 69 66  cks.** to see if
24080 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65   a database file
24090 20 77 61 73 20 61 20 55 52 49 20 74 68 61 74 20   was a URI that 
240a0 63 6f 6e 74 61 69 6e 65 64 20 61 20 73 70 65 63  contained a spec
240b0 69 66 69 63 20 71 75 65 72 79 20 0a 2a 2a 20 70  ific query .** p
240c0 61 72 61 6d 65 74 65 72 2c 20 61 6e 64 20 69 66  arameter, and if
240d0 20 73 6f 20 6f 62 74 61 69 6e 73 20 74 68 65 20   so obtains the 
240e0 76 61 6c 75 65 20 6f 66 20 74 68 65 20 71 75 65  value of the que
240f0 72 79 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  ry parameter..**
24100 0a 2a 2a 20 54 68 65 20 7a 46 69 6c 65 6e 61 6d  .** The zFilenam
24110 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  e argument is th
24120 65 20 66 69 6c 65 6e 61 6d 65 20 70 6f 69 6e 74  e filename point
24130 65 72 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74  er passed into t
24140 68 65 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 6d 65  he xOpen().** me
24150 74 68 6f 64 20 6f 66 20 61 20 56 46 53 20 69 6d  thod of a VFS im
24160 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54  plementation.  T
24170 68 65 20 7a 50 61 72 61 6d 20 61 72 67 75 6d 65  he zParam argume
24180 6e 74 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  nt is the name o
24190 66 20 74 68 65 0a 2a 2a 20 71 75 65 72 79 20 70  f the.** query p
241a0 61 72 61 6d 65 74 65 72 20 77 65 20 73 65 65 6b  arameter we seek
241b0 2e 20 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  .  This routine 
241c0 72 65 74 75 72 6e 73 20 74 68 65 20 76 61 6c 75  returns the valu
241d0 65 20 6f 66 20 74 68 65 20 7a 50 61 72 61 6d 0a  e of the zParam.
241e0 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69 66 20  ** parameter if 
241f0 69 74 20 65 78 69 73 74 73 2e 20 20 49 66 20 74  it exists.  If t
24200 68 65 20 70 61 72 61 6d 65 74 65 72 20 64 6f 65  he parameter doe
24210 73 20 6e 6f 74 20 65 78 69 73 74 2c 20 74 68 69  s not exist, thi
24220 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 72 65 74  s routine.** ret
24230 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  urns a NULL poin
24240 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  ter..**.** If th
24250 65 20 7a 46 69 6c 65 6e 61 6d 65 20 61 72 67 75  e zFilename argu
24260 6d 65 6e 74 20 74 6f 20 74 68 69 73 20 66 75 6e  ment to this fun
24270 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61 20 70  ction is not a p
24280 6f 69 6e 74 65 72 20 74 68 61 74 20 53 51 4c 69  ointer that SQLi
24290 74 65 0a 2a 2a 20 70 61 73 73 65 64 20 69 6e 74  te.** passed int
242a0 6f 20 74 68 65 20 78 4f 70 65 6e 20 56 46 53 20  o the xOpen VFS 
242b0 6d 65 74 68 6f 64 2c 20 74 68 65 6e 20 74 68 65  method, then the
242c0 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 69   behavior of thi
242d0 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 69 73 20  s routine.** is 
242e0 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72  undefined and pr
242f0 6f 62 61 62 6c 79 20 75 6e 64 65 73 69 72 61 62  obably undesirab
24300 6c 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  le..*/.SQLITE_AP
24310 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  I const char *sq
24320 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65  lite3_uri_parame
24330 74 65 72 28 63 6f 6e 73 74 20 63 68 61 72 20 2a  ter(const char *
24340 7a 46 69 6c 65 6e 61 6d 65 2c 20 63 6f 6e 73 74  zFilename, const
24350 20 63 68 61 72 20 2a 7a 50 61 72 61 6d 29 3b 0a   char *zParam);.
24360 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
24370 3a 20 45 72 72 6f 72 20 43 6f 64 65 73 20 41 6e  : Error Codes An
24380 64 20 4d 65 73 73 61 67 65 73 0a 2a 2a 0a 2a 2a  d Messages.**.**
24390 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72   ^The sqlite3_er
243a0 72 63 6f 64 65 28 29 20 69 6e 74 65 72 66 61 63  rcode() interfac
243b0 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  e returns the nu
243c0 6d 65 72 69 63 20 5b 72 65 73 75 6c 74 20 63 6f  meric [result co
243d0 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e  de] or.** [exten
243e0 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d  ded result code]
243f0 20 66 6f 72 20 74 68 65 20 6d 6f 73 74 20 72 65   for the most re
24400 63 65 6e 74 20 66 61 69 6c 65 64 20 73 71 6c 69  cent failed sqli
24410 74 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c 0a 2a  te3_* API call.*
24420 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  * associated wit
24430 68 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  h a [database co
24440 6e 6e 65 63 74 69 6f 6e 5d 2e 20 49 66 20 61 20  nnection]. If a 
24450 70 72 69 6f 72 20 41 50 49 20 63 61 6c 6c 20 66  prior API call f
24460 61 69 6c 65 64 0a 2a 2a 20 62 75 74 20 74 68 65  ailed.** but the
24470 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 41 50 49   most recent API
24480 20 63 61 6c 6c 20 73 75 63 63 65 65 64 65 64 2c   call succeeded,
24490 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
244a0 65 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65  e from.** sqlite
244b0 33 5f 65 72 72 63 6f 64 65 28 29 20 69 73 20 75  3_errcode() is u
244c0 6e 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 20  ndefined.  ^The 
244d0 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
244e0 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20 69 6e  _errcode().** in
244f0 74 65 72 66 61 63 65 20 69 73 20 74 68 65 20 73  terface is the s
24500 61 6d 65 20 65 78 63 65 70 74 20 74 68 61 74 20  ame except that 
24510 69 74 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e  it always return
24520 73 20 74 68 65 20 0a 2a 2a 20 5b 65 78 74 65 6e  s the .** [exten
24530 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d  ded result code]
24540 20 65 76 65 6e 20 77 68 65 6e 20 65 78 74 65 6e   even when exten
24550 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
24560 20 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64   are.** disabled
24570 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
24580 69 74 65 33 5f 65 72 72 6d 73 67 28 29 20 61 6e  ite3_errmsg() an
24590 64 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67  d sqlite3_errmsg
245a0 31 36 28 29 20 72 65 74 75 72 6e 20 45 6e 67 6c  16() return Engl
245b0 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a 20  ish-language.** 
245c0 74 65 78 74 20 74 68 61 74 20 64 65 73 63 72 69  text that descri
245d0 62 65 73 20 74 68 65 20 65 72 72 6f 72 2c 20 61  bes the error, a
245e0 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f  s either UTF-8 o
245f0 72 20 55 54 46 2d 31 36 20 72 65 73 70 65 63 74  r UTF-16 respect
24600 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f  ively..** ^(Memo
24610 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65  ry to hold the e
24620 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72  rror message str
24630 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69  ing is managed i
24640 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68  nternally..** Th
24650 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f  e application do
24660 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 77  es not need to w
24670 6f 72 72 79 20 61 62 6f 75 74 20 66 72 65 65 69  orry about freei
24680 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a  ng the result..*
24690 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20 65  * However, the e
246a0 72 72 6f 72 20 73 74 72 69 6e 67 20 6d 69 67 68  rror string migh
246b0 74 20 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e  t be overwritten
246c0 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   or deallocated 
246d0 62 79 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74  by.** subsequent
246e0 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65 72 20   calls to other 
246f0 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
24700 20 66 75 6e 63 74 69 6f 6e 73 2e 29 5e 0a 2a 2a   functions.)^.**
24710 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 73 65 72  .** When the ser
24720 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69  ialized [threadi
24730 6e 67 20 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75  ng mode] is in u
24740 73 65 2c 20 69 74 20 6d 69 67 68 74 20 62 65 20  se, it might be 
24750 74 68 65 0a 2a 2a 20 63 61 73 65 20 74 68 61 74  the.** case that
24760 20 61 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20   a second error 
24770 6f 63 63 75 72 73 20 6f 6e 20 61 20 73 65 70 61  occurs on a sepa
24780 72 61 74 65 20 74 68 72 65 61 64 20 69 6e 20 62  rate thread in b
24790 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69  etween.** the ti
247a0 6d 65 20 6f 66 20 74 68 65 20 66 69 72 73 74 20  me of the first 
247b0 65 72 72 6f 72 20 61 6e 64 20 74 68 65 20 63 61  error and the ca
247c0 6c 6c 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65  ll to these inte
247d0 72 66 61 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20  rfaces..** When 
247e0 74 68 61 74 20 68 61 70 70 65 6e 73 2c 20 74 68  that happens, th
247f0 65 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 77  e second error w
24800 69 6c 6c 20 62 65 20 72 65 70 6f 72 74 65 64 20  ill be reported 
24810 73 69 6e 63 65 20 74 68 65 73 65 0a 2a 2a 20 69  since these.** i
24820 6e 74 65 72 66 61 63 65 73 20 61 6c 77 61 79 73  nterfaces always
24830 20 72 65 70 6f 72 74 20 74 68 65 20 6d 6f 73 74   report the most
24840 20 72 65 63 65 6e 74 20 72 65 73 75 6c 74 2e 20   recent result. 
24850 20 54 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69   To avoid.** thi
24860 73 2c 20 65 61 63 68 20 74 68 72 65 61 64 20 63  s, each thread c
24870 61 6e 20 6f 62 74 61 69 6e 20 65 78 63 6c 75 73  an obtain exclus
24880 69 76 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b  ive use of the [
24890 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
248a0 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76  ion] D.** by inv
248b0 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d  oking [sqlite3_m
248c0 75 74 65 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c  utex_enter]([sql
248d0 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44  ite3_db_mutex](D
248e0 29 29 20 62 65 66 6f 72 65 20 62 65 67 69 6e 6e  )) before beginn
248f0 69 6e 67 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20  ing.** to use D 
24900 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71  and invoking [sq
24910 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76  lite3_mutex_leav
24920 65 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d  e]([sqlite3_db_m
24930 75 74 65 78 5d 28 44 29 29 20 61 66 74 65 72 0a  utex](D)) after.
24940 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20  ** all calls to 
24950 74 68 65 20 69 6e 74 65 72 66 61 63 65 73 20 6c  the interfaces l
24960 69 73 74 65 64 20 68 65 72 65 20 61 72 65 20 63  isted here are c
24970 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20  ompleted..**.** 
24980 49 66 20 61 6e 20 69 6e 74 65 72 66 61 63 65 20  If an interface 
24990 66 61 69 6c 73 20 77 69 74 68 20 53 51 4c 49 54  fails with SQLIT
249a0 45 5f 4d 49 53 55 53 45 2c 20 74 68 61 74 20 6d  E_MISUSE, that m
249b0 65 61 6e 73 20 74 68 65 20 69 6e 74 65 72 66 61  eans the interfa
249c0 63 65 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65  ce.** was invoke
249d0 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 62 79  d incorrectly by
249e0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
249f0 2e 20 20 49 6e 20 74 68 61 74 20 63 61 73 65 2c  .  In that case,
24a00 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f   the.** error co
24a10 64 65 20 61 6e 64 20 6d 65 73 73 61 67 65 20 6d  de and message m
24a20 61 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65  ay or may not be
24a30 20 73 65 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f   set..*/.SQLITE_
24a40 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
24a50 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20  errcode(sqlite3 
24a60 2a 64 62 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  *db);.SQLITE_API
24a70 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74   int sqlite3_ext
24a80 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 73 71  ended_errcode(sq
24a90 6c 69 74 65 33 20 2a 64 62 29 3b 0a 53 51 4c 49  lite3 *db);.SQLI
24aa0 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61  TE_API const cha
24ab0 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  r *sqlite3_errms
24ac0 67 28 73 71 6c 69 74 65 33 2a 29 3b 0a 53 51 4c  g(sqlite3*);.SQL
24ad0 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f  ITE_API const vo
24ae0 69 64 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d  id *sqlite3_errm
24af0 73 67 31 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a  sg16(sqlite3*);.
24b00 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
24b10 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 4f   SQL Statement O
24b20 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44  bject.** KEYWORD
24b30 53 3a 20 7b 70 72 65 70 61 72 65 64 20 73 74 61  S: {prepared sta
24b40 74 65 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72 65  tement} {prepare
24b50 64 20 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a  d statements}.**
24b60 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20  .** An instance 
24b70 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 72  of this object r
24b80 65 70 72 65 73 65 6e 74 73 20 61 20 73 69 6e 67  epresents a sing
24b90 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  le SQL statement
24ba0 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74  ..** This object
24bb0 20 69 73 20 76 61 72 69 6f 75 73 6c 79 20 6b 6e   is variously kn
24bc0 6f 77 6e 20 61 73 20 61 20 22 70 72 65 70 61 72  own as a "prepar
24bd0 65 64 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72  ed statement" or
24be0 20 61 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65 64 20   a.** "compiled 
24bf0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 22 20 6f  SQL statement" o
24c00 72 20 73 69 6d 70 6c 79 20 61 73 20 61 20 22 73  r simply as a "s
24c10 74 61 74 65 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a  tatement"..**.**
24c20 20 54 68 65 20 6c 69 66 65 20 6f 66 20 61 20 73   The life of a s
24c30 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20  tatement object 
24c40 67 6f 65 73 20 73 6f 6d 65 74 68 69 6e 67 20 6c  goes something l
24c50 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20  ike this:.**.** 
24c60 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65  <ol>.** <li> Cre
24c70 61 74 65 20 74 68 65 20 6f 62 6a 65 63 74 20 75  ate the object u
24c80 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72  sing [sqlite3_pr
24c90 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 61  epare_v2()] or a
24ca0 20 72 65 6c 61 74 65 64 0a 2a 2a 20 20 20 20 20   related.**     
24cb0 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c   function..** <l
24cc0 69 3e 20 42 69 6e 64 20 76 61 6c 75 65 73 20 74  i> Bind values t
24cd0 6f 20 5b 68 6f 73 74 20 70 61 72 61 6d 65 74 65  o [host paramete
24ce0 72 73 5d 20 75 73 69 6e 67 20 74 68 65 20 73 71  rs] using the sq
24cf0 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a  lite3_bind_*().*
24d00 2a 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65  *      interface
24d10 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74  s..** <li> Run t
24d20 68 65 20 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e  he SQL by callin
24d30 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  g [sqlite3_step(
24d40 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74  )] one or more t
24d50 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65  imes..** <li> Re
24d60 73 65 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e  set the statemen
24d70 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
24d80 5f 72 65 73 65 74 28 29 5d 20 74 68 65 6e 20 67  _reset()] then g
24d90 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74  o back.**      t
24da0 6f 20 73 74 65 70 20 32 2e 20 20 44 6f 20 74 68  o step 2.  Do th
24db0 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20  is zero or more 
24dc0 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44  times..** <li> D
24dd0 65 73 74 72 6f 79 20 74 68 65 20 6f 62 6a 65 63  estroy the objec
24de0 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
24df0 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a  _finalize()]..**
24e00 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66   </ol>.**.** Ref
24e10 65 72 20 74 6f 20 64 6f 63 75 6d 65 6e 74 61 74  er to documentat
24e20 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61  ion on individua
24e30 6c 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  l methods above 
24e40 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  for additional.*
24e50 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  * information..*
24e60 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
24e70 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71   sqlite3_stmt sq
24e80 6c 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a  lite3_stmt;../*.
24e90 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e  ** CAPI3REF: Run
24ea0 2d 74 69 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 0a  -time Limits.**.
24eb0 2a 2a 20 5e 28 54 68 69 73 20 69 6e 74 65 72 66  ** ^(This interf
24ec0 61 63 65 20 61 6c 6c 6f 77 73 20 74 68 65 20 73  ace allows the s
24ed0 69 7a 65 20 6f 66 20 76 61 72 69 6f 75 73 20 63  ize of various c
24ee0 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20  onstructs to be 
24ef0 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20  limited.** on a 
24f00 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f  connection by co
24f10 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 2e 20  nnection basis. 
24f20 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   The first param
24f30 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b  eter is the.** [
24f40 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
24f50 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74  ion] whose limit
24f60 20 69 73 20 74 6f 20 62 65 20 73 65 74 20 6f 72   is to be set or
24f70 20 71 75 65 72 69 65 64 2e 20 20 54 68 65 0a 2a   queried.  The.*
24f80 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  * second paramet
24f90 65 72 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65  er is one of the
24fa0 20 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69   [limit categori
24fb0 65 73 5d 20 74 68 61 74 20 64 65 66 69 6e 65 20  es] that define 
24fc0 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f  a.** class of co
24fd0 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 73  nstructs to be s
24fe0 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20 54 68  ize limited.  Th
24ff0 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
25000 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20  r is the.** new 
25010 6c 69 6d 69 74 20 66 6f 72 20 74 68 61 74 20 63  limit for that c
25020 6f 6e 73 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a  onstruct.)^.**.*
25030 2a 20 5e 49 66 20 74 68 65 20 6e 65 77 20 6c 69  * ^If the new li
25040 6d 69 74 20 69 73 20 61 20 6e 65 67 61 74 69 76  mit is a negativ
25050 65 20 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c 69  e number, the li
25060 6d 69 74 20 69 73 20 75 6e 63 68 61 6e 67 65 64  mit is unchanged
25070 2e 0a 2a 2a 20 5e 28 46 6f 72 20 65 61 63 68 20  ..** ^(For each 
25080 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 20 53  limit category S
25090 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e  QLITE_LIMIT_<i>N
250a0 41 4d 45 3c 2f 69 3e 20 74 68 65 72 65 20 69 73  AME</i> there is
250b0 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c   a .** [limits |
250c0 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e   hard upper boun
250d0 64 5d 0a 2a 2a 20 73 65 74 20 61 74 20 63 6f 6d  d].** set at com
250e0 70 69 6c 65 2d 74 69 6d 65 20 62 79 20 61 20 43  pile-time by a C
250f0 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61   preprocessor ma
25100 63 72 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c  cro called.** [l
25110 69 6d 69 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d  imits | SQLITE_M
25120 41 58 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e  AX_<i>NAME</i>].
25130 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49 54  .** (The "_LIMIT
25140 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 69  _" in the name i
25150 73 20 63 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d  s changed to "_M
25160 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74  AX_".))^.** ^Att
25170 65 6d 70 74 73 20 74 6f 20 69 6e 63 72 65 61 73  empts to increas
25180 65 20 61 20 6c 69 6d 69 74 20 61 62 6f 76 65 20  e a limit above 
25190 69 74 73 20 68 61 72 64 20 75 70 70 65 72 20 62  its hard upper b
251a0 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65  ound are.** sile
251b0 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20 74  ntly truncated t
251c0 6f 20 74 68 65 20 68 61 72 64 20 75 70 70 65 72  o the hard upper
251d0 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52   bound..**.** ^R
251e0 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65  egardless of whe
251f0 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20  ther or not the 
25200 6c 69 6d 69 74 20 77 61 73 20 63 68 61 6e 67 65  limit was change
25210 64 2c 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69  d, the .** [sqli
25220 74 65 33 5f 6c 69 6d 69 74 28 29 5d 20 69 6e 74  te3_limit()] int
25230 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
25240 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f  he prior value o
25250 66 20 74 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20  f the limit..** 
25260 5e 48 65 6e 63 65 2c 20 74 6f 20 66 69 6e 64 20  ^Hence, to find 
25270 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75  the current valu
25280 65 20 6f 66 20 61 20 6c 69 6d 69 74 20 77 69 74  e of a limit wit
25290 68 6f 75 74 20 63 68 61 6e 67 69 6e 67 20 69 74  hout changing it
252a0 2c 0a 2a 2a 20 73 69 6d 70 6c 79 20 69 6e 76 6f  ,.** simply invo
252b0 6b 65 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  ke this interfac
252c0 65 20 77 69 74 68 20 74 68 65 20 74 68 69 72 64  e with the third
252d0 20 70 61 72 61 6d 65 74 65 72 20 73 65 74 20 74   parameter set t
252e0 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d  o -1..**.** Run-
252f0 74 69 6d 65 20 6c 69 6d 69 74 73 20 61 72 65 20  time limits are 
25300 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65  intended for use
25310 20 69 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73   in applications
25320 20 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20   that manage.** 
25330 62 6f 74 68 20 74 68 65 69 72 20 6f 77 6e 20 69  both their own i
25340 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65  nternal database
25350 20 61 6e 64 20 61 6c 73 6f 20 64 61 74 61 62 61   and also databa
25360 73 65 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e  ses that are con
25370 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e  trolled.** by un
25380 74 72 75 73 74 65 64 20 65 78 74 65 72 6e 61 6c  trusted external
25390 20 73 6f 75 72 63 65 73 2e 20 20 41 6e 20 65 78   sources.  An ex
253a0 61 6d 70 6c 65 20 61 70 70 6c 69 63 61 74 69 6f  ample applicatio
253b0 6e 20 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a 20  n might be a.** 
253c0 77 65 62 20 62 72 6f 77 73 65 72 20 74 68 61 74  web browser that
253d0 20 68 61 73 20 69 74 73 20 6f 77 6e 20 64 61 74   has its own dat
253e0 61 62 61 73 65 73 20 66 6f 72 20 73 74 6f 72 69  abases for stori
253f0 6e 67 20 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a  ng history and.*
25400 2a 20 73 65 70 61 72 61 74 65 20 64 61 74 61 62  * separate datab
25410 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20  ases controlled 
25420 62 79 20 4a 61 76 61 53 63 72 69 70 74 20 61 70  by JavaScript ap
25430 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c  plications downl
25440 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65  oaded.** off the
25450 20 49 6e 74 65 72 6e 65 74 2e 20 20 54 68 65 20   Internet.  The 
25460 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73  internal databas
25470 65 73 20 63 61 6e 20 62 65 20 67 69 76 65 6e 20  es can be given 
25480 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65  the.** large, de
25490 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44  fault limits.  D
254a0 61 74 61 62 61 73 65 73 20 6d 61 6e 61 67 65 64  atabases managed
254b0 20 62 79 20 65 78 74 65 72 6e 61 6c 20 73 6f 75   by external sou
254c0 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67  rces can.** be g
254d0 69 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65  iven much smalle
254e0 72 20 6c 69 6d 69 74 73 20 64 65 73 69 67 6e 65  r limits designe
254f0 64 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 64  d to prevent a d
25500 65 6e 69 61 6c 20 6f 66 20 73 65 72 76 69 63 65  enial of service
25510 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44 65 76  .** attack.  Dev
25520 65 6c 6f 70 65 72 73 20 6d 69 67 68 74 20 61 6c  elopers might al
25530 73 6f 20 77 61 6e 74 20 74 6f 20 75 73 65 20 74  so want to use t
25540 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  he [sqlite3_set_
25550 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a  authorizer()].**
25560 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 66 75   interface to fu
25570 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e  rther control un
25580 74 72 75 73 74 65 64 20 53 51 4c 2e 20 20 54 68  trusted SQL.  Th
25590 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 64 61  e size of the da
255a0 74 61 62 61 73 65 0a 2a 2a 20 63 72 65 61 74 65  tabase.** create
255b0 64 20 62 79 20 61 6e 20 75 6e 74 72 75 73 74 65  d by an untruste
255c0 64 20 73 63 72 69 70 74 20 63 61 6e 20 62 65 20  d script can be 
255d0 63 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e 67 20  contained using 
255e0 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65  the.** [max_page
255f0 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d  _count] [PRAGMA]
25600 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d  ..**.** New run-
25610 74 69 6d 65 20 6c 69 6d 69 74 20 63 61 74 65 67  time limit categ
25620 6f 72 69 65 73 20 6d 61 79 20 62 65 20 61 64 64  ories may be add
25630 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ed in future rel
25640 65 61 73 65 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45  eases..*/.SQLITE
25650 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
25660 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c  _limit(sqlite3*,
25670 20 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65 77   int id, int new
25680 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  Val);../*.** CAP
25690 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20  I3REF: Run-Time 
256a0 4c 69 6d 69 74 20 43 61 74 65 67 6f 72 69 65 73  Limit Categories
256b0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 6c  .** KEYWORDS: {l
256c0 69 6d 69 74 20 63 61 74 65 67 6f 72 79 7d 20 7b  imit category} {
256d0 2a 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65  *limit categorie
256e0 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  s}.**.** These c
256f0 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20  onstants define 
25700 76 61 72 69 6f 75 73 20 70 65 72 66 6f 72 6d 61  various performa
25710 6e 63 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74 68  nce limits.** th
25720 61 74 20 63 61 6e 20 62 65 20 6c 6f 77 65 72 65  at can be lowere
25730 64 20 61 74 20 72 75 6e 2d 74 69 6d 65 20 75 73  d at run-time us
25740 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d  ing [sqlite3_lim
25750 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 79  it()]..** The sy
25760 6e 6f 70 73 69 73 20 6f 66 20 74 68 65 20 6d 65  nopsis of the me
25770 61 6e 69 6e 67 73 20 6f 66 20 74 68 65 20 76 61  anings of the va
25780 72 69 6f 75 73 20 6c 69 6d 69 74 73 20 69 73 20  rious limits is 
25790 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20  shown below..** 
257a0 41 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  Additional infor
257b0 6d 61 74 69 6f 6e 20 69 73 20 61 76 61 69 6c 61  mation is availa
257c0 62 6c 65 20 61 74 20 5b 6c 69 6d 69 74 73 20 7c  ble at [limits |
257d0 20 4c 69 6d 69 74 73 20 69 6e 20 53 51 4c 69 74   Limits in SQLit
257e0 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a  e]..**.** <dl>.*
257f0 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
25800 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e  _LENGTH]] ^(<dt>
25810 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e  SQLITE_LIMIT_LEN
25820 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  GTH</dt>.** <dd>
25830 54 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65  The maximum size
25840 20 6f 66 20 61 6e 79 20 73 74 72 69 6e 67 20 6f   of any string o
25850 72 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65 20  r BLOB or table 
25860 72 6f 77 2c 20 69 6e 20 62 79 74 65 73 2e 3c 64  row, in bytes.<d
25870 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
25880 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45  ITE_LIMIT_SQL_LE
25890 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  NGTH]] ^(<dt>SQL
258a0 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45  ITE_LIMIT_SQL_LE
258b0 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  NGTH</dt>.** <dd
258c0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e  >The maximum len
258d0 67 74 68 20 6f 66 20 61 6e 20 53 51 4c 20 73 74  gth of an SQL st
258e0 61 74 65 6d 65 6e 74 2c 20 69 6e 20 62 79 74 65  atement, in byte
258f0 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  s.</dd>)^.**.** 
25900 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  [[SQLITE_LIMIT_C
25910 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c 64 74 3e 53 51  OLUMN]] ^(<dt>SQ
25920 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d  LITE_LIMIT_COLUM
25930 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  N</dt>.** <dd>Th
25940 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
25950 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61   of columns in a
25960 20 74 61 62 6c 65 20 64 65 66 69 6e 69 74 69 6f   table definitio
25970 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72  n or in the.** r
25980 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b  esult set of a [
25990 53 45 4c 45 43 54 5d 20 6f 72 20 74 68 65 20 6d  SELECT] or the m
259a0 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
259b0 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69   columns in an i
259c0 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e  ndex.** or in an
259d0 20 4f 52 44 45 52 20 42 59 20 6f 72 20 47 52 4f   ORDER BY or GRO
259e0 55 50 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64  UP BY clause.</d
259f0 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
25a00 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44  ITE_LIMIT_EXPR_D
25a10 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  EPTH]] ^(<dt>SQL
25a20 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44  ITE_LIMIT_EXPR_D
25a30 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  EPTH</dt>.** <dd
25a40 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70  >The maximum dep
25a50 74 68 20 6f 66 20 74 68 65 20 70 61 72 73 65 20  th of the parse 
25a60 74 72 65 65 20 6f 6e 20 61 6e 79 20 65 78 70 72  tree on any expr
25a70 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a  ession.</dd>)^.*
25a80 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
25a90 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c  MIT_COMPOUND_SEL
25aa0 45 43 54 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  ECT]] ^(<dt>SQLI
25ab0 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e  TE_LIMIT_COMPOUN
25ac0 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a  D_SELECT</dt>.**
25ad0 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
25ae0 20 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73   number of terms
25af0 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53   in a compound S
25b00 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e  ELECT statement.
25b10 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
25b20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42  SQLITE_LIMIT_VDB
25b30 45 5f 4f 50 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  E_OP]] ^(<dt>SQL
25b40 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f  ITE_LIMIT_VDBE_O
25b50 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  P</dt>.** <dd>Th
25b60 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
25b70 20 6f 66 20 69 6e 73 74 72 75 63 74 69 6f 6e 73   of instructions
25b80 20 69 6e 20 61 20 76 69 72 74 75 61 6c 20 6d 61   in a virtual ma
25b90 63 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a  chine program.**
25ba0 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65   used to impleme
25bb0 6e 74 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  nt an SQL statem
25bc0 65 6e 74 2e 20 20 54 68 69 73 20 6c 69 6d 69 74  ent.  This limit
25bd0 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c   is not currentl
25be0 79 0a 2a 2a 20 65 6e 66 6f 72 63 65 64 2c 20 74  y.** enforced, t
25bf0 68 6f 75 67 68 20 74 68 61 74 20 6d 69 67 68 74  hough that might
25c00 20 62 65 20 61 64 64 65 64 20 69 6e 20 73 6f 6d   be added in som
25c10 65 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  e future release
25c20 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 3c 2f   of.** SQLite.</
25c30 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
25c40 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54  LITE_LIMIT_FUNCT
25c50 49 4f 4e 5f 41 52 47 5d 5d 20 5e 28 3c 64 74 3e  ION_ARG]] ^(<dt>
25c60 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e  SQLITE_LIMIT_FUN
25c70 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a  CTION_ARG</dt>.*
25c80 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
25c90 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75  m number of argu
25ca0 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63 74  ments on a funct
25cb0 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ion.</dd>)^.**.*
25cc0 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
25cd0 5f 41 54 54 41 43 48 45 44 5d 5d 20 5e 28 3c 64  _ATTACHED]] ^(<d
25ce0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41  t>SQLITE_LIMIT_A
25cf0 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20  TTACHED</dt>.** 
25d00 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
25d10 6e 75 6d 62 65 72 20 6f 66 20 5b 41 54 54 41 43  number of [ATTAC
25d20 48 20 7c 20 61 74 74 61 63 68 65 64 20 64 61 74  H | attached dat
25d30 61 62 61 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e 0a  abases].)^</dd>.
25d40 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
25d50 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52  IMIT_LIKE_PATTER
25d60 4e 5f 4c 45 4e 47 54 48 5d 5d 0a 2a 2a 20 5e 28  N_LENGTH]].** ^(
25d70 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
25d80 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45  _LIKE_PATTERN_LE
25d90 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  NGTH</dt>.** <dd
25da0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e  >The maximum len
25db0 67 74 68 20 6f 66 20 74 68 65 20 70 61 74 74 65  gth of the patte
25dc0 72 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  rn argument to t
25dd0 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20  he [LIKE] or.** 
25de0 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 73  [GLOB] operators
25df0 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
25e00 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41  [SQLITE_LIMIT_VA
25e10 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 5d 0a  RIABLE_NUMBER]].
25e20 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ** ^(<dt>SQLITE_
25e30 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e  LIMIT_VARIABLE_N
25e40 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  UMBER</dt>.** <d
25e50 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 69 6e  d>The maximum in
25e60 64 65 78 20 6e 75 6d 62 65 72 20 6f 66 20 61 6e  dex number of an
25e70 79 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 69 6e  y [parameter] in
25e80 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
25e90 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  t.)^.**.** [[SQL
25ea0 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45  ITE_LIMIT_TRIGGE
25eb0 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e  R_DEPTH]] ^(<dt>
25ec0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49  SQLITE_LIMIT_TRI
25ed0 47 47 45 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a  GGER_DEPTH</dt>.
25ee0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
25ef0 75 6d 20 64 65 70 74 68 20 6f 66 20 72 65 63 75  um depth of recu
25f00 72 73 69 6f 6e 20 66 6f 72 20 74 72 69 67 67 65  rsion for trigge
25f10 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f  rs.</dd>)^.** </
25f20 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  dl>.*/.#define S
25f30 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47  QLITE_LIMIT_LENG
25f40 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TH              
25f50 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20        0.#define 
25f60 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c  SQLITE_LIMIT_SQL
25f70 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 20  _LENGTH         
25f80 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65         1.#define
25f90 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f   SQLITE_LIMIT_CO
25fa0 4c 55 4d 4e 20 20 20 20 20 20 20 20 20 20 20 20  LUMN            
25fb0 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e          2.#defin
25fc0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45  e SQLITE_LIMIT_E
25fd0 58 50 52 5f 44 45 50 54 48 20 20 20 20 20 20 20  XPR_DEPTH       
25fe0 20 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69           3.#defi
25ff0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
26000 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20  COMPOUND_SELECT 
26010 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66            4.#def
26020 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
26030 5f 56 44 42 45 5f 4f 50 20 20 20 20 20 20 20 20  _VDBE_OP        
26040 20 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 65             5.#de
26050 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
26060 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20  T_FUNCTION_ARG  
26070 20 20 20 20 20 20 20 20 20 20 20 20 36 0a 23 64              6.#d
26080 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
26090 49 54 5f 41 54 54 41 43 48 45 44 20 20 20 20 20  IT_ATTACHED     
260a0 20 20 20 20 20 20 20 20 20 20 20 20 20 37 0a 23               7.#
260b0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
260c0 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e  MIT_LIKE_PATTERN
260d0 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 38 0a  _LENGTH       8.
260e0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
260f0 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55  IMIT_VARIABLE_NU
26100 4d 42 45 52 20 20 20 20 20 20 20 20 20 20 20 39  MBER           9
26110 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
26120 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45  LIMIT_TRIGGER_DE
26130 50 54 48 20 20 20 20 20 20 20 20 20 20 20 20 31  PTH            1
26140 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  0../*.** CAPI3RE
26150 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20  F: Compiling An 
26160 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a  SQL Statement.**
26170 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20   KEYWORDS: {SQL 
26180 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c  statement compil
26190 65 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65  er}.**.** To exe
261a0 63 75 74 65 20 61 6e 20 53 51 4c 20 71 75 65 72  cute an SQL quer
261b0 79 2c 20 69 74 20 6d 75 73 74 20 66 69 72 73 74  y, it must first
261c0 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74   be compiled int
261d0 6f 20 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a  o a byte-code.**
261e0 20 70 72 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f   program using o
261f0 6e 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  ne of these rout
26200 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ines..**.** The 
26210 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2c 20  first argument, 
26220 22 64 62 22 2c 20 69 73 20 61 20 5b 64 61 74 61  "db", is a [data
26230 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
26240 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61   obtained from a
26250 0a 2a 2a 20 70 72 69 6f 72 20 73 75 63 63 65 73  .** prior succes
26260 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71  sful call to [sq
26270 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b  lite3_open()], [
26280 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
26290 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
262a0 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 20 54 68  3_open16()].  Th
262b0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
262c0 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68  ction must not h
262d0 61 76 65 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e  ave been closed.
262e0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  .**.** The secon
262f0 64 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71  d argument, "zSq
26300 6c 22 2c 20 69 73 20 74 68 65 20 73 74 61 74 65  l", is the state
26310 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69  ment to be compi
26320 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20  led, encoded.** 
26330 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20  as either UTF-8 
26340 6f 72 20 55 54 46 2d 31 36 2e 20 20 54 68 65 20  or UTF-16.  The 
26350 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
26360 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72  ) and sqlite3_pr
26370 65 70 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e  epare_v2().** in
26380 74 65 72 66 61 63 65 73 20 75 73 65 20 55 54 46  terfaces use UTF
26390 2d 38 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  -8, and sqlite3_
263a0 70 72 65 70 61 72 65 31 36 28 29 20 61 6e 64 20  prepare16() and 
263b0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
263c0 36 5f 76 32 28 29 0a 2a 2a 20 75 73 65 20 55 54  6_v2().** use UT
263d0 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  F-16..**.** ^If 
263e0 74 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65  the nByte argume
263f0 6e 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20  nt is less than 
26400 7a 65 72 6f 2c 20 74 68 65 6e 20 7a 53 71 6c 20  zero, then zSql 
26410 69 73 20 72 65 61 64 20 75 70 20 74 6f 20 74 68  is read up to th
26420 65 0a 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f 20  e.** first zero 
26430 74 65 72 6d 69 6e 61 74 6f 72 2e 20 5e 49 66 20  terminator. ^If 
26440 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67  nByte is non-neg
26450 61 74 69 76 65 2c 20 74 68 65 6e 20 69 74 20 69  ative, then it i
26460 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a  s the maximum.**
26470 20 6e 75 6d 62 65 72 20 6f 66 20 20 62 79 74 65   number of  byte
26480 73 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c  s read from zSql
26490 2e 20 20 5e 57 68 65 6e 20 6e 42 79 74 65 20 69  .  ^When nByte i
264a0 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20  s non-negative, 
264b0 74 68 65 0a 2a 2a 20 7a 53 71 6c 20 73 74 72 69  the.** zSql stri
264c0 6e 67 20 65 6e 64 73 20 61 74 20 65 69 74 68 65  ng ends at eithe
264d0 72 20 74 68 65 20 66 69 72 73 74 20 27 5c 30 30  r the first '\00
264e0 30 27 20 6f 72 20 27 5c 75 30 30 30 30 27 20 63  0' or '\u0000' c
264f0 68 61 72 61 63 74 65 72 20 6f 72 0a 2a 2a 20 74  haracter or.** t
26500 68 65 20 6e 42 79 74 65 2d 74 68 20 62 79 74 65  he nByte-th byte
26510 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65  , whichever come
26520 73 20 66 69 72 73 74 2e 20 49 66 20 74 68 65 20  s first. If the 
26530 63 61 6c 6c 65 72 20 6b 6e 6f 77 73 0a 2a 2a 20  caller knows.** 
26540 74 68 61 74 20 74 68 65 20 73 75 70 70 6c 69 65  that the supplie
26550 64 20 73 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d  d string is nul-
26560 74 65 72 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e  terminated, then
26570 20 74 68 65 72 65 20 69 73 20 61 20 73 6d 61 6c   there is a smal
26580 6c 0a 2a 2a 20 70 65 72 66 6f 72 6d 61 6e 63 65  l.** performance
26590 20 61 64 76 61 6e 74 61 67 65 20 74 6f 20 62 65   advantage to be
265a0 20 67 61 69 6e 65 64 20 62 79 20 70 61 73 73 69   gained by passi
265b0 6e 67 20 61 6e 20 6e 42 79 74 65 20 70 61 72 61  ng an nByte para
265c0 6d 65 74 65 72 20 74 68 61 74 0a 2a 2a 20 69 73  meter that.** is
265d0 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20 6e 75   equal to the nu
265e0 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
265f0 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e   the input strin
26600 67 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f  g <i>including</
26610 69 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65  i>.** the nul-te
26620 72 6d 69 6e 61 74 6f 72 20 62 79 74 65 73 2e 0a  rminator bytes..
26630 2a 2a 0a 2a 2a 20 5e 49 66 20 70 7a 54 61 69 6c  **.** ^If pzTail
26640 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65   is not NULL the
26650 6e 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61 64  n *pzTail is mad
26660 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68  e to point to th
26670 65 20 66 69 72 73 74 20 62 79 74 65 0a 2a 2a 20  e first byte.** 
26680 70 61 73 74 20 74 68 65 20 65 6e 64 20 6f 66 20  past the end of 
26690 74 68 65 20 66 69 72 73 74 20 53 51 4c 20 73 74  the first SQL st
266a0 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e  atement in zSql.
266b0 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73    These routines
266c0 20 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65   only.** compile
266d0 20 74 68 65 20 66 69 72 73 74 20 73 74 61 74 65   the first state
266e0 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2c 20 73 6f  ment in zSql, so
266f0 20 2a 70 7a 54 61 69 6c 20 69 73 20 6c 65 66 74   *pzTail is left
26700 20 70 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20   pointing to.** 
26710 77 68 61 74 20 72 65 6d 61 69 6e 73 20 75 6e 63  what remains unc
26720 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  ompiled..**.** ^
26730 2a 70 70 53 74 6d 74 20 69 73 20 6c 65 66 74 20  *ppStmt is left 
26740 70 6f 69 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f  pointing to a co
26750 6d 70 69 6c 65 64 20 5b 70 72 65 70 61 72 65 64  mpiled [prepared
26760 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
26770 20 63 61 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75   can be.** execu
26780 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ted using [sqlit
26790 65 33 5f 73 74 65 70 28 29 5d 2e 20 20 5e 49 66  e3_step()].  ^If
267a0 20 74 68 65 72 65 20 69 73 20 61 6e 20 65 72 72   there is an err
267b0 6f 72 2c 20 2a 70 70 53 74 6d 74 20 69 73 20 73  or, *ppStmt is s
267c0 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20  et.** to NULL.  
267d0 5e 49 66 20 74 68 65 20 69 6e 70 75 74 20 74 65  ^If the input te
267e0 78 74 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53  xt contains no S
267f0 51 4c 20 28 69 66 20 74 68 65 20 69 6e 70 75 74  QL (if the input
26800 20 69 73 20 61 6e 20 65 6d 70 74 79 0a 2a 2a 20   is an empty.** 
26810 73 74 72 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d  string or a comm
26820 65 6e 74 29 20 74 68 65 6e 20 2a 70 70 53 74 6d  ent) then *ppStm
26830 74 20 69 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c  t is set to NULL
26840 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 69 6e 67  ..** The calling
26850 20 70 72 6f 63 65 64 75 72 65 20 69 73 20 72 65   procedure is re
26860 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64 65  sponsible for de
26870 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6d 70 69  leting the compi
26880 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  led.** SQL state
26890 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  ment using [sqli
268a0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
268b0 61 66 74 65 72 20 69 74 20 68 61 73 20 66 69 6e  after it has fin
268c0 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 0a 2a  ished with it..*
268d0 2a 20 70 70 53 74 6d 74 20 6d 61 79 20 6e 6f 74  * ppStmt may not
268e0 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   be NULL..**.** 
268f0 5e 4f 6e 20 73 75 63 63 65 73 73 2c 20 74 68 65  ^On success, the
26900 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
26910 28 29 20 66 61 6d 69 6c 79 20 6f 66 20 72 6f 75  () family of rou
26920 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51  tines return [SQ
26930 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68  LITE_OK];.** oth
26940 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72  erwise an [error
26950 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e   code] is return
26960 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ed..**.** The sq
26970 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
26980 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70  () and sqlite3_p
26990 72 65 70 61 72 65 31 36 5f 76 32 28 29 20 69 6e  repare16_v2() in
269a0 74 65 72 66 61 63 65 73 20 61 72 65 0a 2a 2a 20  terfaces are.** 
269b0 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20  recommended for 
269c0 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d 73  all new programs
269d0 2e 20 54 68 65 20 74 77 6f 20 6f 6c 64 65 72 20  . The two older 
269e0 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 72  interfaces are r
269f0 65 74 61 69 6e 65 64 0a 2a 2a 20 66 6f 72 20 62  etained.** for b
26a00 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69  ackwards compati
26a10 62 69 6c 69 74 79 2c 20 62 75 74 20 74 68 65 69  bility, but thei
26a20 72 20 75 73 65 20 69 73 20 64 69 73 63 6f 75 72  r use is discour
26a30 61 67 65 64 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65  aged..** ^In the
26a40 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 73   "v2" interfaces
26a50 2c 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73  , the prepared s
26a60 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74  tatement.** that
26a70 20 69 73 20 72 65 74 75 72 6e 65 64 20 28 74 68   is returned (th
26a80 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d  e [sqlite3_stmt]
26a90 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e   object) contain
26aa0 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a  s a copy of the.
26ab0 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20  ** original SQL 
26ac0 74 65 78 74 2e 20 54 68 69 73 20 63 61 75 73 65  text. This cause
26ad0 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  s the [sqlite3_s
26ae0 74 65 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65  tep()] interface
26af0 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20 64 69   to.** behave di
26b00 66 66 65 72 65 6e 74 6c 79 20 69 6e 20 74 68 72  fferently in thr
26b10 65 65 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ee ways:.**.** <
26b20 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e  ol>.** <li>.** ^
26b30 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  If the database 
26b40 73 63 68 65 6d 61 20 63 68 61 6e 67 65 73 2c 20  schema changes, 
26b50 69 6e 73 74 65 61 64 20 6f 66 20 72 65 74 75 72  instead of retur
26b60 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43 48  ning [SQLITE_SCH
26b70 45 4d 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c  EMA] as it.** al
26b80 77 61 79 73 20 75 73 65 64 20 74 6f 20 64 6f 2c  ways used to do,
26b90 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
26ba0 5d 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63  ] will automatic
26bb0 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20 74  ally recompile t
26bc0 68 65 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d  he SQL.** statem
26bd0 65 6e 74 20 61 6e 64 20 74 72 79 20 74 6f 20 72  ent and try to r
26be0 75 6e 20 69 74 20 61 67 61 69 6e 2e 0a 2a 2a 20  un it again..** 
26bf0 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  </li>.**.** <li>
26c00 0a 2a 2a 20 5e 57 68 65 6e 20 61 6e 20 65 72 72  .** ^When an err
26c10 6f 72 20 6f 63 63 75 72 73 2c 20 5b 73 71 6c 69  or occurs, [sqli
26c20 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c  te3_step()] will
26c30 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 74   return one of t
26c40 68 65 20 64 65 74 61 69 6c 65 64 0a 2a 2a 20 5b  he detailed.** [
26c50 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 6f 72 20  error codes] or 
26c60 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20  [extended error 
26c70 63 6f 64 65 73 5d 2e 20 20 5e 54 68 65 20 6c 65  codes].  ^The le
26c80 67 61 63 79 20 62 65 68 61 76 69 6f 72 20 77 61  gacy behavior wa
26c90 73 20 74 68 61 74 0a 2a 2a 20 5b 73 71 6c 69 74  s that.** [sqlit
26ca0 65 33 5f 73 74 65 70 28 29 5d 20 77 6f 75 6c 64  e3_step()] would
26cb0 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20 61 20 67   only return a g
26cc0 65 6e 65 72 69 63 20 5b 53 51 4c 49 54 45 5f 45  eneric [SQLITE_E
26cd0 52 52 4f 52 5d 20 72 65 73 75 6c 74 20 63 6f 64  RROR] result cod
26ce0 65 0a 2a 2a 20 61 6e 64 20 74 68 65 20 61 70 70  e.** and the app
26cf0 6c 69 63 61 74 69 6f 6e 20 77 6f 75 6c 64 20 68  lication would h
26d00 61 76 65 20 74 6f 20 6d 61 6b 65 20 61 20 73 65  ave to make a se
26d10 63 6f 6e 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71  cond call to [sq
26d20 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 0a 2a  lite3_reset()].*
26d30 2a 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69  * in order to fi
26d40 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e  nd the underlyin
26d50 67 20 63 61 75 73 65 20 6f 66 20 74 68 65 20 70  g cause of the p
26d60 72 6f 62 6c 65 6d 2e 20 57 69 74 68 20 74 68 65  roblem. With the
26d70 20 22 76 32 22 20 70 72 65 70 61 72 65 0a 2a 2a   "v2" prepare.**
26d80 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65   interfaces, the
26d90 20 75 6e 64 65 72 6c 79 69 6e 67 20 72 65 61 73   underlying reas
26da0 6f 6e 20 66 6f 72 20 74 68 65 20 65 72 72 6f 72  on for the error
26db0 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d   is returned imm
26dc0 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c  ediately..** </l
26dd0 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a  i>.**.** <li>.**
26de0 20 5e 49 66 20 74 68 65 20 73 70 65 63 69 66 69   ^If the specifi
26df0 63 20 76 61 6c 75 65 20 62 6f 75 6e 64 20 74 6f  c value bound to
26e00 20 5b 70 61 72 61 6d 65 74 65 72 20 7c 20 68 6f   [parameter | ho
26e10 73 74 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e  st parameter] in
26e20 20 74 68 65 20 0a 2a 2a 20 57 48 45 52 45 20 63   the .** WHERE c
26e30 6c 61 75 73 65 20 6d 69 67 68 74 20 69 6e 66 6c  lause might infl
26e40 75 65 6e 63 65 20 74 68 65 20 63 68 6f 69 63 65  uence the choice
26e50 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20 66   of query plan f
26e60 6f 72 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 0a  or a statement,.
26e70 2a 2a 20 74 68 65 6e 20 74 68 65 20 73 74 61 74  ** then the stat
26e80 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 61 75  ement will be au
26e90 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f  tomatically reco
26ea0 6d 70 69 6c 65 64 2c 20 61 73 20 69 66 20 74 68  mpiled, as if th
26eb0 65 72 65 20 68 61 64 20 62 65 65 6e 20 0a 2a 2a  ere had been .**
26ec0 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65   a schema change
26ed0 2c 20 6f 6e 20 74 68 65 20 66 69 72 73 74 20 20  , on the first  
26ee0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
26ef0 20 63 61 6c 6c 20 66 6f 6c 6c 6f 77 69 6e 67 20   call following 
26f00 61 6e 79 20 63 68 61 6e 67 65 0a 2a 2a 20 74 6f  any change.** to
26f10 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69   the [sqlite3_bi
26f20 6e 64 5f 74 65 78 74 20 7c 20 62 69 6e 64 69 6e  nd_text | bindin
26f30 67 73 5d 20 6f 66 20 74 68 61 74 20 5b 70 61 72  gs] of that [par
26f40 61 6d 65 74 65 72 5d 2e 20 0a 2a 2a 20 5e 54 68  ameter]. .** ^Th
26f50 65 20 73 70 65 63 69 66 69 63 20 76 61 6c 75 65  e specific value
26f60 20 6f 66 20 57 48 45 52 45 2d 63 6c 61 75 73 65   of WHERE-clause
26f70 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 6d 69 67   [parameter] mig
26f80 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65  ht influence the
26f90 20 0a 2a 2a 20 63 68 6f 69 63 65 20 6f 66 20 71   .** choice of q
26fa0 75 65 72 79 20 70 6c 61 6e 20 69 66 20 74 68 65  uery plan if the
26fb0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
26fc0 65 20 6c 65 66 74 2d 68 61 6e 64 20 73 69 64 65  e left-hand side
26fd0 20 6f 66 20 61 20 5b 4c 49 4b 45 5d 0a 2a 2a 20   of a [LIKE].** 
26fe0 6f 72 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74  or [GLOB] operat
26ff0 6f 72 20 6f 72 20 69 66 20 74 68 65 20 70 61 72  or or if the par
27000 61 6d 65 74 65 72 20 69 73 20 63 6f 6d 70 61 72  ameter is compar
27010 65 64 20 74 6f 20 61 6e 20 69 6e 64 65 78 65 64  ed to an indexed
27020 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 6e 64 20 74   column.** and t
27030 68 65 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  he [SQLITE_ENABL
27040 45 5f 53 54 41 54 32 5d 20 63 6f 6d 70 69 6c 65  E_STAT2] compile
27050 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20  -time option is 
27060 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 74 68 65 20  enabled..** the 
27070 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f  .** </li>.** </o
27080 6c 3e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  l>.*/.SQLITE_API
27090 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65   int sqlite3_pre
270a0 70 61 72 65 28 0a 20 20 73 71 6c 69 74 65 33 20  pare(.  sqlite3 
270b0 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
270c0 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64  /* Database hand
270d0 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  le */.  const ch
270e0 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20  ar *zSql,       
270f0 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  /* SQL statement
27100 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20  , UTF-8 encoded 
27110 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20  */.  int nByte, 
27120 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
27130 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  Maximum length o
27140 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e  f zSql in bytes.
27150 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74   */.  sqlite3_st
27160 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a  mt **ppStmt,  /*
27170 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20   OUT: Statement 
27180 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
27190 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20  t char **pzTail 
271a0 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e      /* OUT: Poin
271b0 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f  ter to unused po
271c0 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f  rtion of zSql */
271d0 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .);.SQLITE_API i
271e0 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nt sqlite3_prepa
271f0 72 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33  re_v2(.  sqlite3
27200 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
27210 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
27220 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
27230 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  har *zSql,      
27240 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
27250 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64  t, UTF-8 encoded
27260 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c   */.  int nByte,
27270 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
27280 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   Maximum length 
27290 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73  of zSql in bytes
272a0 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73  . */.  sqlite3_s
272b0 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f  tmt **ppStmt,  /
272c0 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74  * OUT: Statement
272d0 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
272e0 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c  st char **pzTail
272f0 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69       /* OUT: Poi
27300 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70  nter to unused p
27310 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a  ortion of zSql *
27320 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  /.);.SQLITE_API 
27330 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70  int sqlite3_prep
27340 61 72 65 31 36 28 0a 20 20 73 71 6c 69 74 65 33  are16(.  sqlite3
27350 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
27360 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
27370 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  dle */.  const v
27380 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  oid *zSql,      
27390 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
273a0 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65  t, UTF-16 encode
273b0 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
273c0 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
273d0 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
273e0 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
273f0 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  s. */.  sqlite3_
27400 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
27410 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
27420 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
27430 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69  nst void **pzTai
27440 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
27450 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
27460 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
27470 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  */.);.SQLITE_API
27480 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65   int sqlite3_pre
27490 70 61 72 65 31 36 5f 76 32 28 0a 20 20 73 71 6c  pare16_v2(.  sql
274a0 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
274b0 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
274c0 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
274d0 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20  st void *zSql,  
274e0 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74       /* SQL stat
274f0 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e  ement, UTF-16 en
27500 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e  coded */.  int n
27510 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20  Byte,           
27520 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65     /* Maximum le
27530 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20  ngth of zSql in 
27540 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69  bytes. */.  sqli
27550 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d  te3_stmt **ppStm
27560 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74  t,  /* OUT: Stat
27570 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a  ement handle */.
27580 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70    const void **p
27590 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54  zTail     /* OUT
275a0 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75  : Pointer to unu
275b0 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a  sed portion of z
275c0 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  Sql */.);../*.**
275d0 20 43 41 50 49 33 52 45 46 3a 20 52 65 74 72 69   CAPI3REF: Retri
275e0 65 76 69 6e 67 20 53 74 61 74 65 6d 65 6e 74 20  eving Statement 
275f0 53 51 4c 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  SQL.**.** ^This 
27600 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65  interface can be
27610 20 75 73 65 64 20 74 6f 20 72 65 74 72 69 65 76   used to retriev
27620 65 20 61 20 73 61 76 65 64 20 63 6f 70 79 20 6f  e a saved copy o
27630 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 0a 2a  f the original.*
27640 2a 20 53 51 4c 20 74 65 78 74 20 75 73 65 64 20  * SQL text used 
27650 74 6f 20 63 72 65 61 74 65 20 61 20 5b 70 72 65  to create a [pre
27660 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
27670 20 69 66 20 74 68 61 74 20 73 74 61 74 65 6d 65   if that stateme
27680 6e 74 20 77 61 73 0a 2a 2a 20 63 6f 6d 70 69 6c  nt was.** compil
27690 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 20  ed using either 
276a0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
276b0 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  _v2()] or [sqlit
276c0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
276d0 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  )]..*/.SQLITE_AP
276e0 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  I const char *sq
276f0 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c 69 74 65  lite3_sql(sqlite
27700 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
27710 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
27720 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e   Determine If An
27730 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 57   SQL Statement W
27740 72 69 74 65 73 20 54 68 65 20 44 61 74 61 62 61  rites The Databa
27750 73 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  se.**.** ^The sq
27760 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f  lite3_stmt_reado
27770 6e 6c 79 28 58 29 20 69 6e 74 65 72 66 61 63 65  nly(X) interface
27780 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 6e   returns true (n
27790 6f 6e 2d 7a 65 72 6f 29 20 69 66 0a 2a 2a 20 61  on-zero) if.** a
277a0 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 5b  nd only if the [
277b0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
277c0 6e 74 5d 20 58 20 6d 61 6b 65 73 20 6e 6f 20 64  nt] X makes no d
277d0 69 72 65 63 74 20 63 68 61 6e 67 65 73 20 74 6f  irect changes to
277e0 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  .** the content 
277f0 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
27800 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65  file..**.** Note
27810 20 74 68 61 74 20 5b 61 70 70 6c 69 63 61 74 69   that [applicati
27820 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
27830 75 6e 63 74 69 6f 6e 73 5d 20 6f 72 0a 2a 2a 20  unctions] or.** 
27840 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 5d  [virtual tables]
27850 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20 74 68   might change th
27860 65 20 64 61 74 61 62 61 73 65 20 69 6e 64 69 72  e database indir
27870 65 63 74 6c 79 20 61 73 20 61 20 73 69 64 65 20  ectly as a side 
27880 65 66 66 65 63 74 2e 20 20 0a 2a 2a 20 5e 28 46  effect.  .** ^(F
27890 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 61  or example, if a
278a0 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65  n application de
278b0 66 69 6e 65 73 20 61 20 66 75 6e 63 74 69 6f 6e  fines a function
278c0 20 22 65 76 61 6c 28 29 22 20 74 68 61 74 20 0a   "eval()" that .
278d0 2a 2a 20 63 61 6c 6c 73 20 5b 73 71 6c 69 74 65  ** calls [sqlite
278e0 33 5f 65 78 65 63 28 29 5d 2c 20 74 68 65 6e 20  3_exec()], then 
278f0 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51  the following SQ
27900 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 6f 75 6c  L statement woul
27910 64 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20  d.** change the 
27920 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 68  database file th
27930 72 6f 75 67 68 20 73 69 64 65 2d 65 66 66 65 63  rough side-effec
27940 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ts:.**.** <block
27950 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
27960 20 20 53 45 4c 45 43 54 20 65 76 61 6c 28 27 44    SELECT eval('D
27970 45 4c 45 54 45 20 46 52 4f 4d 20 74 31 27 29 20  ELETE FROM t1') 
27980 46 52 4f 4d 20 74 32 3b 0a 2a 2a 20 3c 2f 70 72  FROM t2;.** </pr
27990 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
279a0 2a 2a 0a 2a 2a 20 42 75 74 20 62 65 63 61 75 73  **.** But becaus
279b0 65 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73  e the [SELECT] s
279c0 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f  tatement does no
279d0 74 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74  t change the dat
279e0 61 62 61 73 65 20 66 69 6c 65 0a 2a 2a 20 64 69  abase file.** di
279f0 72 65 63 74 6c 79 2c 20 73 71 6c 69 74 65 33 5f  rectly, sqlite3_
27a00 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20  stmt_readonly() 
27a10 77 6f 75 6c 64 20 73 74 69 6c 6c 20 72 65 74 75  would still retu
27a20 72 6e 20 74 72 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a  rn true.)^.**.**
27a30 20 5e 54 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f   ^Transaction co
27a40 6e 74 72 6f 6c 20 73 74 61 74 65 6d 65 6e 74 73  ntrol statements
27a50 20 73 75 63 68 20 61 73 20 5b 42 45 47 49 4e 5d   such as [BEGIN]
27a60 2c 20 5b 43 4f 4d 4d 49 54 5d 2c 20 5b 52 4f 4c  , [COMMIT], [ROL
27a70 4c 42 41 43 4b 5d 2c 0a 2a 2a 20 5b 53 41 56 45  LBACK],.** [SAVE
27a80 50 4f 49 4e 54 5d 2c 20 61 6e 64 20 5b 52 45 4c  POINT], and [REL
27a90 45 41 53 45 5d 20 63 61 75 73 65 20 73 71 6c 69  EASE] cause sqli
27aa0 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c  te3_stmt_readonl
27ab0 79 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72  y() to return tr
27ac0 75 65 2c 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65  ue,.** since the
27ad0 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 65 6d   statements them
27ae0 73 65 6c 76 65 73 20 64 6f 20 6e 6f 74 20 61 63  selves do not ac
27af0 74 75 61 6c 6c 79 20 6d 6f 64 69 66 79 20 74 68  tually modify th
27b00 65 20 64 61 74 61 62 61 73 65 20 62 75 74 0a 2a  e database but.*
27b10 2a 20 72 61 74 68 65 72 20 74 68 65 79 20 63 6f  * rather they co
27b20 6e 74 72 6f 6c 20 74 68 65 20 74 69 6d 69 6e 67  ntrol the timing
27b30 20 6f 66 20 77 68 65 6e 20 6f 74 68 65 72 20 73   of when other s
27b40 74 61 74 65 6d 65 6e 74 73 20 6d 6f 64 69 66 79  tatements modify
27b50 20 74 68 65 20 0a 2a 2a 20 64 61 74 61 62 61 73   the .** databas
27b60 65 2e 20 20 5e 54 68 65 20 5b 41 54 54 41 43 48  e.  ^The [ATTACH
27b70 5d 20 61 6e 64 20 5b 44 45 54 41 43 48 5d 20 73  ] and [DETACH] s
27b80 74 61 74 65 6d 65 6e 74 73 20 61 6c 73 6f 20 63  tatements also c
27b90 61 75 73 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ause.** sqlite3_
27ba0 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20  stmt_readonly() 
27bb0 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65 20 73  to return true s
27bc0 69 6e 63 65 2c 20 77 68 69 6c 65 20 74 68 6f 73  ince, while thos
27bd0 65 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  e statements.** 
27be0 63 68 61 6e 67 65 20 74 68 65 20 63 6f 6e 66 69  change the confi
27bf0 67 75 72 61 74 69 6f 6e 20 6f 66 20 61 20 64 61  guration of a da
27c00 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
27c10 6e 2c 20 74 68 65 79 20 64 6f 20 6e 6f 74 20 6d  n, they do not m
27c20 61 6b 65 20 0a 2a 2a 20 63 68 61 6e 67 65 73 20  ake .** changes 
27c30 74 6f 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f  to the content o
27c40 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  f the database f
27c50 69 6c 65 73 20 6f 6e 20 64 69 73 6b 2e 0a 2a 2f  iles on disk..*/
27c60 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
27c70 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61  sqlite3_stmt_rea
27c80 64 6f 6e 6c 79 28 73 71 6c 69 74 65 33 5f 73 74  donly(sqlite3_st
27c90 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
27ca0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 79 6e  ** CAPI3REF: Dyn
27cb0 61 6d 69 63 61 6c 6c 79 20 54 79 70 65 64 20 56  amically Typed V
27cc0 61 6c 75 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b  alue Object.** K
27cd0 45 59 57 4f 52 44 53 3a 20 7b 70 72 6f 74 65 63  EYWORDS: {protec
27ce0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
27cf0 65 7d 20 7b 75 6e 70 72 6f 74 65 63 74 65 64 20  e} {unprotected 
27d00 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 0a 2a  sqlite3_value}.*
27d10 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73  *.** SQLite uses
27d20 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c   the sqlite3_val
27d30 75 65 20 6f 62 6a 65 63 74 20 74 6f 20 72 65 70  ue object to rep
27d40 72 65 73 65 6e 74 20 61 6c 6c 20 76 61 6c 75 65  resent all value
27d50 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65  s.** that can be
27d60 20 73 74 6f 72 65 64 20 69 6e 20 61 20 64 61 74   stored in a dat
27d70 61 62 61 73 65 20 74 61 62 6c 65 2e 20 53 51 4c  abase table. SQL
27d80 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63  ite uses dynamic
27d90 20 74 79 70 69 6e 67 0a 2a 2a 20 66 6f 72 20 74   typing.** for t
27da0 68 65 20 76 61 6c 75 65 73 20 69 74 20 73 74 6f  he values it sto
27db0 72 65 73 2e 20 20 5e 56 61 6c 75 65 73 20 73 74  res.  ^Values st
27dc0 6f 72 65 64 20 69 6e 20 73 71 6c 69 74 65 33 5f  ored in sqlite3_
27dd0 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 0a 2a 2a  value objects.**
27de0 20 63 61 6e 20 62 65 20 69 6e 74 65 67 65 72 73   can be integers
27df0 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  , floating point
27e00 20 76 61 6c 75 65 73 2c 20 73 74 72 69 6e 67 73   values, strings
27e10 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c  , BLOBs, or NULL
27e20 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 74  ..**.** An sqlit
27e30 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20  e3_value object 
27e40 6d 61 79 20 62 65 20 65 69 74 68 65 72 20 22 70  may be either "p
27e50 72 6f 74 65 63 74 65 64 22 20 6f 72 20 22 75 6e  rotected" or "un
27e60 70 72 6f 74 65 63 74 65 64 22 2e 0a 2a 2a 20 53  protected"..** S
27e70 6f 6d 65 20 69 6e 74 65 72 66 61 63 65 73 20 72  ome interfaces r
27e80 65 71 75 69 72 65 20 61 20 70 72 6f 74 65 63 74  equire a protect
27e90 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
27ea0 2e 20 20 4f 74 68 65 72 20 69 6e 74 65 72 66 61  .  Other interfa
27eb0 63 65 73 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 65  ces.** will acce
27ec0 70 74 20 65 69 74 68 65 72 20 61 20 70 72 6f 74  pt either a prot
27ed0 65 63 74 65 64 20 6f 72 20 61 6e 20 75 6e 70 72  ected or an unpr
27ee0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
27ef0 76 61 6c 75 65 2e 0a 2a 2a 20 45 76 65 72 79 20  value..** Every 
27f00 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 61  interface that a
27f10 63 63 65 70 74 73 20 73 71 6c 69 74 65 33 5f 76  ccepts sqlite3_v
27f20 61 6c 75 65 20 61 72 67 75 6d 65 6e 74 73 20 73  alue arguments s
27f30 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 65 74  pecifies.** whet
27f40 68 65 72 20 6f 72 20 6e 6f 74 20 69 74 20 72 65  her or not it re
27f50 71 75 69 72 65 73 20 61 20 70 72 6f 74 65 63 74  quires a protect
27f60 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
27f70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d  ..**.** The term
27f80 73 20 22 70 72 6f 74 65 63 74 65 64 22 20 61 6e  s "protected" an
27f90 64 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 20  d "unprotected" 
27fa0 72 65 66 65 72 20 74 6f 20 77 68 65 74 68 65 72  refer to whether
27fb0 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74   or not.** a mut
27fc0 65 78 20 69 73 20 68 65 6c 64 2e 20 20 41 6e 20  ex is held.  An 
27fd0 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78 20 69  internal mutex i
27fe0 73 20 68 65 6c 64 20 66 6f 72 20 61 20 70 72 6f  s held for a pro
27ff0 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65  tected.** sqlite
28000 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 62  3_value object b
28010 75 74 20 6e 6f 20 6d 75 74 65 78 20 69 73 20 68  ut no mutex is h
28020 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f  eld for an unpro
28030 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65  tected.** sqlite
28040 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20  3_value object. 
28050 20 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f   If SQLite is co
28060 6d 70 69 6c 65 64 20 74 6f 20 62 65 20 73 69 6e  mpiled to be sin
28070 67 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20  gle-threaded.** 
28080 28 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 54 48  (with [SQLITE_TH
28090 52 45 41 44 53 41 46 45 3d 30 5d 20 61 6e 64 20  READSAFE=0] and 
280a0 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 74 68  with [sqlite3_th
280b0 72 65 61 64 73 61 66 65 28 29 5d 20 72 65 74 75  readsafe()] retu
280c0 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69  rning 0).** or i
280d0 66 20 53 51 4c 69 74 65 20 69 73 20 72 75 6e 20  f SQLite is run 
280e0 69 6e 20 6f 6e 65 20 6f 66 20 72 65 64 75 63 65  in one of reduce
280f0 64 20 6d 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a  d mutex modes .*
28100 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  * [SQLITE_CONFIG
28110 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f  _SINGLETHREAD] o
28120 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  r [SQLITE_CONFIG
28130 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a  _MULTITHREAD].**
28140 20 74 68 65 6e 20 74 68 65 72 65 20 69 73 20 6e   then there is n
28150 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65  o distinction be
28160 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20  tween protected 
28170 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a  and unprotected.
28180 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
28190 20 6f 62 6a 65 63 74 73 20 61 6e 64 20 74 68 65   objects and the
281a0 79 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e  y can be used in
281b0 74 65 72 63 68 61 6e 67 65 61 62 6c 79 2e 20 20  terchangeably.  
281c0 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20  However,.** for 
281d0 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72  maximum code por
281e0 74 61 62 69 6c 69 74 79 20 69 74 20 69 73 20 72  tability it is r
281f0 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20  ecommended that 
28200 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20  applications.** 
28210 73 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64  still make the d
28220 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65  istinction betwe
28230 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64  en protected and
28240 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20   unprotected.** 
28250 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
28260 6a 65 63 74 73 20 65 76 65 6e 20 77 68 65 6e 20  jects even when 
28270 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 72 65 71  not strictly req
28280 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  uired..**.** ^Th
28290 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  e sqlite3_value 
282a0 6f 62 6a 65 63 74 73 20 74 68 61 74 20 61 72 65  objects that are
282b0 20 70 61 73 73 65 64 20 61 73 20 70 61 72 61 6d   passed as param
282c0 65 74 65 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a  eters into the.*
282d0 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
282e0 20 6f 66 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e   of [application
282f0 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
28300 63 74 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74  ctions] are prot
28310 65 63 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73  ected..** ^The s
28320 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
28330 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a  ect returned by.
28340 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
28350 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75  mn_value()] is u
28360 6e 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55  nprotected..** U
28370 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
28380 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
28390 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65   may only be use
283a0 64 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74  d with.** [sqlit
283b0 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
283c0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
283d0 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a  bind_value()]..*
283e0 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  * The [sqlite3_v
283f0 61 6c 75 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69  alue_blob | sqli
28400 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 29  te3_value_type()
28410 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69  ] family of.** i
28420 6e 74 65 72 66 61 63 65 73 20 72 65 71 75 69 72  nterfaces requir
28430 65 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  e protected sqli
28440 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
28450 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  s..*/.typedef st
28460 72 75 63 74 20 4d 65 6d 20 73 71 6c 69 74 65 33  ruct Mem sqlite3
28470 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43  _value;../*.** C
28480 41 50 49 33 52 45 46 3a 20 53 51 4c 20 46 75 6e  API3REF: SQL Fun
28490 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62  ction Context Ob
284a0 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  ject.**.** The c
284b0 6f 6e 74 65 78 74 20 69 6e 20 77 68 69 63 68 20  ontext in which 
284c0 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  an SQL function 
284d0 65 78 65 63 75 74 65 73 20 69 73 20 73 74 6f 72  executes is stor
284e0 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69  ed in an.** sqli
284f0 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65  te3_context obje
28500 63 74 2e 20 20 5e 41 20 70 6f 69 6e 74 65 72 20  ct.  ^A pointer 
28510 74 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f  to an sqlite3_co
28520 6e 74 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20  ntext object.** 
28530 69 73 20 61 6c 77 61 79 73 20 66 69 72 73 74 20  is always first 
28540 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 61 70  parameter to [ap
28550 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
28560 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d  d SQL functions]
28570 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  ..** The applica
28580 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
28590 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
285a0 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61  entation will pa
285b0 73 73 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74  ss this.** point
285c0 65 72 20 74 68 72 6f 75 67 68 20 69 6e 74 6f 20  er through into 
285d0 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
285e0 33 5f 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73  3_result_int | s
285f0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 28 29 5d  qlite3_result()]
28600 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67  ,.** [sqlite3_ag
28610 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
28620 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73 65  )], [sqlite3_use
28630 72 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73  r_data()],.** [s
28640 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64  qlite3_context_d
28650 62 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71  b_handle()], [sq
28660 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74  lite3_get_auxdat
28670 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20  a()],.** and/or 
28680 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78  [sqlite3_set_aux
28690 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65  data()]..*/.type
286a0 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
286b0 65 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69 74  e3_context sqlit
286c0 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a  e3_context;../*.
286d0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 42 69 6e  ** CAPI3REF: Bin
286e0 64 69 6e 67 20 56 61 6c 75 65 73 20 54 6f 20 50  ding Values To P
286f0 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
28700 74 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ts.** KEYWORDS: 
28710 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 7d  {host parameter}
28720 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72   {host parameter
28730 73 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74  s} {host paramet
28740 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57  er name}.** KEYW
28750 4f 52 44 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d  ORDS: {SQL param
28760 65 74 65 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d  eter} {SQL param
28770 65 74 65 72 73 7d 20 7b 70 61 72 61 6d 65 74 65  eters} {paramete
28780 72 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a  r binding}.**.**
28790 20 5e 28 49 6e 20 74 68 65 20 53 51 4c 20 73 74   ^(In the SQL st
287a0 61 74 65 6d 65 6e 74 20 74 65 78 74 20 69 6e 70  atement text inp
287b0 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70  ut to [sqlite3_p
287c0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
287d0 20 69 74 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a   its variants,.*
287e0 2a 20 6c 69 74 65 72 61 6c 73 20 6d 61 79 20 62  * literals may b
287f0 65 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 20  e replaced by a 
28800 5b 70 61 72 61 6d 65 74 65 72 5d 20 74 68 61 74  [parameter] that
28810 20 6d 61 74 63 68 65 73 20 6f 6e 65 20 6f 66 20   matches one of 
28820 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d  following.** tem
28830 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  plates:.**.** <u
28840 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a  l>.** <li>  ?.**
28850 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c   <li>  ?NNN.** <
28860 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69  li>  :VVV.** <li
28870 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20  >  @VVV.** <li> 
28880 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a   $VVV.** </ul>.*
28890 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 74 65 6d 70  *.** In the temp
288a0 6c 61 74 65 73 20 61 62 6f 76 65 2c 20 4e 4e 4e  lates above, NNN
288b0 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 69   represents an i
288c0 6e 74 65 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a  nteger literal,.
288d0 2a 2a 20 61 6e 64 20 56 56 56 20 72 65 70 72 65  ** and VVV repre
288e0 73 65 6e 74 73 20 61 6e 20 61 6c 70 68 61 6e 75  sents an alphanu
288f0 6d 65 72 69 63 20 69 64 65 6e 74 69 66 69 65 72  meric identifier
28900 2e 29 5e 20 20 5e 54 68 65 20 76 61 6c 75 65 73  .)^  ^The values
28910 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 70 61 72   of these.** par
28920 61 6d 65 74 65 72 73 20 28 61 6c 73 6f 20 63 61  ameters (also ca
28930 6c 6c 65 64 20 22 68 6f 73 74 20 70 61 72 61 6d  lled "host param
28940 65 74 65 72 20 6e 61 6d 65 73 22 20 6f 72 20 22  eter names" or "
28950 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 22 29  SQL parameters")
28960 0a 2a 2a 20 63 61 6e 20 62 65 20 73 65 74 20 75  .** can be set u
28970 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33  sing the sqlite3
28980 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e  _bind_*() routin
28990 65 73 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e  es defined here.
289a0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
289b0 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
289c0 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
289d0 28 29 20 72 6f 75 74 69 6e 65 73 20 69 73 20 61  () routines is a
289e0 6c 77 61 79 73 0a 2a 2a 20 61 20 70 6f 69 6e 74  lways.** a point
289f0 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  er to the [sqlit
28a00 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20  e3_stmt] object 
28a10 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a  returned from.**
28a20 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
28a30 65 5f 76 32 28 29 5d 20 6f 72 20 69 74 73 20 76  e_v2()] or its v
28a40 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e  ariants..**.** ^
28a50 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
28a60 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78  ent is the index
28a70 20 6f 66 20 74 68 65 20 53 51 4c 20 70 61 72 61   of the SQL para
28a80 6d 65 74 65 72 20 74 6f 20 62 65 20 73 65 74 2e  meter to be set.
28a90 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73  .** ^The leftmos
28aa0 74 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  t SQL parameter 
28ab0 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20  has an index of 
28ac0 31 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 73 61  1.  ^When the sa
28ad0 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c 20  me named.** SQL 
28ae0 70 61 72 61 6d 65 74 65 72 20 69 73 20 75 73 65  parameter is use
28af0 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65  d more than once
28b00 2c 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62  , second and sub
28b10 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72  sequent.** occur
28b20 72 65 6e 63 65 73 20 68 61 76 65 20 74 68 65 20  rences have the 
28b30 73 61 6d 65 20 69 6e 64 65 78 20 61 73 20 74 68  same index as th
28b40 65 20 66 69 72 73 74 20 6f 63 63 75 72 72 65 6e  e first occurren
28b50 63 65 2e 0a 2a 2a 20 5e 54 68 65 20 69 6e 64 65  ce..** ^The inde
28b60 78 20 66 6f 72 20 6e 61 6d 65 64 20 70 61 72 61  x for named para
28b70 6d 65 74 65 72 73 20 63 61 6e 20 62 65 20 6c 6f  meters can be lo
28b80 6f 6b 65 64 20 75 70 20 75 73 69 6e 67 20 74 68  oked up using th
28b90 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  e.** [sqlite3_bi
28ba0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
28bb0 65 78 28 29 5d 20 41 50 49 20 69 66 20 64 65 73  ex()] API if des
28bc0 69 72 65 64 2e 20 20 5e 54 68 65 20 69 6e 64 65  ired.  ^The inde
28bd0 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20  x.** for "?NNN" 
28be0 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 74 68  parameters is th
28bf0 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a  e value of NNN..
28c00 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20 76 61 6c 75  ** ^The NNN valu
28c10 65 20 6d 75 73 74 20 62 65 20 62 65 74 77 65 65  e must be betwee
28c20 6e 20 31 20 61 6e 64 20 74 68 65 20 5b 73 71 6c  n 1 and the [sql
28c30 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a  ite3_limit()].**
28c40 20 70 61 72 61 6d 65 74 65 72 20 5b 53 51 4c 49   parameter [SQLI
28c50 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c  TE_LIMIT_VARIABL
28c60 45 5f 4e 55 4d 42 45 52 5d 20 28 64 65 66 61 75  E_NUMBER] (defau
28c70 6c 74 20 76 61 6c 75 65 3a 20 39 39 39 29 2e 0a  lt value: 999)..
28c80 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64  **.** ^The third
28c90 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
28ca0 20 76 61 6c 75 65 20 74 6f 20 62 69 6e 64 20 74   value to bind t
28cb0 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e  o the parameter.
28cc0 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f 73  .**.** ^(In thos
28cd0 65 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20  e routines that 
28ce0 68 61 76 65 20 61 20 66 6f 75 72 74 68 20 61 72  have a fourth ar
28cf0 67 75 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c 75  gument, its valu
28d00 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62  e is the.** numb
28d10 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
28d20 68 65 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54  he parameter.  T
28d30 6f 20 62 65 20 63 6c 65 61 72 3a 20 74 68 65 20  o be clear: the 
28d40 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20  value is the.** 
28d50 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79 74  number of <u>byt
28d60 65 73 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76 61  es</u> in the va
28d70 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d  lue, not the num
28d80 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72  ber of character
28d90 73 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  s.)^.** ^If the 
28da0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
28db0 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
28dc0 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20  e length of the 
28dd0 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74 68 65  string is.** the
28de0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
28df0 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74   up to the first
28e00 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
28e10 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66  ..**.** ^The fif
28e20 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  th argument to s
28e30 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
28e40 28 29 2c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  (), sqlite3_bind
28e50 5f 74 65 78 74 28 29 2c 20 61 6e 64 0a 2a 2a 20  _text(), and.** 
28e60 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
28e70 74 31 36 28 29 20 69 73 20 61 20 64 65 73 74 72  t16() is a destr
28e80 75 63 74 6f 72 20 75 73 65 64 20 74 6f 20 64 69  uctor used to di
28e90 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f  spose of the BLO
28ea0 42 20 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20 61  B or.** string a
28eb0 66 74 65 72 20 53 51 4c 69 74 65 20 68 61 73 20  fter SQLite has 
28ec0 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 74  finished with it
28ed0 2e 20 20 5e 54 68 65 20 64 65 73 74 72 75 63 74  .  ^The destruct
28ee0 6f 72 20 69 73 20 63 61 6c 6c 65 64 0a 2a 2a 20  or is called.** 
28ef0 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68  to dispose of th
28f00 65 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67  e BLOB or string
28f10 20 65 76 65 6e 20 69 66 20 74 68 65 20 63 61 6c   even if the cal
28f20 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e  l to sqlite3_bin
28f30 64 5f 62 6c 6f 62 28 29 2c 0a 2a 2a 20 73 71 6c  d_blob(),.** sql
28f40 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29  ite3_bind_text()
28f50 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e  , or sqlite3_bin
28f60 64 5f 74 65 78 74 31 36 28 29 20 66 61 69 6c 73  d_text16() fails
28f70 2e 20 20 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  .  .** ^If the f
28f80 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 69 73  ifth argument is
28f90 0a 2a 2a 20 74 68 65 20 73 70 65 63 69 61 6c 20  .** the special 
28fa0 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53 54  value [SQLITE_ST
28fb0 41 54 49 43 5d 2c 20 74 68 65 6e 20 53 51 4c 69  ATIC], then SQLi
28fc0 74 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20  te assumes that 
28fd0 74 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  the.** informati
28fe0 6f 6e 20 69 73 20 69 6e 20 73 74 61 74 69 63 2c  on is in static,
28ff0 20 75 6e 6d 61 6e 61 67 65 64 20 73 70 61 63 65   unmanaged space
29000 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65   and does not ne
29010 65 64 20 74 6f 20 62 65 20 66 72 65 65 64 2e 0a  ed to be freed..
29020 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74 68  ** ^If the fifth
29030 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20 74 68   argument has th
29040 65 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f  e value [SQLITE_
29050 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e  TRANSIENT], then
29060 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65 73  .** SQLite makes
29070 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65   its own private
29080 20 63 6f 70 79 20 6f 66 20 74 68 65 20 64 61 74   copy of the dat
29090 61 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62  a immediately, b
290a0 65 66 6f 72 65 0a 2a 2a 20 74 68 65 20 73 71 6c  efore.** the sql
290b0 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f  ite3_bind_*() ro
290c0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a  utine returns..*
290d0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
290e0 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28  3_bind_zeroblob(
290f0 29 20 72 6f 75 74 69 6e 65 20 62 69 6e 64 73 20  ) routine binds 
29100 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 68  a BLOB of length
29110 20 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20 66 69   N that.** is fi
29120 6c 6c 65 64 20 77 69 74 68 20 7a 65 72 6f 65 73  lled with zeroes
29130 2e 20 20 5e 41 20 7a 65 72 6f 62 6c 6f 62 20 75  .  ^A zeroblob u
29140 73 65 73 20 61 20 66 69 78 65 64 20 61 6d 6f 75  ses a fixed amou
29150 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20  nt of memory.** 
29160 28 6a 75 73 74 20 61 6e 20 69 6e 74 65 67 65 72  (just an integer
29170 20 74 6f 20 68 6f 6c 64 20 69 74 73 20 73 69 7a   to hold its siz
29180 65 29 20 77 68 69 6c 65 20 69 74 20 69 73 20 62  e) while it is b
29190 65 69 6e 67 20 70 72 6f 63 65 73 73 65 64 2e 0a  eing processed..
291a0 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61 72 65  ** Zeroblobs are
291b0 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 73 65 72   intended to ser
291c0 76 65 20 61 73 20 70 6c 61 63 65 68 6f 6c 64 65  ve as placeholde
291d0 72 73 20 66 6f 72 20 42 4c 4f 42 73 20 77 68 6f  rs for BLOBs who
291e0 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69 73  se.** content is
291f0 20 6c 61 74 65 72 20 77 72 69 74 74 65 6e 20 75   later written u
29200 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
29210 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63  _blob_open | inc
29220 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f  remental BLOB I/
29230 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20  O] routines..** 
29240 5e 41 20 6e 65 67 61 74 69 76 65 20 76 61 6c 75  ^A negative valu
29250 65 20 66 6f 72 20 74 68 65 20 7a 65 72 6f 62 6c  e for the zerobl
29260 6f 62 20 72 65 73 75 6c 74 73 20 69 6e 20 61 20  ob results in a 
29270 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42  zero-length BLOB
29280 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79 20  ..**.** ^If any 
29290 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  of the sqlite3_b
292a0 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73  ind_*() routines
292b0 20 61 72 65 20 63 61 6c 6c 65 64 20 77 69 74 68   are called with
292c0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a   a NULL pointer.
292d0 2a 2a 20 66 6f 72 20 74 68 65 20 5b 70 72 65 70  ** for the [prep
292e0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
292f0 6f 72 20 77 69 74 68 20 61 20 70 72 65 70 61 72  or with a prepar
29300 65 64 20 73 74 61 74 65 6d 65 6e 74 20 66 6f 72  ed statement for
29310 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74   which.** [sqlit
29320 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 62  e3_step()] has b
29330 65 65 6e 20 63 61 6c 6c 65 64 20 6d 6f 72 65 20  een called more 
29340 72 65 63 65 6e 74 6c 79 20 74 68 61 6e 20 5b 73  recently than [s
29350 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c  qlite3_reset()],
29360 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 61 6c  .** then the cal
29370 6c 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53  l will return [S
29380 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20  QLITE_MISUSE].  
29390 49 66 20 61 6e 79 20 73 71 6c 69 74 65 33 5f 62  If any sqlite3_b
293a0 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75 74 69 6e  ind_().** routin
293b0 65 20 69 73 20 70 61 73 73 65 64 20 61 20 5b 70  e is passed a [p
293c0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
293d0 74 5d 20 74 68 61 74 20 68 61 73 20 62 65 65 6e  t] that has been
293e0 20 66 69 6e 61 6c 69 7a 65 64 2c 20 74 68 65 0a   finalized, the.
293f0 2a 2a 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64  ** result is und
29400 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61  efined and proba
29410 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a  bly harmful..**.
29420 2a 2a 20 5e 42 69 6e 64 69 6e 67 73 20 61 72 65  ** ^Bindings are
29430 20 6e 6f 74 20 63 6c 65 61 72 65 64 20 62 79 20   not cleared by 
29440 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  the [sqlite3_res
29450 65 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a  et()] routine..*
29460 2a 20 5e 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d  * ^Unbound param
29470 65 74 65 72 73 20 61 72 65 20 69 6e 74 65 72 70  eters are interp
29480 72 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a  reted as NULL..*
29490 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
294a0 33 5f 62 69 6e 64 5f 2a 20 72 6f 75 74 69 6e 65  3_bind_* routine
294b0 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  s return [SQLITE
294c0 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20  _OK] on success 
294d0 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20  or an.** [error 
294e0 63 6f 64 65 5d 20 69 66 20 61 6e 79 74 68 69 6e  code] if anythin
294f0 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a  g goes wrong..**
29500 20 5e 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d   ^[SQLITE_RANGE]
29510 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20   is returned if 
29520 74 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  the parameter.**
29530 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66   index is out of
29540 20 72 61 6e 67 65 2e 20 20 5e 5b 53 51 4c 49 54   range.  ^[SQLIT
29550 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74 75  E_NOMEM] is retu
29560 72 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63 28 29  rned if malloc()
29570 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53 65   fails..**.** Se
29580 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
29590 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
295a0 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71  count()],.** [sq
295b0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
295c0 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e  eter_name()], an
295d0 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  d [sqlite3_bind_
295e0 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
295f0 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  )]..*/.SQLITE_AP
29600 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  I int sqlite3_bi
29610 6e 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  nd_blob(sqlite3_
29620 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73  stmt*, int, cons
29630 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20  t void*, int n, 
29640 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
29650 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
29660 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75  sqlite3_bind_dou
29670 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ble(sqlite3_stmt
29680 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b  *, int, double);
29690 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
296a0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74  sqlite3_bind_int
296b0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
296c0 69 6e 74 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54  int, int);.SQLIT
296d0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
296e0 33 5f 62 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c  3_bind_int64(sql
296f0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
29700 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b   sqlite3_int64);
29710 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
29720 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c  sqlite3_bind_nul
29730 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  l(sqlite3_stmt*,
29740 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50   int);.SQLITE_AP
29750 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  I int sqlite3_bi
29760 6e 64 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f  nd_text(sqlite3_
29770 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73  stmt*, int, cons
29780 74 20 63 68 61 72 2a 2c 20 69 6e 74 20 6e 2c 20  t char*, int n, 
29790 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
297a0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
297b0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
297c0 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  t16(sqlite3_stmt
297d0 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f  *, int, const vo
297e0 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a  id*, int, void(*
297f0 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54  )(void*));.SQLIT
29800 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
29810 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c  3_bind_value(sql
29820 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
29830 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 76   const sqlite3_v
29840 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41  alue*);.SQLITE_A
29850 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  PI int sqlite3_b
29860 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c  ind_zeroblob(sql
29870 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
29880 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20   int n);../*.** 
29890 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72  CAPI3REF: Number
298a0 20 4f 66 20 53 51 4c 20 50 61 72 61 6d 65 74 65   Of SQL Paramete
298b0 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72  rs.**.** ^This r
298c0 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 75 73  outine can be us
298d0 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e  ed to find the n
298e0 75 6d 62 65 72 20 6f 66 20 5b 53 51 4c 20 70 61  umber of [SQL pa
298f0 72 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 6e 20  rameters].** in 
29900 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
29910 65 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 70 61 72  ement].  SQL par
29920 61 6d 65 74 65 72 73 20 61 72 65 20 74 6f 6b 65  ameters are toke
29930 6e 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72  ns of the.** for
29940 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22  m "?", "?NNN", "
29950 3a 41 41 41 22 2c 20 22 24 41 41 41 22 2c 20 6f  :AAA", "$AAA", o
29960 72 20 22 40 41 41 41 22 20 74 68 61 74 20 73 65  r "@AAA" that se
29970 72 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65 68  rve as.** placeh
29980 6f 6c 64 65 72 73 20 66 6f 72 20 76 61 6c 75 65  olders for value
29990 73 20 74 68 61 74 20 61 72 65 20 5b 73 71 6c 69  s that are [sqli
299a0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20  te3_bind_blob | 
299b0 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68 65  bound].** to the
299c0 20 70 61 72 61 6d 65 74 65 72 73 20 61 74 20 61   parameters at a
299d0 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a   later time..**.
299e0 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e  ** ^(This routin
299f0 65 20 61 63 74 75 61 6c 6c 79 20 72 65 74 75 72  e actually retur
29a00 6e 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20  ns the index of 
29a10 74 68 65 20 6c 61 72 67 65 73 74 20 28 72 69 67  the largest (rig
29a20 68 74 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 61 6d  htmost).** param
29a30 65 74 65 72 2e 20 46 6f 72 20 61 6c 6c 20 66 6f  eter. For all fo
29a40 72 6d 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c  rms except ?NNN,
29a50 20 74 68 69 73 20 77 69 6c 6c 20 63 6f 72 72 65   this will corre
29a60 73 70 6f 6e 64 20 74 6f 20 74 68 65 0a 2a 2a 20  spond to the.** 
29a70 6e 75 6d 62 65 72 20 6f 66 20 75 6e 69 71 75 65  number of unique
29a80 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 49 66   parameters.  If
29a90 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74   parameters of t
29aa0 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61 72 65  he ?NNN form are
29ab0 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 72 65 20   used,.** there 
29ac0 6d 61 79 20 62 65 20 67 61 70 73 20 69 6e 20 74  may be gaps in t
29ad0 68 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a  he list.)^.**.**
29ae0 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
29af0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71  te3_bind_blob|sq
29b00 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a  lite3_bind()],.*
29b10 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
29b20 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29  parameter_name()
29b30 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  ], and.** [sqlit
29b40 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
29b50 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53  r_index()]..*/.S
29b60 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
29b70 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
29b80 65 74 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74  eter_count(sqlit
29b90 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a  e3_stmt*);../*.*
29ba0 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65  * CAPI3REF: Name
29bb0 20 4f 66 20 41 20 48 6f 73 74 20 50 61 72 61 6d   Of A Host Param
29bc0 65 74 65 72 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  eter.**.** ^The 
29bd0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
29be0 61 6d 65 74 65 72 5f 6e 61 6d 65 28 50 2c 4e 29  ameter_name(P,N)
29bf0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
29c00 6e 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f  ns.** the name o
29c10 66 20 74 68 65 20 4e 2d 74 68 20 5b 53 51 4c 20  f the N-th [SQL 
29c20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68  parameter] in th
29c30 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
29c40 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53  ement] P..** ^(S
29c50 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66  QL parameters of
29c60 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22   the form "?NNN"
29c70 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40   or ":AAA" or "@
29c80 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a  AAA" or "$AAA".*
29c90 2a 20 68 61 76 65 20 61 20 6e 61 6d 65 20 77 68  * have a name wh
29ca0 69 63 68 20 69 73 20 74 68 65 20 73 74 72 69 6e  ich is the strin
29cb0 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41  g "?NNN" or ":AA
29cc0 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20  A" or "@AAA" or 
29cd0 22 24 41 41 41 22 0a 2a 2a 20 72 65 73 70 65 63  "$AAA".** respec
29ce0 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74  tively..** In ot
29cf0 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 69  her words, the i
29d00 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72 20 22 24  nitial ":" or "$
29d10 22 20 6f 72 20 22 40 22 20 6f 72 20 22 3f 22 0a  " or "@" or "?".
29d20 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65 64 20 61  ** is included a
29d30 73 20 70 61 72 74 20 6f 66 20 74 68 65 20 6e 61  s part of the na
29d40 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65  me.)^.** ^Parame
29d50 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d  ters of the form
29d60 20 22 3f 22 20 77 69 74 68 6f 75 74 20 61 20 66   "?" without a f
29d70 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65 72  ollowing integer
29d80 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a   have no name.**
29d90 20 61 6e 64 20 61 72 65 20 72 65 66 65 72 72 65   and are referre
29da0 64 20 74 6f 20 61 73 20 22 6e 61 6d 65 6c 65 73  d to as "nameles
29db0 73 22 20 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75 73  s" or "anonymous
29dc0 20 70 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a 2a   parameters"..**
29dd0 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 68  .** ^The first h
29de0 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 68 61  ost parameter ha
29df0 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c  s an index of 1,
29e00 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49   not 0..**.** ^I
29e10 66 20 74 68 65 20 76 61 6c 75 65 20 4e 20 69 73  f the value N is
29e20 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 6f 72   out of range or
29e30 20 69 66 20 74 68 65 20 4e 2d 74 68 20 70 61 72   if the N-th par
29e40 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d  ameter is.** nam
29e50 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c  eless, then NULL
29e60 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 5e   is returned.  ^
29e70 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72  The returned str
29e80 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73  ing is.** always
29e90 20 69 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64 69   in UTF-8 encodi
29ea0 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 6e  ng even if the n
29eb0 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 20 77  amed parameter w
29ec0 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79  as.** originally
29ed0 20 73 70 65 63 69 66 69 65 64 20 61 73 20 55 54   specified as UT
29ee0 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74 65 33  F-16 in [sqlite3
29ef0 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 6f 72  _prepare16()] or
29f00 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
29f10 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a  pare16_v2()]..**
29f20 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
29f30 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
29f40 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d  |sqlite3_bind()]
29f50 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  ,.** [sqlite3_bi
29f60 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75  nd_parameter_cou
29f70 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73  nt()], and.** [s
29f80 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
29f90 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a  meter_index()]..
29fa0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  */.SQLITE_API co
29fb0 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
29fc0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
29fd0 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
29fe0 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  mt*, int);../*.*
29ff0 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 64 65  * CAPI3REF: Inde
2a000 78 20 4f 66 20 41 20 50 61 72 61 6d 65 74 65 72  x Of A Parameter
2a010 20 57 69 74 68 20 41 20 47 69 76 65 6e 20 4e 61   With A Given Na
2a020 6d 65 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e  me.**.** ^Return
2a030 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e   the index of an
2a040 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 67   SQL parameter g
2a050 69 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20  iven its name.  
2a060 5e 54 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61  ^The.** index va
2a070 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69 73 20  lue returned is 
2a080 73 75 69 74 61 62 6c 65 20 66 6f 72 20 75 73 65  suitable for use
2a090 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a   as the second.*
2a0a0 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  * parameter to [
2a0b0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
2a0c0 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29  b|sqlite3_bind()
2a0d0 5d 2e 20 20 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69  ].  ^A zero.** i
2a0e0 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6e 6f  s returned if no
2a0f0 20 6d 61 74 63 68 69 6e 67 20 70 61 72 61 6d 65   matching parame
2a100 74 65 72 20 69 73 20 66 6f 75 6e 64 2e 20 20 5e  ter is found.  ^
2a110 54 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  The parameter.**
2a120 20 6e 61 6d 65 20 6d 75 73 74 20 62 65 20 67 69   name must be gi
2a130 76 65 6e 20 69 6e 20 55 54 46 2d 38 20 65 76 65  ven in UTF-8 eve
2a140 6e 20 69 66 20 74 68 65 20 6f 72 69 67 69 6e 61  n if the origina
2a150 6c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77  l statement.** w
2a160 61 73 20 70 72 65 70 61 72 65 64 20 66 72 6f 6d  as prepared from
2a170 20 55 54 46 2d 31 36 20 74 65 78 74 20 75 73 69   UTF-16 text usi
2a180 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ng [sqlite3_prep
2a190 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a  are16_v2()]..**.
2a1a0 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
2a1b0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
2a1c0 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c  sqlite3_bind()],
2a1d0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
2a1e0 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e  d_parameter_coun
2a1f0 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71  t()], and.** [sq
2a200 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
2a210 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a  eter_index()]..*
2a220 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
2a230 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61   sqlite3_bind_pa
2a240 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 73 71  rameter_index(sq
2a250 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e  lite3_stmt*, con
2a260 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b  st char *zName);
2a270 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2a280 3a 20 52 65 73 65 74 20 41 6c 6c 20 42 69 6e 64  : Reset All Bind
2a290 69 6e 67 73 20 4f 6e 20 41 20 50 72 65 70 61 72  ings On A Prepar
2a2a0 65 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a  ed Statement.**.
2a2b0 2a 2a 20 5e 43 6f 6e 74 72 61 72 79 20 74 6f 20  ** ^Contrary to 
2a2c0 74 68 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66  the intuition of
2a2d0 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f   many, [sqlite3_
2a2e0 72 65 73 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f  reset()] does no
2a2f0 74 20 72 65 73 65 74 0a 2a 2a 20 74 68 65 20 5b  t reset.** the [
2a300 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
2a310 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e  b | bindings] on
2a320 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
2a330 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 65  tement]..** ^Use
2a340 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 74 6f   this routine to
2a350 20 72 65 73 65 74 20 61 6c 6c 20 68 6f 73 74 20   reset all host 
2a360 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 4e 55  parameters to NU
2a370 4c 4c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  LL..*/.SQLITE_AP
2a380 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c  I int sqlite3_cl
2a390 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c  ear_bindings(sql
2a3a0 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a  ite3_stmt*);../*
2a3b0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75  .** CAPI3REF: Nu
2a3c0 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20  mber Of Columns 
2a3d0 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a  In A Result Set.
2a3e0 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68  **.** ^Return th
2a3f0 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  e number of colu
2a400 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c  mns in the resul
2a410 74 20 73 65 74 20 72 65 74 75 72 6e 65 64 20 62  t set returned b
2a420 79 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  y the.** [prepar
2a430 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e  ed statement]. ^
2a440 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74  This routine ret
2a450 75 72 6e 73 20 30 20 69 66 20 70 53 74 6d 74 20  urns 0 if pStmt 
2a460 69 73 20 61 6e 20 53 51 4c 0a 2a 2a 20 73 74 61  is an SQL.** sta
2a470 74 65 6d 65 6e 74 20 74 68 61 74 20 64 6f 65 73  tement that does
2a480 20 6e 6f 74 20 72 65 74 75 72 6e 20 64 61 74 61   not return data
2a490 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 61 6e   (for example an
2a4a0 20 5b 55 50 44 41 54 45 5d 29 2e 0a 2a 2a 0a 2a   [UPDATE])..**.*
2a4b0 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
2a4c0 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
2a4d0 29 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  )].*/.SQLITE_API
2a4e0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c   int sqlite3_col
2a4f0 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65  umn_count(sqlite
2a500 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
2a510 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2a520 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e   Column Names In
2a530 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a   A Result Set.**
2a540 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
2a550 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 6e  nes return the n
2a560 61 6d 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20  ame assigned to 
2a570 61 20 70 61 72 74 69 63 75 6c 61 72 20 63 6f 6c  a particular col
2a580 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65  umn.** in the re
2a590 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53  sult set of a [S
2a5a0 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
2a5b0 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
2a5c0 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a  column_name().**
2a5d0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2a5e0 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
2a5f0 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
2a600 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a  d UTF-8 string.*
2a610 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  * and sqlite3_co
2a620 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65  lumn_name16() re
2a630 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
2a640 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  to a zero-termin
2a650 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73  ated.** UTF-16 s
2a660 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 66 69 72  tring.  ^The fir
2a670 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  st parameter is 
2a680 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
2a690 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74  atement].** that
2a6a0 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20   implements the 
2a6b0 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
2a6c0 6e 74 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  nt. ^The second 
2a6d0 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
2a6e0 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65  .** column numbe
2a6f0 72 2e 20 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73  r.  ^The leftmos
2a700 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62  t column is numb
2a710 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  er 0..**.** ^The
2a720 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67   returned string
2a730 20 70 6f 69 6e 74 65 72 20 69 73 20 76 61 6c 69   pointer is vali
2a740 64 20 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74  d until either t
2a750 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
2a760 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65  tement].** is de
2a770 73 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69  stroyed by [sqli
2a780 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
2a790 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61  or until the sta
2a7a0 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61  tement is automa
2a7b0 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65  tically.** repre
2a7c0 70 61 72 65 64 20 62 79 20 74 68 65 20 66 69 72  pared by the fir
2a7d0 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  st call to [sqli
2a7e0 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20  te3_step()] for 
2a7f0 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e  a particular run
2a800 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65  .** or until the
2a810 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a   next call to.**
2a820 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2a830 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c 69 74 65  name() or sqlite
2a840 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28  3_column_name16(
2a850 29 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 63 6f  ) on the same co
2a860 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  lumn..**.** ^If 
2a870 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
2a880 20 66 61 69 6c 73 20 64 75 72 69 6e 67 20 74 68   fails during th
2a890 65 20 70 72 6f 63 65 73 73 69 6e 67 20 6f 66 20  e processing of 
2a8a0 65 69 74 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a  either routine.*
2a8b0 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 64  * (for example d
2a8c0 75 72 69 6e 67 20 61 20 63 6f 6e 76 65 72 73 69  uring a conversi
2a8d0 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f  on from UTF-8 to
2a8e0 20 55 54 46 2d 31 36 29 20 74 68 65 6e 20 61 0a   UTF-16) then a.
2a8f0 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20  ** NULL pointer 
2a900 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
2a910 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20  ** ^The name of 
2a920 61 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  a result column 
2a930 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  is the value of 
2a940 74 68 65 20 22 41 53 22 20 63 6c 61 75 73 65 20  the "AS" clause 
2a950 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75  for.** that colu
2a960 6d 6e 2c 20 69 66 20 74 68 65 72 65 20 69 73 20  mn, if there is 
2a970 61 6e 20 41 53 20 63 6c 61 75 73 65 2e 20 20 49  an AS clause.  I
2a980 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 41 53  f there is no AS
2a990 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20   clause.** then 
2a9a0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
2a9b0 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65 63  column is unspec
2a9c0 69 66 69 65 64 20 61 6e 64 20 6d 61 79 20 63 68  ified and may ch
2a9d0 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65  ange from.** one
2a9e0 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69   release of SQLi
2a9f0 74 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a  te to the next..
2aa00 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  */.SQLITE_API co
2aa10 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
2aa20 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71  3_column_name(sq
2aa30 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2aa40 20 4e 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20   N);.SQLITE_API 
2aa50 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
2aa60 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31  te3_column_name1
2aa70 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
2aa80 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20   int N);../*.** 
2aa90 43 41 50 49 33 52 45 46 3a 20 53 6f 75 72 63 65  CAPI3REF: Source
2aaa0 20 4f 66 20 44 61 74 61 20 49 6e 20 41 20 51 75   Of Data In A Qu
2aab0 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a  ery Result.**.**
2aac0 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
2aad0 20 70 72 6f 76 69 64 65 20 61 20 6d 65 61 6e 73   provide a means
2aae0 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 74 68   to determine th
2aaf0 65 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c  e database, tabl
2ab00 65 2c 20 61 6e 64 0a 2a 2a 20 74 61 62 6c 65 20  e, and.** table 
2ab10 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73 20 74  column that is t
2ab20 68 65 20 6f 72 69 67 69 6e 20 6f 66 20 61 20 70  he origin of a p
2ab30 61 72 74 69 63 75 6c 61 72 20 72 65 73 75 6c 74  articular result
2ab40 20 63 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 5b 53   column in.** [S
2ab50 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
2ab60 2e 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f  ..** ^The name o
2ab70 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f  f the database o
2ab80 72 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d  r table or colum
2ab90 6e 20 63 61 6e 20 62 65 20 72 65 74 75 72 6e 65  n can be returne
2aba0 64 20 61 73 0a 2a 2a 20 65 69 74 68 65 72 20 61  d as.** either a
2abb0 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36   UTF-8 or UTF-16
2abc0 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 5f   string.  ^The _
2abd0 64 61 74 61 62 61 73 65 5f 20 72 6f 75 74 69 6e  database_ routin
2abe0 65 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65  es return.** the
2abf0 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65 2c 20   database name, 
2ac00 74 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74  the _table_ rout
2ac10 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20  ines return the 
2ac20 74 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a  table name, and.
2ac30 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f 20 72  ** the origin_ r
2ac40 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74  outines return t
2ac50 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a  he column name..
2ac60 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64  ** ^The returned
2ac70 20 73 74 72 69 6e 67 20 69 73 20 76 61 6c 69 64   string is valid
2ac80 20 75 6e 74 69 6c 20 74 68 65 20 5b 70 72 65 70   until the [prep
2ac90 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2aca0 69 73 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20  is destroyed.** 
2acb0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66  using [sqlite3_f
2acc0 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e  inalize()] or un
2acd0 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e  til the statemen
2ace0 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c  t is automatical
2acf0 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64  ly.** reprepared
2ad00 20 62 79 20 74 68 65 20 66 69 72 73 74 20 63 61   by the first ca
2ad10 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
2ad20 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72  tep()] for a par
2ad30 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f  ticular run.** o
2ad40 72 20 75 6e 74 69 6c 20 74 68 65 20 73 61 6d 65  r until the same
2ad50 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20   information is 
2ad60 72 65 71 75 65 73 74 65 64 0a 2a 2a 20 61 67 61  requested.** aga
2ad70 69 6e 20 69 6e 20 61 20 64 69 66 66 65 72 65 6e  in in a differen
2ad80 74 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a  t encoding..**.*
2ad90 2a 20 5e 54 68 65 20 6e 61 6d 65 73 20 72 65 74  * ^The names ret
2ada0 75 72 6e 65 64 20 61 72 65 20 74 68 65 20 6f 72  urned are the or
2adb0 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65  iginal un-aliase
2adc0 64 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a  d names of the.*
2add0 2a 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c  * database, tabl
2ade0 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a  e, and column..*
2adf0 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
2ae00 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 73  argument to thes
2ae10 65 20 69 6e 74 65 72 66 61 63 65 73 20 69 73 20  e interfaces is 
2ae20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
2ae30 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 65 73  ement]..** ^Thes
2ae40 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75  e functions retu
2ae50 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  rn information a
2ae60 62 6f 75 74 20 74 68 65 20 4e 74 68 20 72 65 73  bout the Nth res
2ae70 75 6c 74 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72  ult column retur
2ae80 6e 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 73 74  ned by.** the st
2ae90 61 74 65 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e  atement, where N
2aea0 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66   is the second f
2aeb0 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74  unction argument
2aec0 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 2d 6d  ..** ^The left-m
2aed0 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 63 6f  ost column is co
2aee0 6c 75 6d 6e 20 30 20 66 6f 72 20 74 68 65 73 65  lumn 0 for these
2aef0 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a   routines..**.**
2af00 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c   ^If the Nth col
2af10 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20  umn returned by 
2af20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
2af30 20 61 6e 20 65 78 70 72 65 73 73 69 6f 6e 20 6f   an expression o
2af40 72 0a 2a 2a 20 73 75 62 71 75 65 72 79 20 61 6e  r.** subquery an
2af50 64 20 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d  d is not a colum
2af60 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c  n value, then al
2af70 6c 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74  l of these funct
2af80 69 6f 6e 73 20 72 65 74 75 72 6e 0a 2a 2a 20 4e  ions return.** N
2af90 55 4c 4c 2e 20 20 5e 54 68 65 73 65 20 72 6f 75  ULL.  ^These rou
2afa0 74 69 6e 65 20 6d 69 67 68 74 20 61 6c 73 6f 20  tine might also 
2afb0 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69 66 20 61  return NULL if a
2afc0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
2afd0 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f 63 63 75  on error.** occu
2afe0 72 73 2e 20 20 5e 4f 74 68 65 72 77 69 73 65 2c  rs.  ^Otherwise,
2aff0 20 74 68 65 79 20 72 65 74 75 72 6e 20 74 68 65   they return the
2b000 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 61 74 74   name of the att
2b010 61 63 68 65 64 20 64 61 74 61 62 61 73 65 2c 20  ached database, 
2b020 74 61 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6c  table,.** or col
2b030 75 6d 6e 20 74 68 61 74 20 71 75 65 72 79 20 72  umn that query r
2b040 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 61 73  esult column was
2b050 20 65 78 74 72 61 63 74 65 64 20 66 72 6f 6d 2e   extracted from.
2b060 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 77 69 74 68 20  .**.** ^As with 
2b070 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69 74 65  all other SQLite
2b080 20 41 50 49 73 2c 20 74 68 6f 73 65 20 77 68 6f   APIs, those who
2b090 73 65 20 6e 61 6d 65 73 20 65 6e 64 20 77 69 74  se names end wit
2b0a0 68 20 22 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a  h "16" return.**
2b0b0 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20   UTF-16 encoded 
2b0c0 73 74 72 69 6e 67 73 20 61 6e 64 20 74 68 65 20  strings and the 
2b0d0 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 73 20  other functions 
2b0e0 72 65 74 75 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a  return UTF-8..**
2b0f0 0a 2a 2a 20 5e 54 68 65 73 65 20 41 50 49 73 20  .** ^These APIs 
2b100 61 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62  are only availab
2b110 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72 61 72  le if the librar
2b120 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77  y was compiled w
2b130 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ith the.** [SQLI
2b140 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e  TE_ENABLE_COLUMN
2b150 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d 70 72 65  _METADATA] C-pre
2b160 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c  processor symbol
2b170 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f  ..**.** If two o
2b180 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63  r more threads c
2b190 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  all one or more 
2b1a0 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
2b1b0 73 20 61 67 61 69 6e 73 74 20 74 68 65 20 73 61  s against the sa
2b1c0 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73  me.** prepared s
2b1d0 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c  tatement and col
2b1e0 75 6d 6e 20 61 74 20 74 68 65 20 73 61 6d 65 20  umn at the same 
2b1f0 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65  time then the re
2b200 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64  sults are.** und
2b210 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66  efined..**.** If
2b220 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72   two or more thr
2b230 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72  eads call one or
2b240 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65   more.** [sqlite
2b250 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73  3_column_databas
2b260 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20  e_name | column 
2b270 6d 65 74 61 64 61 74 61 20 69 6e 74 65 72 66 61  metadata interfa
2b280 63 65 73 5d 0a 2a 2a 20 66 6f 72 20 74 68 65 20  ces].** for the 
2b290 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73  same [prepared s
2b2a0 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65  tatement] and re
2b2b0 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61  sult column.** a
2b2c0 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20  t the same time 
2b2d0 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73  then the results
2b2e0 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a   are undefined..
2b2f0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  */.SQLITE_API co
2b300 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
2b310 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73  3_column_databas
2b320 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  e_name(sqlite3_s
2b330 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54  tmt*,int);.SQLIT
2b340 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64  E_API const void
2b350 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
2b360 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 31 36  _database_name16
2b370 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
2b380 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  nt);.SQLITE_API 
2b390 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
2b3a0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65  te3_column_table
2b3b0 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
2b3c0 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45  mt*,int);.SQLITE
2b3d0 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20  _API const void 
2b3e0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
2b3f0 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c  table_name16(sql
2b400 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
2b410 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
2b420 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
2b430 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61  column_origin_na
2b440 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
2b450 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50  ,int);.SQLITE_AP
2b460 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  I const void *sq
2b470 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69  lite3_column_ori
2b480 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74  gin_name16(sqlit
2b490 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a  e3_stmt*,int);..
2b4a0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2b4b0 44 65 63 6c 61 72 65 64 20 44 61 74 61 74 79 70  Declared Datatyp
2b4c0 65 20 4f 66 20 41 20 51 75 65 72 79 20 52 65 73  e Of A Query Res
2b4d0 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  ult.**.** ^(The 
2b4e0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
2b4f0 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  is a [prepared s
2b500 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66  tatement]..** If
2b510 20 74 68 69 73 20 73 74 61 74 65 6d 65 6e 74 20   this statement 
2b520 69 73 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74  is a [SELECT] st
2b530 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 68 65 20  atement and the 
2b540 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  Nth column of th
2b550 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 72 65  e.** returned re
2b560 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68 61 74  sult set of that
2b570 20 5b 53 45 4c 45 43 54 5d 20 69 73 20 61 20 74   [SELECT] is a t
2b580 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74  able column (not
2b590 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f   an.** expressio
2b5a0 6e 20 6f 72 20 73 75 62 71 75 65 72 79 29 20 74  n or subquery) t
2b5b0 68 65 6e 20 74 68 65 20 64 65 63 6c 61 72 65 64  hen the declared
2b5c0 20 74 79 70 65 20 6f 66 20 74 68 65 20 74 61 62   type of the tab
2b5d0 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 20  le.** column is 
2b5e0 72 65 74 75 72 6e 65 64 2e 29 5e 20 20 5e 49 66  returned.)^  ^If
2b5f0 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
2b600 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  of the result se
2b610 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65  t is an.** expre
2b620 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72  ssion or subquer
2b630 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70  y, then a NULL p
2b640 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e  ointer is return
2b650 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75  ed..** ^The retu
2b660 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 61  rned string is a
2b670 6c 77 61 79 73 20 55 54 46 2d 38 20 65 6e 63 6f  lways UTF-8 enco
2b680 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72  ded..**.** ^(For
2b690 20 65 78 61 6d 70 6c 65 2c 20 67 69 76 65 6e 20   example, given 
2b6a0 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68  the database sch
2b6b0 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54  ema:.**.** CREAT
2b6c0 45 20 54 41 42 4c 45 20 74 31 28 63 31 20 56 41  E TABLE t1(c1 VA
2b6d0 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e  RIANT);.**.** an
2b6e0 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  d the following 
2b6f0 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20  statement to be 
2b700 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20  compiled:.**.** 
2b710 53 45 4c 45 43 54 20 63 31 20 2b 20 31 2c 20 63  SELECT c1 + 1, c
2b720 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a  1 FROM t1;.**.**
2b730 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 6f   this routine wo
2b740 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 73  uld return the s
2b750 74 72 69 6e 67 20 22 56 41 52 49 41 4e 54 22 20  tring "VARIANT" 
2b760 66 6f 72 20 74 68 65 20 73 65 63 6f 6e 64 20 72  for the second r
2b770 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20  esult.** column 
2b780 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55  (i==1), and a NU
2b790 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74  LL pointer for t
2b7a0 68 65 20 66 69 72 73 74 20 72 65 73 75 6c 74 20  he first result 
2b7b0 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e 29 5e  column (i==0).)^
2b7c0 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75  .**.** ^SQLite u
2b7d0 73 65 73 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d  ses dynamic run-
2b7e0 74 69 6d 65 20 74 79 70 69 6e 67 2e 20 20 5e 53  time typing.  ^S
2b7f0 6f 20 6a 75 73 74 20 62 65 63 61 75 73 65 20 61  o just because a
2b800 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64 65   column.** is de
2b810 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e 74 61 69  clared to contai
2b820 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 74  n a particular t
2b830 79 70 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65 61  ype does not mea
2b840 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 64 61  n that the.** da
2b850 74 61 20 73 74 6f 72 65 64 20 69 6e 20 74 68 61  ta stored in tha
2b860 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20 74  t column is of t
2b870 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65  he declared type
2b880 2e 20 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20  .  SQLite is.** 
2b890 73 74 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c 20  strongly typed, 
2b8a0 62 75 74 20 74 68 65 20 74 79 70 69 6e 67 20 69  but the typing i
2b8b0 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73 74  s dynamic not st
2b8c0 61 74 69 63 2e 20 20 5e 54 79 70 65 0a 2a 2a 20  atic.  ^Type.** 
2b8d0 69 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  is associated wi
2b8e0 74 68 20 69 6e 64 69 76 69 64 75 61 6c 20 76 61  th individual va
2b8f0 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74 68 20 74  lues, not with t
2b900 68 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a  he containers.**
2b910 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 74 68   used to hold th
2b920 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a 53  ose values..*/.S
2b930 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
2b940 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
2b950 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73 71  lumn_decltype(sq
2b960 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
2b970 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  ;.SQLITE_API con
2b980 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
2b990 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65  _column_decltype
2b9a0 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
2b9b0 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ,int);../*.** CA
2b9c0 50 49 33 52 45 46 3a 20 45 76 61 6c 75 61 74 65  PI3REF: Evaluate
2b9d0 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e   An SQL Statemen
2b9e0 74 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20  t.**.** After a 
2b9f0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2ba00 65 6e 74 5d 20 68 61 73 20 62 65 65 6e 20 70 72  ent] has been pr
2ba10 65 70 61 72 65 64 20 75 73 69 6e 67 20 65 69 74  epared using eit
2ba20 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  her.** [sqlite3_
2ba30 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
2ba40 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2ba50 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65  e16_v2()] or one
2ba60 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79 0a 2a   of the legacy.*
2ba70 2a 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71  * interfaces [sq
2ba80 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
2ba90 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
2baa0 70 61 72 65 31 36 28 29 5d 2c 20 74 68 69 73 20  pare16()], this 
2bab0 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74  function.** must
2bac0 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f   be called one o
2bad0 72 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20  r more times to 
2bae0 65 76 61 6c 75 61 74 65 20 74 68 65 20 73 74 61  evaluate the sta
2baf0 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68  tement..**.** Th
2bb00 65 20 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65  e details of the
2bb10 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 65   behavior of the
2bb20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
2bb30 69 6e 74 65 72 66 61 63 65 20 64 65 70 65 6e 64  interface depend
2bb40 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 74  .** on whether t
2bb50 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73  he statement was
2bb60 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20   prepared using 
2bb70 74 68 65 20 6e 65 77 65 72 20 22 76 32 22 20 69  the newer "v2" i
2bb80 6e 74 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c  nterface.** [sql
2bb90 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
2bba0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
2bbb0 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20  prepare16_v2()] 
2bbc0 6f 72 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 67  or the older leg
2bbd0 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  acy.** interface
2bbe0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2bbf0 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
2bc00 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2e 20  3_prepare16()]. 
2bc10 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 0a   The use of the.
2bc20 2a 2a 20 6e 65 77 20 22 76 32 22 20 69 6e 74 65  ** new "v2" inte
2bc30 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65  rface is recomme
2bc40 6e 64 65 64 20 66 6f 72 20 6e 65 77 20 61 70 70  nded for new app
2bc50 6c 69 63 61 74 69 6f 6e 73 20 62 75 74 20 74 68  lications but th
2bc60 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65  e legacy.** inte
2bc70 72 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69  rface will conti
2bc80 6e 75 65 20 74 6f 20 62 65 20 73 75 70 70 6f 72  nue to be suppor
2bc90 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74  ted..**.** ^In t
2bca0 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66  he legacy interf
2bcb0 61 63 65 2c 20 74 68 65 20 72 65 74 75 72 6e 20  ace, the return 
2bcc0 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 65 69  value will be ei
2bcd0 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 42 55 53  ther [SQLITE_BUS
2bce0 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44  Y],.** [SQLITE_D
2bcf0 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f  ONE], [SQLITE_RO
2bd00 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  W], [SQLITE_ERRO
2bd10 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d  R], or [SQLITE_M
2bd20 49 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68  ISUSE]..** ^With
2bd30 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
2bd40 61 63 65 2c 20 61 6e 79 20 6f 66 20 74 68 65 20  ace, any of the 
2bd50 6f 74 68 65 72 20 5b 72 65 73 75 6c 74 20 63 6f  other [result co
2bd60 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65  des] or.** [exte
2bd70 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
2bd80 73 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 75  s] might be retu
2bd90 72 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a  rned as well..**
2bda0 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 42 55 53  .** ^[SQLITE_BUS
2bdb0 59 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  Y] means that th
2bdc0 65 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e  e database engin
2bdd0 65 20 77 61 73 20 75 6e 61 62 6c 65 20 74 6f 20  e was unable to 
2bde0 61 63 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 64  acquire the.** d
2bdf0 61 74 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 74  atabase locks it
2be00 20 6e 65 65 64 73 20 74 6f 20 64 6f 20 69 74 73   needs to do its
2be10 20 6a 6f 62 2e 20 20 5e 49 66 20 74 68 65 20 73   job.  ^If the s
2be20 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 43  tatement is a [C
2be30 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63  OMMIT].** or occ
2be40 75 72 73 20 6f 75 74 73 69 64 65 20 6f 66 20 61  urs outside of a
2be50 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73  n explicit trans
2be60 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75  action, then you
2be70 20 63 61 6e 20 72 65 74 72 79 20 74 68 65 0a 2a   can retry the.*
2be80 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66  * statement.  If
2be90 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
2bea0 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d  s not a [COMMIT]
2beb0 20 61 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68   and occurs with
2bec0 69 6e 20 61 6e 0a 2a 2a 20 65 78 70 6c 69 63 69  in an.** explici
2bed0 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 68  t transaction th
2bee0 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f  en you should ro
2bef0 6c 6c 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73  llback the trans
2bf00 61 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a  action before.**
2bf10 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a   continuing..**.
2bf20 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e 45  ** ^[SQLITE_DONE
2bf30 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  ] means that the
2bf40 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20 66   statement has f
2bf50 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 6e  inished executin
2bf60 67 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c  g.** successfull
2bf70 79 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70  y.  sqlite3_step
2bf80 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65  () should not be
2bf90 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e   called again on
2bfa0 20 74 68 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a   this virtual.**
2bfb0 20 6d 61 63 68 69 6e 65 20 77 69 74 68 6f 75 74   machine without
2bfc0 20 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b   first calling [
2bfd0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2bfe0 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 76 69   to reset the vi
2bff0 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65  rtual.** machine
2c000 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69   back to its ini
2c010 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a  tial state..**.*
2c020 2a 20 5e 49 66 20 74 68 65 20 53 51 4c 20 73 74  * ^If the SQL st
2c030 61 74 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78  atement being ex
2c040 65 63 75 74 65 64 20 72 65 74 75 72 6e 73 20 61  ecuted returns a
2c050 6e 79 20 64 61 74 61 2c 20 74 68 65 6e 20 5b 53  ny data, then [S
2c060 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73  QLITE_ROW].** is
2c070 20 72 65 74 75 72 6e 65 64 20 65 61 63 68 20 74   returned each t
2c080 69 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66  ime a new row of
2c090 20 64 61 74 61 20 69 73 20 72 65 61 64 79 20 66   data is ready f
2c0a0 6f 72 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79  or processing by
2c0b0 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20   the.** caller. 
2c0c0 54 68 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62  The values may b
2c0d0 65 20 61 63 63 65 73 73 65 64 20 75 73 69 6e 67  e accessed using
2c0e0 20 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63   the [column acc
2c0f0 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a  ess functions]..
2c100 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  ** sqlite3_step(
2c110 29 20 69 73 20 63 61 6c 6c 65 64 20 61 67 61 69  ) is called agai
2c120 6e 20 74 6f 20 72 65 74 72 69 65 76 65 20 74 68  n to retrieve th
2c130 65 20 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 61  e next row of da
2c140 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49  ta..**.** ^[SQLI
2c150 54 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20  TE_ERROR] means 
2c160 74 68 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 20  that a run-time 
2c170 65 72 72 6f 72 20 28 73 75 63 68 20 61 73 20 61  error (such as a
2c180 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76   constraint.** v
2c190 69 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f 63  iolation) has oc
2c1a0 63 75 72 72 65 64 2e 20 20 73 71 6c 69 74 65 33  curred.  sqlite3
2c1b0 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e  _step() should n
2c1c0 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61  ot be called aga
2c1d0 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e  in on.** the VM.
2c1e0 20 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f   More informatio
2c1f0 6e 20 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 62  n may be found b
2c200 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  y calling [sqlit
2c210 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a  e3_errmsg()]..**
2c220 20 5e 57 69 74 68 20 74 68 65 20 6c 65 67 61 63   ^With the legac
2c230 79 20 69 6e 74 65 72 66 61 63 65 2c 20 61 20 6d  y interface, a m
2c240 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72  ore specific err
2c250 6f 72 20 63 6f 64 65 20 28 66 6f 72 20 65 78 61  or code (for exa
2c260 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  mple,.** [SQLITE
2c270 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 51  _INTERRUPT], [SQ
2c280 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53  LITE_SCHEMA], [S
2c290 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20  QLITE_CORRUPT], 
2c2a0 61 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a  and so forth).**
2c2b0 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64   can be obtained
2c2c0 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c   by calling [sql
2c2d0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e  ite3_reset()] on
2c2e0 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
2c2f0 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e  d statement].  ^
2c300 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65  In the "v2" inte
2c310 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f  rface,.** the mo
2c320 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f  re specific erro
2c330 72 20 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e  r code is return
2c340 65 64 20 64 69 72 65 63 74 6c 79 20 62 79 20 73  ed directly by s
2c350 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a  qlite3_step()..*
2c360 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53  *.** [SQLITE_MIS
2c370 55 53 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20  USE] means that 
2c380 74 68 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65  the this routine
2c390 20 77 61 73 20 63 61 6c 6c 65 64 20 69 6e 61 70   was called inap
2c3a0 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20  propriately..** 
2c3b0 50 65 72 68 61 70 73 20 69 74 20 77 61 73 20 63  Perhaps it was c
2c3c0 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65 70  alled on a [prep
2c3d0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2c3e0 74 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65  that has.** alre
2c3f0 61 64 79 20 62 65 65 6e 20 5b 73 71 6c 69 74 65  ady been [sqlite
2c400 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e  3_finalize | fin
2c410 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e  alized] or on on
2c420 65 20 74 68 61 74 20 68 61 64 0a 2a 2a 20 70 72  e that had.** pr
2c430 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65  eviously returne
2c440 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  d [SQLITE_ERROR]
2c450 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45   or [SQLITE_DONE
2c460 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a  ].  Or it could.
2c470 2a 2a 20 62 65 20 74 68 65 20 63 61 73 65 20 74  ** be the case t
2c480 68 61 74 20 74 68 65 20 73 61 6d 65 20 64 61 74  hat the same dat
2c490 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2c4a0 20 69 73 20 62 65 69 6e 67 20 75 73 65 64 20 62   is being used b
2c4b0 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65  y two or.** more
2c4c0 20 74 68 72 65 61 64 73 20 61 74 20 74 68 65 20   threads at the 
2c4d0 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74  same moment in t
2c4e0 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61  ime..**.** For a
2c4f0 6c 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  ll versions of S
2c500 51 4c 69 74 65 20 75 70 20 74 6f 20 61 6e 64 20  QLite up to and 
2c510 69 6e 63 6c 75 64 69 6e 67 20 33 2e 36 2e 32 33  including 3.6.23
2c520 2e 31 2c 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a  .1, a call to.**
2c530 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2c540 29 5d 20 77 61 73 20 72 65 71 75 69 72 65 64 20  )] was required 
2c550 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 73 74  after sqlite3_st
2c560 65 70 28 29 20 72 65 74 75 72 6e 65 64 20 61 6e  ep() returned an
2c570 79 74 68 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20  ything.** other 
2c580 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57  than [SQLITE_ROW
2c590 5d 20 62 65 66 6f 72 65 20 61 6e 79 20 73 75 62  ] before any sub
2c5a0 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69  sequent invocati
2c5b0 6f 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33  on of.** sqlite3
2c5c0 5f 73 74 65 70 28 29 2e 20 20 46 61 69 6c 75 72  _step().  Failur
2c5d0 65 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 70  e to reset the p
2c5e0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2c5f0 74 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c  t using .** [sql
2c600 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77 6f  ite3_reset()] wo
2c610 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61 6e  uld result in an
2c620 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
2c630 20 72 65 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20   return from.** 
2c640 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20  sqlite3_step(). 
2c650 20 42 75 74 20 61 66 74 65 72 20 76 65 72 73 69   But after versi
2c660 6f 6e 20 33 2e 36 2e 32 33 2e 31 2c 20 73 71 6c  on 3.6.23.1, sql
2c670 69 74 65 33 5f 73 74 65 70 28 29 20 62 65 67 61  ite3_step() bega
2c680 6e 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20 5b 73 71  n.** calling [sq
2c690 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 61  lite3_reset()] a
2c6a0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 20  utomatically in 
2c6b0 74 68 69 73 20 63 69 72 63 75 6d 73 74 61 6e 63  this circumstanc
2c6c0 65 20 72 61 74 68 65 72 0a 2a 2a 20 74 68 61 6e  e rather.** than
2c6d0 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49   returning [SQLI
2c6e0 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 54 68 69  TE_MISUSE].  Thi
2c6f0 73 20 69 73 20 6e 6f 74 20 63 6f 6e 73 69 64 65  s is not conside
2c700 72 65 64 20 61 20 63 6f 6d 70 61 74 69 62 69 6c  red a compatibil
2c710 69 74 79 0a 2a 2a 20 62 72 65 61 6b 20 62 65 63  ity.** break bec
2c720 61 75 73 65 20 61 6e 79 20 61 70 70 6c 69 63 61  ause any applica
2c730 74 69 6f 6e 20 74 68 61 74 20 65 76 65 72 20 72  tion that ever r
2c740 65 63 65 69 76 65 73 20 61 6e 20 53 51 4c 49 54  eceives an SQLIT
2c750 45 5f 4d 49 53 55 53 45 20 65 72 72 6f 72 0a 2a  E_MISUSE error.*
2c760 2a 20 69 73 20 62 72 6f 6b 65 6e 20 62 79 20 64  * is broken by d
2c770 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 65 20  efinition.  The 
2c780 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54  [SQLITE_OMIT_AUT
2c790 4f 52 45 53 45 54 5d 20 63 6f 6d 70 69 6c 65 2d  ORESET] compile-
2c7a0 74 69 6d 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63  time option.** c
2c7b0 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72 65  an be used to re
2c7c0 73 74 6f 72 65 20 74 68 65 20 6c 65 67 61 63 79  store the legacy
2c7d0 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a   behavior..**.**
2c7e0 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66   <b>Goofy Interf
2c7f0 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49  ace Alert:</b> I
2c800 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74  n the legacy int
2c810 65 72 66 61 63 65 2c 20 74 68 65 20 73 71 6c 69  erface, the sqli
2c820 74 65 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50  te3_step().** AP
2c830 49 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73  I always returns
2c840 20 61 20 67 65 6e 65 72 69 63 20 65 72 72 6f 72   a generic error
2c850 20 63 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45   code, [SQLITE_E
2c860 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67  RROR], following
2c870 20 61 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74   any.** error ot
2c880 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
2c890 5f 42 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49  _BUSY] and [SQLI
2c8a0 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75  TE_MISUSE].  You
2c8b0 20 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73   must call.** [s
2c8c0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
2c8d0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  or [sqlite3_fina
2c8e0 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65 72  lize()] in order
2c8f0 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20   to find one of 
2c900 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20  the.** specific 
2c910 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 74 68  [error codes] th
2c920 61 74 20 62 65 74 74 65 72 20 64 65 73 63 72 69  at better descri
2c930 62 65 73 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a  bes the error..*
2c940 2a 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 20  * We admit that 
2c950 74 68 69 73 20 69 73 20 61 20 67 6f 6f 66 79 20  this is a goofy 
2c960 64 65 73 69 67 6e 2e 20 20 54 68 65 20 70 72 6f  design.  The pro
2c970 62 6c 65 6d 20 68 61 73 20 62 65 65 6e 20 66 69  blem has been fi
2c980 78 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  xed.** with the 
2c990 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2e 20  "v2" interface. 
2c9a0 20 49 66 20 79 6f 75 20 70 72 65 70 61 72 65 20   If you prepare 
2c9b0 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c 20  all of your SQL 
2c9c0 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73  statements.** us
2c9d0 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69  ing either [sqli
2c9e0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
2c9f0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ] or [sqlite3_pr
2ca00 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 69 6e  epare16_v2()] in
2ca10 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20  stead.** of the 
2ca20 6c 65 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f  legacy [sqlite3_
2ca30 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b  prepare()] and [
2ca40 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2ca50 36 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 2c  6()] interfaces,
2ca60 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f 72  .** then the mor
2ca70 65 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f  e specific [erro
2ca80 72 20 63 6f 64 65 73 5d 20 61 72 65 20 72 65 74  r codes] are ret
2ca90 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 0a 2a  urned directly.*
2caa0 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65  * by sqlite3_ste
2cab0 70 28 29 2e 20 20 54 68 65 20 75 73 65 20 6f 66  p().  The use of
2cac0 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
2cad0 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64  ace is recommend
2cae0 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  ed..*/.SQLITE_AP
2caf0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74  I int sqlite3_st
2cb00 65 70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ep(sqlite3_stmt*
2cb10 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2cb20 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20 63 6f  EF: Number of co
2cb30 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65 73 75 6c  lumns in a resul
2cb40 74 20 73 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  t set.**.** ^The
2cb50 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
2cb60 75 6e 74 28 50 29 20 69 6e 74 65 72 66 61 63 65  unt(P) interface
2cb70 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
2cb80 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
2cb90 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74  n the.** current
2cba0 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75   row of the resu
2cbb0 6c 74 20 73 65 74 20 6f 66 20 5b 70 72 65 70 61  lt set of [prepa
2cbc0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50  red statement] P
2cbd0 2e 0a 2a 2a 20 5e 49 66 20 70 72 65 70 61 72 65  ..** ^If prepare
2cbe0 64 20 73 74 61 74 65 6d 65 6e 74 20 50 20 64 6f  d statement P do
2cbf0 65 73 20 6e 6f 74 20 68 61 76 65 20 72 65 73 75  es not have resu
2cc00 6c 74 73 20 72 65 61 64 79 20 74 6f 20 72 65 74  lts ready to ret
2cc10 75 72 6e 0a 2a 2a 20 28 76 69 61 20 63 61 6c 6c  urn.** (via call
2cc20 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  s to the [sqlite
2cc30 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20 73  3_column_int | s
2cc40 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 28  qlite3_column_*(
2cc50 29 5d 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61  )] of.** interfa
2cc60 63 65 73 29 20 74 68 65 6e 20 73 71 6c 69 74 65  ces) then sqlite
2cc70 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20  3_data_count(P) 
2cc80 72 65 74 75 72 6e 73 20 30 2e 0a 2a 2a 20 5e 54  returns 0..** ^T
2cc90 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  he sqlite3_data_
2cca0 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65  count(P) routine
2ccb0 20 61 6c 73 6f 20 72 65 74 75 72 6e 73 20 30 20   also returns 0 
2ccc0 69 66 20 50 20 69 73 20 61 20 4e 55 4c 4c 20 70  if P is a NULL p
2ccd0 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 53 65  ointer..**.** Se
2cce0 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
2ccf0 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d  _column_count()]
2cd00 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
2cd10 6e 74 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  nt sqlite3_data_
2cd20 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  count(sqlite3_st
2cd30 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
2cd40 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e  ** CAPI3REF: Fun
2cd50 64 61 6d 65 6e 74 61 6c 20 44 61 74 61 74 79 70  damental Datatyp
2cd60 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  es.** KEYWORDS: 
2cd70 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a  SQLITE_TEXT.**.*
2cd80 2a 20 5e 28 45 76 65 72 79 20 76 61 6c 75 65 20  * ^(Every value 
2cd90 69 6e 20 53 51 4c 69 74 65 20 68 61 73 20 6f 6e  in SQLite has on
2cda0 65 20 6f 66 20 66 69 76 65 20 66 75 6e 64 61 6d  e of five fundam
2cdb0 65 6e 74 61 6c 20 64 61 74 61 74 79 70 65 73 3a  ental datatypes:
2cdc0 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
2cdd0 6c 69 3e 20 36 34 2d 62 69 74 20 73 69 67 6e 65  li> 64-bit signe
2cde0 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69  d integer.** <li
2cdf0 3e 20 36 34 2d 62 69 74 20 49 45 45 45 20 66 6c  > 64-bit IEEE fl
2ce00 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d  oating point num
2ce10 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69  ber.** <li> stri
2ce20 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a  ng.** <li> BLOB.
2ce30 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20  ** <li> NULL.** 
2ce40 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  </ul>)^.**.** Th
2ce50 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72  ese constants ar
2ce60 65 20 63 6f 64 65 73 20 66 6f 72 20 65 61 63 68  e codes for each
2ce70 20 6f 66 20 74 68 6f 73 65 20 74 79 70 65 73 2e   of those types.
2ce80 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  .**.** Note that
2ce90 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45 58 54   the SQLITE_TEXT
2cea0 20 63 6f 6e 73 74 61 6e 74 20 77 61 73 20 61 6c   constant was al
2ceb0 73 6f 20 75 73 65 64 20 69 6e 20 53 51 4c 69 74  so used in SQLit
2cec0 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66  e version 2.** f
2ced0 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20  or a completely 
2cee0 64 69 66 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e  different meanin
2cef0 67 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68 61  g.  Software tha
2cf00 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20  t links against 
2cf10 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76  both.** SQLite v
2cf20 65 72 73 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c  ersion 2 and SQL
2cf30 69 74 65 20 76 65 72 73 69 6f 6e 20 33 20 73 68  ite version 3 sh
2cf40 6f 75 6c 64 20 75 73 65 20 53 51 4c 49 54 45 33  ould use SQLITE3
2cf50 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51  _TEXT, not.** SQ
2cf60 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64  LITE_TEXT..*/.#d
2cf70 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54  efine SQLITE_INT
2cf80 45 47 45 52 20 20 31 0a 23 64 65 66 69 6e 65 20  EGER  1.#define 
2cf90 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20 20  SQLITE_FLOAT    
2cfa0 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
2cfb0 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23 64 65 66  _BLOB     4.#def
2cfc0 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20  ine SQLITE_NULL 
2cfd0 20 20 20 20 35 0a 23 69 66 64 65 66 20 53 51 4c      5.#ifdef SQL
2cfe0 49 54 45 5f 54 45 58 54 0a 23 20 75 6e 64 65 66  ITE_TEXT.# undef
2cff0 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c   SQLITE_TEXT.#el
2d000 73 65 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49  se.# define SQLI
2d010 54 45 5f 54 45 58 54 20 20 20 20 20 33 0a 23 65  TE_TEXT     3.#e
2d020 6e 64 69 66 0a 23 64 65 66 69 6e 65 20 53 51 4c  ndif.#define SQL
2d030 49 54 45 33 5f 54 45 58 54 20 20 20 20 20 33 0a  ITE3_TEXT     3.
2d040 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2d050 20 52 65 73 75 6c 74 20 56 61 6c 75 65 73 20 46   Result Values F
2d060 72 6f 6d 20 41 20 51 75 65 72 79 0a 2a 2a 20 4b  rom A Query.** K
2d070 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e  EYWORDS: {column
2d080 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e   access function
2d090 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  s}.**.** These r
2d0a0 6f 75 74 69 6e 65 73 20 66 6f 72 6d 20 74 68 65  outines form the
2d0b0 20 22 72 65 73 75 6c 74 20 73 65 74 22 20 69 6e   "result set" in
2d0c0 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e  terface..**.** ^
2d0d0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
2d0e0 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f  eturn informatio
2d0f0 6e 20 61 62 6f 75 74 20 61 20 73 69 6e 67 6c 65  n about a single
2d100 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 63   column of the c
2d110 75 72 72 65 6e 74 0a 2a 2a 20 72 65 73 75 6c 74  urrent.** result
2d120 20 72 6f 77 20 6f 66 20 61 20 71 75 65 72 79 2e   row of a query.
2d130 20 20 5e 49 6e 20 65 76 65 72 79 20 63 61 73 65    ^In every case
2d140 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
2d150 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ent is a pointer
2d160 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 70 72 65 70  .** to the [prep
2d170 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2d180 74 68 61 74 20 69 73 20 62 65 69 6e 67 20 65 76  that is being ev
2d190 61 6c 75 61 74 65 64 20 28 74 68 65 20 5b 73 71  aluated (the [sq
2d1a0 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20  lite3_stmt*].** 
2d1b0 74 68 61 74 20 77 61 73 20 72 65 74 75 72 6e 65  that was returne
2d1c0 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
2d1d0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
2d1e0 20 6f 6e 65 20 6f 66 20 69 74 73 20 76 61 72 69   one of its vari
2d1f0 61 6e 74 73 29 0a 2a 2a 20 61 6e 64 20 74 68 65  ants).** and the
2d200 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
2d210 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66   is the index of
2d220 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20   the column for 
2d230 77 68 69 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f  which informatio
2d240 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72  n.** should be r
2d250 65 74 75 72 6e 65 64 2e 20 5e 54 68 65 20 6c 65  eturned. ^The le
2d260 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66  ftmost column of
2d270 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
2d280 68 61 73 20 74 68 65 20 69 6e 64 65 78 20 30 2e  has the index 0.
2d290 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d 62 65 72 20  .** ^The number 
2d2a0 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68  of columns in th
2d2b0 65 20 72 65 73 75 6c 74 20 63 61 6e 20 62 65 20  e result can be 
2d2c0 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67  determined using
2d2d0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
2d2e0 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a  umn_count()]..**
2d2f0 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73  .** If the SQL s
2d300 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f  tatement does no
2d310 74 20 63 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e  t currently poin
2d320 74 20 74 6f 20 61 20 76 61 6c 69 64 20 72 6f 77  t to a valid row
2d330 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20 63  , or if the.** c
2d340 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f  olumn index is o
2d350 75 74 20 6f 66 20 72 61 6e 67 65 2c 20 74 68 65  ut of range, the
2d360 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66   result is undef
2d370 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 73 65 20 72  ined..** These r
2d380 6f 75 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79  outines may only
2d390 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20   be called when 
2d3a0 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
2d3b0 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  call to.** [sqli
2d3c0 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20  te3_step()] has 
2d3d0 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45  returned [SQLITE
2d3e0 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68 65  _ROW] and neithe
2d3f0 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  r.** [sqlite3_re
2d400 73 65 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69  set()] nor [sqli
2d410 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
2d420 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64  have been called
2d430 20 73 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a   subsequently..*
2d440 2a 20 49 66 20 61 6e 79 20 6f 66 20 74 68 65 73  * If any of thes
2d450 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63  e routines are c
2d460 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c  alled after [sql
2d470 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
2d480 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  .** [sqlite3_fin
2d490 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65  alize()] or afte
2d4a0 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  r [sqlite3_step(
2d4b0 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 0a  )] has returned.
2d4c0 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68  ** something oth
2d4d0 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
2d4e0 52 4f 57 5d 2c 20 74 68 65 20 72 65 73 75 6c 74  ROW], the result
2d4f0 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
2d500 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65 33 5f  .** If [sqlite3_
2d510 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69  step()] or [sqli
2d520 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20  te3_reset()] or 
2d530 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
2d540 65 28 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c  e()].** are call
2d550 65 64 20 66 72 6f 6d 20 61 20 64 69 66 66 65 72  ed from a differ
2d560 65 6e 74 20 74 68 72 65 61 64 20 77 68 69 6c 65  ent thread while
2d570 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f   any of these ro
2d580 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65  utines.** are pe
2d590 6e 64 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20  nding, then the 
2d5a0 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
2d5b0 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  fined..**.** ^Th
2d5c0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
2d5d0 5f 74 79 70 65 28 29 20 72 6f 75 74 69 6e 65 20  _type() routine 
2d5e0 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 5b  returns the.** [
2d5f0 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c  SQLITE_INTEGER |
2d600 20 64 61 74 61 74 79 70 65 20 63 6f 64 65 5d 20   datatype code] 
2d610 66 6f 72 20 74 68 65 20 69 6e 69 74 69 61 6c 20  for the initial 
2d620 64 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20  data type.** of 
2d630 74 68 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  the result colum
2d640 6e 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65  n.  ^The returne
2d650 64 20 76 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f  d value is one o
2d660 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45  f [SQLITE_INTEGE
2d670 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46  R],.** [SQLITE_F
2d680 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54  LOAT], [SQLITE_T
2d690 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c  EXT], [SQLITE_BL
2d6a0 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  OB], or [SQLITE_
2d6b0 4e 55 4c 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75  NULL].  The valu
2d6c0 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79  e.** returned by
2d6d0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2d6e0 74 79 70 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d  type() is only m
2d6f0 65 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20  eaningful if no 
2d700 74 79 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69  type.** conversi
2d710 6f 6e 73 20 68 61 76 65 20 6f 63 63 75 72 72 65  ons have occurre
2d720 64 20 61 73 20 64 65 73 63 72 69 62 65 64 20 62  d as described b
2d730 65 6c 6f 77 2e 20 20 41 66 74 65 72 20 61 20 74  elow.  After a t
2d740 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a  ype conversion,.
2d750 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  ** the value ret
2d760 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
2d770 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69  _column_type() i
2d780 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 46 75  s undefined.  Fu
2d790 74 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73  ture.** versions
2d7a0 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 63   of SQLite may c
2d7b0 68 61 6e 67 65 20 74 68 65 20 62 65 68 61 76 69  hange the behavi
2d7c0 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f  or of sqlite3_co
2d7d0 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66  lumn_type().** f
2d7e0 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70 65 20  ollowing a type 
2d7f0 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a  conversion..**.*
2d800 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
2d810 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54   is a BLOB or UT
2d820 46 2d 38 20 73 74 72 69 6e 67 20 74 68 65 6e 20  F-8 string then 
2d830 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  the sqlite3_colu
2d840 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 72 6f  mn_bytes().** ro
2d850 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
2d860 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
2d870 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f  s in that BLOB o
2d880 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66  r string..** ^If
2d890 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
2d8a0 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2c 20   UTF-16 string, 
2d8b0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
2d8c0 75 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e 76  umn_bytes() conv
2d8d0 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69  erts.** the stri
2d8e0 6e 67 20 74 6f 20 55 54 46 2d 38 20 61 6e 64 20  ng to UTF-8 and 
2d8f0 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65  then returns the
2d900 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
2d910 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  ..** ^If the res
2d920 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63  ult is a numeric
2d930 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69   value then sqli
2d940 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2d950 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69  () uses.** [sqli
2d960 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20  te3_snprintf()] 
2d970 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20  to convert that 
2d980 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 38  value to a UTF-8
2d990 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75   string and retu
2d9a0 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65  rns.** the numbe
2d9b0 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
2d9c0 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49  at string..** ^I
2d9d0 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
2d9e0 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74  NULL, then sqlit
2d9f0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
2da00 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a  ) returns zero..
2da10 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  **.** ^If the re
2da20 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f  sult is a BLOB o
2da30 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20  r UTF-16 string 
2da40 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33  then the sqlite3
2da50 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
2da60 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74  ).** routine ret
2da70 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
2da80 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74  of bytes in that
2da90 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e   BLOB or string.
2daa0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
2dab0 6c 74 20 69 73 20 61 20 55 54 46 2d 38 20 73 74  lt is a UTF-8 st
2dac0 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74  ring, then sqlit
2dad0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
2dae0 36 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20  6() converts.** 
2daf0 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54  the string to UT
2db00 46 2d 31 36 20 61 6e 64 20 74 68 65 6e 20 72 65  F-16 and then re
2db10 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
2db20 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49   of bytes..** ^I
2db30 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
2db40 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20  a numeric value 
2db50 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
2db60 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 75 73  umn_bytes16() us
2db70 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  es.** [sqlite3_s
2db80 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f  nprintf()] to co
2db90 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c 75 65  nvert that value
2dba0 20 74 6f 20 61 20 55 54 46 2d 31 36 20 73 74 72   to a UTF-16 str
2dbb0 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a  ing and returns.
2dbc0 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
2dbd0 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 73   bytes in that s
2dbe0 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68  tring..** ^If th
2dbf0 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c  e result is NULL
2dc00 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  , then sqlite3_c
2dc10 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20  olumn_bytes16() 
2dc20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a  returns zero..**
2dc30 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65 73 20  .** ^The values 
2dc40 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
2dc50 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2dc60 73 28 29 5d 20 61 6e 64 20 0a 2a 2a 20 5b 73 71  s()] and .** [sq
2dc70 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2dc80 65 73 31 36 28 29 5d 20 64 6f 20 6e 6f 74 20 69  es16()] do not i
2dc90 6e 63 6c 75 64 65 20 74 68 65 20 7a 65 72 6f 20  nclude the zero 
2dca0 74 65 72 6d 69 6e 61 74 6f 72 73 20 61 74 20 74  terminators at t
2dcb0 68 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65  he end.** of the
2dcc0 20 73 74 72 69 6e 67 2e 20 20 5e 46 6f 72 20 63   string.  ^For c
2dcd0 6c 61 72 69 74 79 3a 20 74 68 65 20 76 61 6c 75  larity: the valu
2dce0 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  es returned by.*
2dcf0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
2dd00 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 20 5b  n_bytes()] and [
2dd10 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2dd20 79 74 65 73 31 36 28 29 5d 20 61 72 65 20 74 68  ytes16()] are th
2dd30 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62  e number of.** b
2dd40 79 74 65 73 20 69 6e 20 74 68 65 20 73 74 72 69  ytes in the stri
2dd50 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62  ng, not the numb
2dd60 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73  er of characters
2dd70 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67 73  ..**.** ^Strings
2dd80 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
2dd90 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2dda0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  () and sqlite3_c
2ddb0 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a  olumn_text16(),.
2ddc0 2a 2a 20 65 76 65 6e 20 65 6d 70 74 79 20 73 74  ** even empty st
2ddd0 72 69 6e 67 73 2c 20 61 72 65 20 61 6c 77 61 79  rings, are alway
2dde0 73 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 65  s zero terminate
2ddf0 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 0a  d.  ^The return.
2de00 2a 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71  ** value from sq
2de10 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
2de20 62 28 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c  b() for a zero-l
2de30 65 6e 67 74 68 20 42 4c 4f 42 20 69 73 20 61 20  ength BLOB is a 
2de40 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
2de50 0a 2a 2a 20 5e 54 68 65 20 6f 62 6a 65 63 74 20  .** ^The object 
2de60 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
2de70 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
2de80 65 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75  e()] is an.** [u
2de90 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
2dea0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
2deb0 2e 20 20 41 6e 20 75 6e 70 72 6f 74 65 63 74 65  .  An unprotecte
2dec0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  d sqlite3_value 
2ded0 6f 62 6a 65 63 74 0a 2a 2a 20 6d 61 79 20 6f 6e  object.** may on
2dee0 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 68 20  ly be used with 
2def0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61  [sqlite3_bind_va
2df00 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  lue()] and [sqli
2df10 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
2df20 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b  ()]..** If the [
2df30 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
2df40 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
2df50 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  t returned by.**
2df60 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2df70 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 73 65  _value()] is use
2df80 64 20 69 6e 20 61 6e 79 20 6f 74 68 65 72 20 77  d in any other w
2df90 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63 61  ay, including ca
2dfa0 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e  lls.** to routin
2dfb0 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33  es like [sqlite3
2dfc0 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b  _value_int()], [
2dfd0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
2dfe0 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71  xt()],.** or [sq
2dff0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
2e000 73 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 62  s()], then the b
2e010 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66  ehavior is undef
2e020 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ined..**.** Thes
2e030 65 20 72 6f 75 74 69 6e 65 73 20 61 74 74 65 6d  e routines attem
2e040 70 74 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68  pt to convert th
2e050 65 20 76 61 6c 75 65 20 77 68 65 72 65 20 61 70  e value where ap
2e060 70 72 6f 70 72 69 61 74 65 2e 20 20 5e 46 6f 72  propriate.  ^For
2e070 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66 20  .** example, if 
2e080 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70  the internal rep
2e090 72 65 73 65 6e 74 61 74 69 6f 6e 20 69 73 20 46  resentation is F
2e0a0 4c 4f 41 54 20 61 6e 64 20 61 20 74 65 78 74 20  LOAT and a text 
2e0b0 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71  result.** is req
2e0c0 75 65 73 74 65 64 2c 20 5b 73 71 6c 69 74 65 33  uested, [sqlite3
2e0d0 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 73 20  _snprintf()] is 
2e0e0 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20  used internally 
2e0f0 74 6f 20 70 65 72 66 6f 72 6d 20 74 68 65 0a 2a  to perform the.*
2e100 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75 74  * conversion aut
2e110 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 5e 28 54  omatically.  ^(T
2e120 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62  he following tab
2e130 6c 65 20 64 65 74 61 69 6c 73 20 74 68 65 20 63  le details the c
2e140 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 68  onversions.** th
2e150 61 74 20 61 72 65 20 61 70 70 6c 69 65 64 3a 0a  at are applied:.
2e160 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
2e170 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72  e>.** <table bor
2e180 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e  der="1">.** <tr>
2e190 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72  <th> Internal<br
2e1a0 3e 54 79 70 65 20 3c 74 68 3e 20 52 65 71 75 65  >Type <th> Reque
2e1b0 73 74 65 64 3c 62 72 3e 54 79 70 65 20 3c 74 68  sted<br>Type <th
2e1c0 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a  >  Conversion.**
2e1d0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55  .** <tr><td>  NU
2e1e0 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47  LL    <td> INTEG
2e1f0 45 52 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74  ER   <td> Result
2e200 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64   is 0.** <tr><td
2e210 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20  >  NULL    <td> 
2e220 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 52   FLOAT    <td> R
2e230 65 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20  esult is 0.0.** 
2e240 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20  <tr><td>  NULL  
2e250 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20    <td>   TEXT   
2e260 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20   <td> Result is 
2e270 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  NULL pointer.** 
2e280 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20  <tr><td>  NULL  
2e290 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20    <td>   BLOB   
2e2a0 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20   <td> Result is 
2e2b0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  NULL pointer.** 
2e2c0 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52  <tr><td> INTEGER
2e2d0 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20    <td>  FLOAT   
2e2e0 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72   <td> Convert fr
2e2f0 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f 20 66 6c  om integer to fl
2e300 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  oat.** <tr><td> 
2e310 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20  INTEGER  <td>   
2e320 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43  TEXT    <td> ASC
2e330 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20  II rendering of 
2e340 74 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c  the integer.** <
2e350 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20  tr><td> INTEGER 
2e360 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20   <td>   BLOB    
2e370 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 49 4e 54  <td> Same as INT
2e380 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74  EGER->TEXT.** <t
2e390 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20  r><td>  FLOAT   
2e3a0 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c  <td> INTEGER   <
2e3b0 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d  td> Convert from
2e3c0 20 66 6c 6f 61 74 20 74 6f 20 69 6e 74 65 67 65   float to intege
2e3d0 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46  r.** <tr><td>  F
2e3e0 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 54 45  LOAT   <td>   TE
2e3f0 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49  XT    <td> ASCII
2e400 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68   rendering of th
2e410 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c  e float.** <tr><
2e420 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64  td>  FLOAT   <td
2e430 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  >   BLOB    <td>
2e440 20 53 61 6d 65 20 61 73 20 46 4c 4f 41 54 2d 3e   Same as FLOAT->
2e450 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  TEXT.** <tr><td>
2e460 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 49    TEXT    <td> I
2e470 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 55 73  NTEGER   <td> Us
2e480 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e  e atoi().** <tr>
2e490 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74  <td>  TEXT    <t
2e4a0 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64  d>  FLOAT    <td
2e4b0 3e 20 55 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20  > Use atof().** 
2e4c0 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20  <tr><td>  TEXT  
2e4d0 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20    <td>   BLOB   
2e4e0 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a   <td> No change.
2e4f0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f  ** <tr><td>  BLO
2e500 42 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45  B    <td> INTEGE
2e510 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74  R   <td> Convert
2e520 20 74 6f 20 54 45 58 54 20 74 68 65 6e 20 75 73   to TEXT then us
2e530 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e  e atoi().** <tr>
2e540 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74  <td>  BLOB    <t
2e550 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64  d>  FLOAT    <td
2e560 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45 58  > Convert to TEX
2e570 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f 66 28  T then use atof(
2e580 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42  ).** <tr><td>  B
2e590 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 20 54 45  LOB    <td>   TE
2e5a0 58 54 20 20 20 20 3c 74 64 3e 20 41 64 64 20 61  XT    <td> Add a
2e5b0 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
2e5c0 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f   if needed.** </
2e5d0 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63  table>.** </bloc
2e5e0 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20  kquote>)^.**.** 
2e5f0 54 68 65 20 74 61 62 6c 65 20 61 62 6f 76 65 20  The table above 
2e600 6d 61 6b 65 73 20 72 65 66 65 72 65 6e 63 65 20  makes reference 
2e610 74 6f 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  to standard C li
2e620 62 72 61 72 79 20 66 75 6e 63 74 69 6f 6e 73 20  brary functions 
2e630 61 74 6f 69 28 29 0a 2a 2a 20 61 6e 64 20 61 74  atoi().** and at
2e640 6f 66 28 29 2e 20 20 53 51 4c 69 74 65 20 64 6f  of().  SQLite do
2e650 65 73 20 6e 6f 74 20 72 65 61 6c 6c 79 20 75 73  es not really us
2e660 65 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  e these function
2e670 73 2e 20 20 49 74 20 68 61 73 20 69 74 73 0a 2a  s.  It has its.*
2e680 2a 20 6f 77 6e 20 65 71 75 69 76 61 6c 65 6e 74  * own equivalent
2e690 20 69 6e 74 65 72 6e 61 6c 20 72 6f 75 74 69 6e   internal routin
2e6a0 65 73 2e 20 20 54 68 65 20 61 74 6f 69 28 29 20  es.  The atoi() 
2e6b0 61 6e 64 20 61 74 6f 66 28 29 20 6e 61 6d 65 73  and atof() names
2e6c0 20 61 72 65 0a 2a 2a 20 75 73 65 64 20 69 6e 20   are.** used in 
2e6d0 74 68 65 20 74 61 62 6c 65 20 66 6f 72 20 62 72  the table for br
2e6e0 65 76 69 74 79 20 61 6e 64 20 62 65 63 61 75 73  evity and becaus
2e6f0 65 20 74 68 65 79 20 61 72 65 20 66 61 6d 69 6c  e they are famil
2e700 69 61 72 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43  iar to most.** C
2e710 20 70 72 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a   programmers..**
2e720 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 77 68  .** Note that wh
2e730 65 6e 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69  en type conversi
2e740 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74  ons occur, point
2e750 65 72 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ers returned by 
2e760 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74  prior.** calls t
2e770 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  o sqlite3_column
2e780 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33  _blob(), sqlite3
2e790 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20  _column_text(), 
2e7a0 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  and/or.** sqlite
2e7b0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
2e7c0 29 20 6d 61 79 20 62 65 20 69 6e 76 61 6c 69 64  ) may be invalid
2e7d0 61 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f  ated..** Type co
2e7e0 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f  nversions and po
2e7f0 69 6e 74 65 72 20 69 6e 76 61 6c 69 64 61 74 69  inter invalidati
2e800 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a  ons might occur.
2e810 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77  ** in the follow
2e820 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a  ing cases:.**.**
2e830 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68   <ul>.** <li> Th
2e840 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e  e initial conten
2e850 74 20 69 73 20 61 20 42 4c 4f 42 20 61 6e 64 20  t is a BLOB and 
2e860 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2e870 65 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20  ext() or.**     
2e880 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2e890 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c  text16() is call
2e8a0 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d  ed.  A zero-term
2e8b0 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20  inator might.** 
2e8c0 20 20 20 20 20 6e 65 65 64 20 74 6f 20 62 65 20       need to be 
2e8d0 61 64 64 65 64 20 74 6f 20 74 68 65 20 73 74 72  added to the str
2e8e0 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69  ing.</li>.** <li
2e8f0 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f  > The initial co
2e900 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 38 20 74  ntent is UTF-8 t
2e910 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  ext and sqlite3_
2e920 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
2e930 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69   or.**      sqli
2e940 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
2e950 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20  6() is called.  
2e960 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74  The content must
2e970 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a   be converted.**
2e980 20 20 20 20 20 20 74 6f 20 55 54 46 2d 31 36 2e        to UTF-16.
2e990 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68  </li>.** <li> Th
2e9a0 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e  e initial conten
2e9b0 74 20 69 73 20 55 54 46 2d 31 36 20 74 65 78 74  t is UTF-16 text
2e9c0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
2e9d0 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a  umn_bytes() or.*
2e9e0 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63  *      sqlite3_c
2e9f0 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69 73 20  olumn_text() is 
2ea00 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e  called.  The con
2ea10 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e  tent must be con
2ea20 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74  verted.**      t
2ea30 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a  o UTF-8.</li>.**
2ea40 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f   </ul>.**.** ^Co
2ea50 6e 76 65 72 73 69 6f 6e 73 20 62 65 74 77 65 65  nversions betwee
2ea60 6e 20 55 54 46 2d 31 36 62 65 20 61 6e 64 20 55  n UTF-16be and U
2ea70 54 46 2d 31 36 6c 65 20 61 72 65 20 61 6c 77 61  TF-16le are alwa
2ea80 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65  ys done in place
2ea90 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69   and do.** not i
2eaa0 6e 76 61 6c 69 64 61 74 65 20 61 20 70 72 69 6f  nvalidate a prio
2eab0 72 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67  r pointer, thoug
2eac0 68 20 6f 66 20 63 6f 75 72 73 65 20 74 68 65 20  h of course the 
2ead0 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 62  content of the b
2eae0 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 74 68  uffer.** that th
2eaf0 65 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 20  e prior pointer 
2eb00 72 65 66 65 72 65 6e 63 65 73 20 77 69 6c 6c 20  references will 
2eb10 68 61 76 65 20 62 65 65 6e 20 6d 6f 64 69 66 69  have been modifi
2eb20 65 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64 73  ed.  Other kinds
2eb30 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f  .** of conversio
2eb40 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c  n are done in pl
2eb50 61 63 65 20 77 68 65 6e 20 69 74 20 69 73 20 70  ace when it is p
2eb60 6f 73 73 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d  ossible, but som
2eb70 65 74 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61  etimes they.** a
2eb80 72 65 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20  re not possible 
2eb90 61 6e 64 20 69 6e 20 74 68 6f 73 65 20 63 61 73  and in those cas
2eba0 65 73 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72  es prior pointer
2ebb0 73 20 61 72 65 20 69 6e 76 61 6c 69 64 61 74 65  s are invalidate
2ebc0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66  d..**.** The saf
2ebd0 65 73 74 20 61 6e 64 20 65 61 73 69 65 73 74 20  est and easiest 
2ebe0 74 6f 20 72 65 6d 65 6d 62 65 72 20 70 6f 6c 69  to remember poli
2ebf0 63 79 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20  cy is to invoke 
2ec00 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a  these routines.*
2ec10 2a 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20  * in one of the 
2ec20 66 6f 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a  following ways:.
2ec30 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c  **.** <ul>.**  <
2ec40 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  li>sqlite3_colum
2ec50 6e 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65  n_text() followe
2ec60 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
2ec70 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e  umn_bytes()</li>
2ec80 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33  .**  <li>sqlite3
2ec90 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66  _column_blob() f
2eca0 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74  ollowed by sqlit
2ecb0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
2ecc0 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73  )</li>.**  <li>s
2ecd0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2ece0 78 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20  xt16() followed 
2ecf0 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
2ed00 6e 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e  n_bytes16()</li>
2ed10 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
2ed20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
2ed30 79 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20  you should call 
2ed40 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2ed50 65 78 74 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65  ext(),.** sqlite
2ed60 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c  3_column_blob(),
2ed70 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   or sqlite3_colu
2ed80 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 69 72 73  mn_text16() firs
2ed90 74 20 74 6f 20 66 6f 72 63 65 20 74 68 65 20 72  t to force the r
2eda0 65 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68  esult.** into th
2edb0 65 20 64 65 73 69 72 65 64 20 66 6f 72 6d 61 74  e desired format
2edc0 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71  , then invoke sq
2edd0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2ede0 65 73 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74  es() or.** sqlit
2edf0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
2ee00 36 28 29 20 74 6f 20 66 69 6e 64 20 74 68 65 20  6() to find the 
2ee10 73 69 7a 65 20 6f 66 20 74 68 65 20 72 65 73 75  size of the resu
2ee20 6c 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20  lt.  Do not mix 
2ee30 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69  calls.** to sqli
2ee40 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
2ee50 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ) or sqlite3_col
2ee60 75 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68 20  umn_blob() with 
2ee70 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69  calls to.** sqli
2ee80 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2ee90 31 36 28 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74  16(), and do not
2eea0 20 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20 73 71   mix calls to sq
2eeb0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2eec0 74 31 36 28 29 0a 2a 2a 20 77 69 74 68 20 63 61  t16().** with ca
2eed0 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  lls to sqlite3_c
2eee0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a  olumn_bytes()..*
2eef0 2a 0a 2a 2a 20 5e 54 68 65 20 70 6f 69 6e 74 65  *.** ^The pointe
2ef00 72 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20  rs returned are 
2ef10 76 61 6c 69 64 20 75 6e 74 69 6c 20 61 20 74 79  valid until a ty
2ef20 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63  pe conversion oc
2ef30 63 75 72 73 20 61 73 0a 2a 2a 20 64 65 73 63 72  curs as.** descr
2ef40 69 62 65 64 20 61 62 6f 76 65 2c 20 6f 72 20 75  ibed above, or u
2ef50 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74  ntil [sqlite3_st
2ef60 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  ep()] or [sqlite
2ef70 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a  3_reset()] or.**
2ef80 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
2ef90 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e  ze()] is called.
2efa0 20 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 73 70    ^The memory sp
2efb0 61 63 65 20 75 73 65 64 20 74 6f 20 68 6f 6c 64  ace used to hold
2efc0 20 73 74 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20   strings.** and 
2efd0 42 4c 4f 42 73 20 69 73 20 66 72 65 65 64 20 61  BLOBs is freed a
2efe0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44  utomatically.  D
2eff0 6f 20 3c 62 3e 6e 6f 74 3c 2f 62 3e 20 70 61 73  o <b>not</b> pas
2f000 73 20 74 68 65 20 70 6f 69 6e 74 65 72 73 20 72  s the pointers r
2f010 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 73 71 6c 69  eturned.** [sqli
2f020 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
2f030 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  )], [sqlite3_col
2f040 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 65 74 63  umn_text()], etc
2f050 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  . into.** [sqlit
2f060 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a  e3_free()]..**.*
2f070 2a 20 5e 28 49 66 20 61 20 6d 65 6d 6f 72 79 20  * ^(If a memory 
2f080 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72  allocation error
2f090 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20 74   occurs during t
2f0a0 68 65 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66  he evaluation of
2f0b0 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 73 65   any.** of these
2f0c0 20 72 6f 75 74 69 6e 65 73 2c 20 61 20 64 65 66   routines, a def
2f0d0 61 75 6c 74 20 76 61 6c 75 65 20 69 73 20 72 65  ault value is re
2f0e0 74 75 72 6e 65 64 2e 20 20 54 68 65 20 64 65 66  turned.  The def
2f0f0 61 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 69 73  ault value.** is
2f100 20 65 69 74 68 65 72 20 74 68 65 20 69 6e 74 65   either the inte
2f110 67 65 72 20 30 2c 20 74 68 65 20 66 6c 6f 61 74  ger 0, the float
2f120 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72  ing point number
2f130 20 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a   0.0, or a NULL.
2f140 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53 75 62  ** pointer.  Sub
2f150 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f  sequent calls to
2f160 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64   [sqlite3_errcod
2f170 65 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  e()] will return
2f180 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45  .** [SQLITE_NOME
2f190 4d 5d 2e 29 5e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  M].)^.*/.SQLITE_
2f1a0 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  API const void *
2f1b0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2f1c0 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lob(sqlite3_stmt
2f1d0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51  *, int iCol);.SQ
2f1e0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
2f1f0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2f200 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  s(sqlite3_stmt*,
2f210 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49   int iCol);.SQLI
2f220 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
2f230 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
2f240 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
2f250 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49   int iCol);.SQLI
2f260 54 45 5f 41 50 49 20 64 6f 75 62 6c 65 20 73 71  TE_API double sq
2f270 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75  lite3_column_dou
2f280 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ble(sqlite3_stmt
2f290 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51  *, int iCol);.SQ
2f2a0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
2f2b0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28  ite3_column_int(
2f2c0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2f2d0 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45  nt iCol);.SQLITE
2f2e0 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74  _API sqlite3_int
2f2f0 36 34 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  64 sqlite3_colum
2f300 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f  n_int64(sqlite3_
2f310 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
2f320 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  ;.SQLITE_API con
2f330 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72  st unsigned char
2f340 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
2f350 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74  _text(sqlite3_st
2f360 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
2f370 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
2f380 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
2f390 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 73 71 6c  olumn_text16(sql
2f3a0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
2f3b0 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50  iCol);.SQLITE_AP
2f3c0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  I int sqlite3_co
2f3d0 6c 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74 65  lumn_type(sqlite
2f3e0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
2f3f0 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73  l);.SQLITE_API s
2f400 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 73 71  qlite3_value *sq
2f410 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c  lite3_column_val
2f420 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ue(sqlite3_stmt*
2f430 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a  , int iCol);../*
2f440 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
2f450 73 74 72 6f 79 20 41 20 50 72 65 70 61 72 65 64  stroy A Prepared
2f460 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63   Statement Objec
2f470 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  t.**.** ^The sql
2f480 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20  ite3_finalize() 
2f490 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c  function is call
2f4a0 65 64 20 74 6f 20 64 65 6c 65 74 65 20 61 20 5b  ed to delete a [
2f4b0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2f4c0 6e 74 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  nt]..** ^If the 
2f4d0 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 76 61 6c  most recent eval
2f4e0 75 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 74  uation of the st
2f4f0 61 74 65 6d 65 6e 74 20 65 6e 63 6f 75 6e 74 65  atement encounte
2f500 72 65 64 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a  red no errors.**
2f510 20 6f 72 20 69 66 20 74 68 65 20 73 74 61 74 65   or if the state
2f520 6d 65 6e 74 20 69 73 20 6e 65 76 65 72 20 62 65  ment is never be
2f530 65 6e 20 65 76 61 6c 75 61 74 65 64 2c 20 74 68  en evaluated, th
2f540 65 6e 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  en sqlite3_final
2f550 69 7a 65 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a  ize() returns.**
2f560 20 53 51 4c 49 54 45 5f 4f 4b 2e 20 20 5e 49 66   SQLITE_OK.  ^If
2f570 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
2f580 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 73   evaluation of s
2f590 74 61 74 65 6d 65 6e 74 20 53 20 66 61 69 6c 65  tatement S faile
2f5a0 64 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74  d, then.** sqlit
2f5b0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 72  e3_finalize(S) r
2f5c0 65 74 75 72 6e 73 20 74 68 65 20 61 70 70 72 6f  eturns the appro
2f5d0 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f  priate [error co
2f5e0 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e  de] or.** [exten
2f5f0 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 2e  ded error code].
2f600 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2f610 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20  te3_finalize(S) 
2f620 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 63  routine can be c
2f630 61 6c 6c 65 64 20 61 74 20 61 6e 79 20 70 6f 69  alled at any poi
2f640 6e 74 20 64 75 72 69 6e 67 0a 2a 2a 20 74 68 65  nt during.** the
2f650 20 6c 69 66 65 20 63 79 63 6c 65 20 6f 66 20 5b   life cycle of [
2f660 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2f670 6e 74 5d 20 53 3a 0a 2a 2a 20 62 65 66 6f 72 65  nt] S:.** before
2f680 20 73 74 61 74 65 6d 65 6e 74 20 53 20 69 73 20   statement S is 
2f690 65 76 65 72 20 65 76 61 6c 75 61 74 65 64 2c 20  ever evaluated, 
2f6a0 61 66 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20  after.** one or 
2f6b0 6d 6f 72 65 20 63 61 6c 6c 73 20 74 6f 20 5b 73  more calls to [s
2f6c0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c  qlite3_reset()],
2f6d0 20 6f 72 20 61 66 74 65 72 20 61 6e 79 20 63 61   or after any ca
2f6e0 6c 6c 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65  ll.** to [sqlite
2f6f0 33 5f 73 74 65 70 28 29 5d 20 72 65 67 61 72 64  3_step()] regard
2f700 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20  less of whether 
2f710 6f 72 20 6e 6f 74 20 74 68 65 20 73 74 61 74 65  or not the state
2f720 6d 65 6e 74 20 68 61 73 0a 2a 2a 20 63 6f 6d 70  ment has.** comp
2f730 6c 65 74 65 64 20 65 78 65 63 75 74 69 6f 6e 2e  leted execution.
2f740 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f 6b 69 6e 67  .**.** ^Invoking
2f750 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
2f760 65 28 29 20 6f 6e 20 61 20 4e 55 4c 4c 20 70 6f  e() on a NULL po
2f770 69 6e 74 65 72 20 69 73 20 61 20 68 61 72 6d 6c  inter is a harml
2f780 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a  ess no-op..**.**
2f790 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
2f7a0 20 6d 75 73 74 20 66 69 6e 61 6c 69 7a 65 20 65   must finalize e
2f7b0 76 65 72 79 20 5b 70 72 65 70 61 72 65 64 20 73  very [prepared s
2f7c0 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 6f 72 64  tatement] in ord
2f7d0 65 72 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 72  er to avoid.** r
2f7e0 65 73 6f 75 72 63 65 20 6c 65 61 6b 73 2e 20 20  esource leaks.  
2f7f0 49 74 20 69 73 20 61 20 67 72 69 65 76 6f 75 73  It is a grievous
2f800 20 65 72 72 6f 72 20 66 6f 72 20 74 68 65 20 61   error for the a
2f810 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 74 72  pplication to tr
2f820 79 20 74 6f 20 75 73 65 0a 2a 2a 20 61 20 70 72  y to use.** a pr
2f830 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2f840 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65   after it has be
2f850 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2e 20 20 41  en finalized.  A
2f860 6e 79 20 75 73 65 20 6f 66 20 61 20 70 72 65 70  ny use of a prep
2f870 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e  ared.** statemen
2f880 74 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62  t after it has b
2f890 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 20 63 61  een finalized ca
2f8a0 6e 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65  n result in unde
2f8b0 66 69 6e 65 64 20 61 6e 64 0a 2a 2a 20 75 6e 64  fined and.** und
2f8c0 65 73 69 72 61 62 6c 65 20 62 65 68 61 76 69 6f  esirable behavio
2f8d0 72 20 73 75 63 68 20 61 73 20 73 65 67 66 61 75  r such as segfau
2f8e0 6c 74 73 20 61 6e 64 20 68 65 61 70 20 63 6f 72  lts and heap cor
2f8f0 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49  ruption..*/.SQLI
2f900 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
2f910 65 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c 69  e3_finalize(sqli
2f920 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
2f930 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2f940 46 3a 20 52 65 73 65 74 20 41 20 50 72 65 70 61  F: Reset A Prepa
2f950 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62  red Statement Ob
2f960 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ject.**.** The s
2f970 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 20 66  qlite3_reset() f
2f980 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65  unction is calle
2f990 64 20 74 6f 20 72 65 73 65 74 20 61 20 5b 70 72  d to reset a [pr
2f9a0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2f9b0 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 62 61 63 6b  ].** object back
2f9c0 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20   to its initial 
2f9d0 73 74 61 74 65 2c 20 72 65 61 64 79 20 74 6f 20  state, ready to 
2f9e0 62 65 20 72 65 2d 65 78 65 63 75 74 65 64 2e 0a  be re-executed..
2f9f0 2a 2a 20 5e 41 6e 79 20 53 51 4c 20 73 74 61 74  ** ^Any SQL stat
2fa00 65 6d 65 6e 74 20 76 61 72 69 61 62 6c 65 73 20  ement variables 
2fa10 74 68 61 74 20 68 61 64 20 76 61 6c 75 65 73 20  that had values 
2fa20 62 6f 75 6e 64 20 74 6f 20 74 68 65 6d 20 75 73  bound to them us
2fa30 69 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69  ing.** the [sqli
2fa40 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20  te3_bind_blob | 
2fa50 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
2fa60 20 41 50 49 5d 20 72 65 74 61 69 6e 20 74 68 65   API] retain the
2fa70 69 72 20 76 61 6c 75 65 73 2e 0a 2a 2a 20 55 73  ir values..** Us
2fa80 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61 72  e [sqlite3_clear
2fa90 5f 62 69 6e 64 69 6e 67 73 28 29 5d 20 74 6f 20  _bindings()] to 
2faa0 72 65 73 65 74 20 74 68 65 20 62 69 6e 64 69 6e  reset the bindin
2fab0 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b  gs..**.** ^The [
2fac0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
2fad0 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 73 65  ] interface rese
2fae0 74 73 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  ts the [prepared
2faf0 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a   statement] S.**
2fb00 20 62 61 63 6b 20 74 6f 20 74 68 65 20 62 65 67   back to the beg
2fb10 69 6e 6e 69 6e 67 20 6f 66 20 69 74 73 20 70 72  inning of its pr
2fb20 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  ogram..**.** ^If
2fb30 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
2fb40 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
2fb50 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74  3_step(S)] for t
2fb60 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
2fb70 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 72 65 74  statement] S ret
2fb80 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f  urned [SQLITE_RO
2fb90 57 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f  W] or [SQLITE_DO
2fba0 4e 45 5d 2c 0a 2a 2a 20 6f 72 20 69 66 20 5b 73  NE],.** or if [s
2fbb0 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
2fbc0 68 61 73 20 6e 65 76 65 72 20 62 65 66 6f 72 65  has never before
2fbd0 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f 6e 20   been called on 
2fbe0 53 2c 0a 2a 2a 20 74 68 65 6e 20 5b 73 71 6c 69  S,.** then [sqli
2fbf0 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65  te3_reset(S)] re
2fc00 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
2fc10 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  ]..**.** ^If the
2fc20 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c   most recent cal
2fc30 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  l to [sqlite3_st
2fc40 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a  ep(S)] for the.*
2fc50 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
2fc60 65 6d 65 6e 74 5d 20 53 20 69 6e 64 69 63 61 74  ement] S indicat
2fc70 65 64 20 61 6e 20 65 72 72 6f 72 2c 20 74 68 65  ed an error, the
2fc80 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  n.** [sqlite3_re
2fc90 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20  set(S)] returns 
2fca0 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b  an appropriate [
2fcb0 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a  error code]..**.
2fcc0 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33  ** ^The [sqlite3
2fcd0 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72  _reset(S)] inter
2fce0 66 61 63 65 20 64 6f 65 73 20 6e 6f 74 20 63 68  face does not ch
2fcf0 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 73 0a  ange the values.
2fd00 2a 2a 20 6f 66 20 61 6e 79 20 5b 73 71 6c 69 74  ** of any [sqlit
2fd10 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e  e3_bind_blob|bin
2fd20 64 69 6e 67 73 5d 20 6f 6e 20 74 68 65 20 5b 70  dings] on the [p
2fd30 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2fd40 74 5d 20 53 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  t] S..*/.SQLITE_
2fd50 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
2fd60 72 65 73 65 74 28 73 71 6c 69 74 65 33 5f 73 74  reset(sqlite3_st
2fd70 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
2fd80 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 72 65  ** CAPI3REF: Cre
2fd90 61 74 65 20 4f 72 20 52 65 64 65 66 69 6e 65 20  ate Or Redefine 
2fda0 53 51 4c 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  SQL Functions.**
2fdb0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66 75 6e 63   KEYWORDS: {func
2fdc0 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f  tion creation ro
2fdd0 75 74 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f  utines}.** KEYWO
2fde0 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f  RDS: {applicatio
2fdf0 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
2fe00 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f  nction}.** KEYWO
2fe10 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f  RDS: {applicatio
2fe20 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
2fe30 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 5e  nctions}.**.** ^
2fe40 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  These functions 
2fe50 28 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e  (collectively kn
2fe60 6f 77 6e 20 61 73 20 22 66 75 6e 63 74 69 6f 6e  own as "function
2fe70 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e   creation routin
2fe80 65 73 22 29 0a 2a 2a 20 61 72 65 20 75 73 65 64  es").** are used
2fe90 20 74 6f 20 61 64 64 20 53 51 4c 20 66 75 6e 63   to add SQL func
2fea0 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61  tions or aggrega
2feb0 74 65 73 20 6f 72 20 74 6f 20 72 65 64 65 66 69  tes or to redefi
2fec0 6e 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a  ne the behavior.
2fed0 2a 2a 20 6f 66 20 65 78 69 73 74 69 6e 67 20 53  ** of existing S
2fee0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20  QL functions or 
2fef0 61 67 67 72 65 67 61 74 65 73 2e 20 20 54 68 65  aggregates.  The
2ff00 20 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 65   only difference
2ff10 73 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65  s between.** the
2ff20 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
2ff30 74 68 65 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  the text encodin
2ff40 67 20 65 78 70 65 63 74 65 64 20 66 6f 72 0a 2a  g expected for.*
2ff50 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  * the second par
2ff60 61 6d 65 74 65 72 20 28 74 68 65 20 6e 61 6d 65  ameter (the name
2ff70 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e   of the function
2ff80 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 29 0a   being created).
2ff90 2a 2a 20 61 6e 64 20 74 68 65 20 70 72 65 73 65  ** and the prese
2ffa0 6e 63 65 20 6f 72 20 61 62 73 65 6e 63 65 20 6f  nce or absence o
2ffb0 66 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 63  f a destructor c
2ffc0 61 6c 6c 62 61 63 6b 20 66 6f 72 0a 2a 2a 20 74  allback for.** t
2ffd0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
2ffe0 61 74 61 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ata pointer..**.
2fff0 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70 61  ** ^The first pa
30000 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b  rameter is the [
30010 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
30020 69 6f 6e 5d 20 74 6f 20 77 68 69 63 68 20 74 68  ion] to which th
30030 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f  e SQL.** functio
30040 6e 20 69 73 20 74 6f 20 62 65 20 61 64 64 65 64  n is to be added
30050 2e 20 20 5e 49 66 20 61 6e 20 61 70 70 6c 69 63  .  ^If an applic
30060 61 74 69 6f 6e 20 75 73 65 73 20 6d 6f 72 65 20  ation uses more 
30070 74 68 61 6e 20 6f 6e 65 20 64 61 74 61 62 61 73  than one databas
30080 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  e.** connection 
30090 74 68 65 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  then application
300a0 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
300b0 63 74 69 6f 6e 73 20 6d 75 73 74 20 62 65 20 61  ctions must be a
300c0 64 64 65 64 0a 2a 2a 20 74 6f 20 65 61 63 68 20  dded.** to each 
300d0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
300e0 69 6f 6e 20 73 65 70 61 72 61 74 65 6c 79 2e 0a  ion separately..
300f0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e  **.** ^The secon
30100 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  d parameter is t
30110 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 53  he name of the S
30120 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  QL function to b
30130 65 20 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a 20  e created or.** 
30140 72 65 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 65  redefined.  ^The
30150 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 6e   length of the n
30160 61 6d 65 20 69 73 20 6c 69 6d 69 74 65 64 20 74  ame is limited t
30170 6f 20 32 35 35 20 62 79 74 65 73 20 69 6e 20 61  o 255 bytes in a
30180 20 55 54 46 2d 38 0a 2a 2a 20 72 65 70 72 65 73   UTF-8.** repres
30190 65 6e 74 61 74 69 6f 6e 2c 20 65 78 63 6c 75 73  entation, exclus
301a0 69 76 65 20 6f 66 20 74 68 65 20 7a 65 72 6f 2d  ive of the zero-
301b0 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 4e 6f  terminator.  ^No
301c0 74 65 20 74 68 61 74 20 74 68 65 20 6e 61 6d 65  te that the name
301d0 0a 2a 2a 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74  .** length limit
301e0 20 69 73 20 69 6e 20 55 54 46 2d 38 20 62 79 74   is in UTF-8 byt
301f0 65 73 2c 20 6e 6f 74 20 63 68 61 72 61 63 74 65  es, not characte
30200 72 73 20 6e 6f 72 20 55 54 46 2d 31 36 20 62 79  rs nor UTF-16 by
30210 74 65 73 2e 20 20 0a 2a 2a 20 5e 41 6e 79 20 61  tes.  .** ^Any a
30220 74 74 65 6d 70 74 20 74 6f 20 63 72 65 61 74 65  ttempt to create
30230 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68   a function with
30240 20 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a   a longer name.*
30250 2a 20 77 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e  * will result in
30260 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
30270 20 62 65 69 6e 67 20 72 65 74 75 72 6e 65 64 2e   being returned.
30280 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72  .**.** ^The thir
30290 64 20 70 61 72 61 6d 65 74 65 72 20 28 6e 41 72  d parameter (nAr
302a0 67 29 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d  g).** is the num
302b0 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73  ber of arguments
302c0 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 66 75   that the SQL fu
302d0 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67  nction or.** agg
302e0 72 65 67 61 74 65 20 74 61 6b 65 73 2e 20 5e 49  regate takes. ^I
302f0 66 20 74 68 69 73 20 70 61 72 61 6d 65 74 65 72  f this parameter
30300 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 74 68 65   is -1, then the
30310 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72   SQL function or
30320 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 6d 61  .** aggregate ma
30330 79 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65  y take any numbe
30340 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 62  r of arguments b
30350 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68 65  etween 0 and the
30360 20 6c 69 6d 69 74 0a 2a 2a 20 73 65 74 20 62 79   limit.** set by
30370 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d   [sqlite3_limit]
30380 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46  ([SQLITE_LIMIT_F
30390 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 29 2e 20 20  UNCTION_ARG]).  
303a0 49 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20  If the third.** 
303b0 70 61 72 61 6d 65 74 65 72 20 69 73 20 6c 65 73  parameter is les
303c0 73 20 74 68 61 6e 20 2d 31 20 6f 72 20 67 72 65  s than -1 or gre
303d0 61 74 65 72 20 74 68 61 6e 20 31 32 37 20 74 68  ater than 127 th
303e0 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
303f0 69 73 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e  is.** undefined.
30400 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72  .**.** ^The four
30410 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20 65 54  th parameter, eT
30420 65 78 74 52 65 70 2c 20 73 70 65 63 69 66 69 65  extRep, specifie
30430 73 20 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 54  s what.** [SQLIT
30440 45 5f 55 54 46 38 20 7c 20 74 65 78 74 20 65 6e  E_UTF8 | text en
30450 63 6f 64 69 6e 67 5d 20 74 68 69 73 20 53 51 4c  coding] this SQL
30460 20 66 75 6e 63 74 69 6f 6e 20 70 72 65 66 65 72   function prefer
30470 73 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72  s for.** its par
30480 61 6d 65 74 65 72 73 2e 20 20 45 76 65 72 79 20  ameters.  Every 
30490 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70  SQL function imp
304a0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73 74  lementation must
304b0 20 62 65 20 61 62 6c 65 20 74 6f 20 77 6f 72 6b   be able to work
304c0 0a 2a 2a 20 77 69 74 68 20 55 54 46 2d 38 2c 20  .** with UTF-8, 
304d0 55 54 46 2d 31 36 6c 65 2c 20 6f 72 20 55 54 46  UTF-16le, or UTF
304e0 2d 31 36 62 65 2e 20 20 42 75 74 20 73 6f 6d 65  -16be.  But some
304f0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
30500 20 6d 61 79 20 62 65 0a 2a 2a 20 6d 6f 72 65 20   may be.** more 
30510 65 66 66 69 63 69 65 6e 74 20 77 69 74 68 20 6f  efficient with o
30520 6e 65 20 65 6e 63 6f 64 69 6e 67 20 74 68 61 6e  ne encoding than
30530 20 61 6e 6f 74 68 65 72 2e 20 20 5e 41 6e 20 61   another.  ^An a
30540 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 0a 2a  pplication may.*
30550 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33  * invoke sqlite3
30560 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
30570 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 72  () or sqlite3_cr
30580 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
30590 29 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 74 69  ) multiple.** ti
305a0 6d 65 73 20 77 69 74 68 20 74 68 65 20 73 61 6d  mes with the sam
305b0 65 20 66 75 6e 63 74 69 6f 6e 20 62 75 74 20 77  e function but w
305c0 69 74 68 20 64 69 66 66 65 72 65 6e 74 20 76 61  ith different va
305d0 6c 75 65 73 20 6f 66 20 65 54 65 78 74 52 65 70  lues of eTextRep
305e0 2e 0a 2a 2a 20 5e 57 68 65 6e 20 6d 75 6c 74 69  ..** ^When multi
305f0 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ple implementati
30600 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ons of the same 
30610 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 61 76 61  function are ava
30620 69 6c 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a  ilable, SQLite.*
30630 2a 20 77 69 6c 6c 20 70 69 63 6b 20 74 68 65 20  * will pick the 
30640 6f 6e 65 20 74 68 61 74 20 69 6e 76 6f 6c 76 65  one that involve
30650 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75  s the least amou
30660 6e 74 20 6f 66 20 64 61 74 61 20 63 6f 6e 76 65  nt of data conve
30670 72 73 69 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65  rsion..** If the
30680 72 65 20 69 73 20 6f 6e 6c 79 20 61 20 73 69 6e  re is only a sin
30690 67 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  gle implementati
306a0 6f 6e 20 77 68 69 63 68 20 64 6f 65 73 20 6e 6f  on which does no
306b0 74 20 63 61 72 65 20 77 68 61 74 20 74 65 78 74  t care what text
306c0 0a 2a 2a 20 65 6e 63 6f 64 69 6e 67 20 69 73 20  .** encoding is 
306d0 75 73 65 64 2c 20 74 68 65 6e 20 74 68 65 20 66  used, then the f
306e0 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 73  ourth argument s
306f0 68 6f 75 6c 64 20 62 65 20 5b 53 51 4c 49 54 45  hould be [SQLITE
30700 5f 41 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  _ANY]..**.** ^(T
30710 68 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 74  he fifth paramet
30720 65 72 20 69 73 20 61 6e 20 61 72 62 69 74 72 61  er is an arbitra
30730 72 79 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65  ry pointer.  The
30740 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
30750 6f 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69  of the.** functi
30760 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61 63 63 65  on can gain acce
30770 73 73 20 74 6f 20 74 68 69 73 20 70 6f 69 6e 74  ss to this point
30780 65 72 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  er using [sqlite
30790 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2e 29  3_user_data()].)
307a0 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78  ^.**.** ^The six
307b0 74 68 2c 20 73 65 76 65 6e 74 68 20 61 6e 64 20  th, seventh and 
307c0 65 69 67 68 74 68 20 70 61 72 61 6d 65 74 65 72  eighth parameter
307d0 73 2c 20 78 46 75 6e 63 2c 20 78 53 74 65 70 20  s, xFunc, xStep 
307e0 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a  and xFinal, are.
307f0 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 43  ** pointers to C
30800 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e 63 74 69  -language functi
30810 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65  ons that impleme
30820 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  nt the SQL funct
30830 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67  ion or.** aggreg
30840 61 74 65 2e 20 5e 41 20 73 63 61 6c 61 72 20 53  ate. ^A scalar S
30850 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75  QL function requ
30860 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e  ires an implemen
30870 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 46  tation of the xF
30880 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20  unc.** callback 
30890 6f 6e 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74  only; NULL point
308a0 65 72 73 20 6d 75 73 74 20 62 65 20 70 61 73 73  ers must be pass
308b0 65 64 20 61 73 20 74 68 65 20 78 53 74 65 70 20  ed as the xStep 
308c0 61 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a 20 70 61  and xFinal.** pa
308d0 72 61 6d 65 74 65 72 73 2e 20 5e 41 6e 20 61 67  rameters. ^An ag
308e0 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63  gregate SQL func
308f0 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e  tion requires an
30900 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
30910 6f 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20  of xStep.** and 
30920 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20  xFinal and NULL 
30930 70 6f 69 6e 74 65 72 20 6d 75 73 74 20 62 65 20  pointer must be 
30940 70 61 73 73 65 64 20 66 6f 72 20 78 46 75 6e 63  passed for xFunc
30950 2e 20 5e 54 6f 20 64 65 6c 65 74 65 20 61 6e 20  . ^To delete an 
30960 65 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20  existing.** SQL 
30970 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72  function or aggr
30980 65 67 61 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c  egate, pass NULL
30990 20 70 6f 69 6e 74 65 72 73 20 66 6f 72 20 61 6c   pointers for al
309a0 6c 20 74 68 72 65 65 20 66 75 6e 63 74 69 6f 6e  l three function
309b0 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a  .** callbacks..*
309c0 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 65 20 6e 69  *.** ^(If the ni
309d0 6e 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  nth parameter to
309e0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
309f0 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 69 73  function_v2() is
30a00 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 74 68   not NULL,.** th
30a10 65 6e 20 69 74 20 69 73 20 64 65 73 74 72 75 63  en it is destruc
30a20 74 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70 6c  tor for the appl
30a30 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69  ication data poi
30a40 6e 74 65 72 2e 20 0a 2a 2a 20 54 68 65 20 64 65  nter. .** The de
30a50 73 74 72 75 63 74 6f 72 20 69 73 20 69 6e 76 6f  structor is invo
30a60 6b 65 64 20 77 68 65 6e 20 74 68 65 20 66 75 6e  ked when the fun
30a70 63 74 69 6f 6e 20 69 73 20 64 65 6c 65 74 65 64  ction is deleted
30a80 2c 20 65 69 74 68 65 72 20 62 79 20 62 65 69 6e  , either by bein
30a90 67 0a 2a 2a 20 6f 76 65 72 6c 6f 61 64 65 64 20  g.** overloaded 
30aa0 6f 72 20 77 68 65 6e 20 74 68 65 20 64 61 74 61  or when the data
30ab0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
30ac0 63 6c 6f 73 65 73 2e 29 5e 0a 2a 2a 20 5e 54 68  closes.)^.** ^Th
30ad0 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20  e destructor is 
30ae0 61 6c 73 6f 20 69 6e 76 6f 6b 65 64 20 69 66 20  also invoked if 
30af0 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73  the call to.** s
30b00 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
30b10 6e 63 74 69 6f 6e 5f 76 32 28 29 20 66 61 69 6c  nction_v2() fail
30b20 73 2e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20  s..** ^When the 
30b30 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62  destructor callb
30b40 61 63 6b 20 6f 66 20 74 68 65 20 74 65 6e 74 68  ack of the tenth
30b50 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 69 6e   parameter is in
30b60 76 6f 6b 65 64 2c 20 69 74 0a 2a 2a 20 69 73 20  voked, it.** is 
30b70 70 61 73 73 65 64 20 61 20 73 69 6e 67 6c 65 20  passed a single 
30b80 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
30b90 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
30ba0 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61  application data
30bb0 20 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 77 68 69   .** pointer whi
30bc0 63 68 20 77 61 73 20 74 68 65 20 66 69 66 74 68  ch was the fifth
30bd0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
30be0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
30bf0 63 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a  ction_v2()..**.*
30c00 2a 20 5e 49 74 20 69 73 20 70 65 72 6d 69 74 74  * ^It is permitt
30c10 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d  ed to register m
30c20 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e  ultiple implemen
30c30 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  tations of the s
30c40 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73  ame.** functions
30c50 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e   with the same n
30c60 61 6d 65 20 62 75 74 20 77 69 74 68 20 65 69 74  ame but with eit
30c70 68 65 72 20 64 69 66 66 65 72 69 6e 67 20 6e 75  her differing nu
30c80 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75  mbers of.** argu
30c90 6d 65 6e 74 73 20 6f 72 20 64 69 66 66 65 72 69  ments or differi
30ca0 6e 67 20 70 72 65 66 65 72 72 65 64 20 74 65 78  ng preferred tex
30cb0 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20 5e 53  t encodings.  ^S
30cc0 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a  QLite will use.*
30cd0 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  * the implementa
30ce0 74 69 6f 6e 20 74 68 61 74 20 6d 6f 73 74 20 63  tion that most c
30cf0 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65 73 20 74  losely matches t
30d00 68 65 20 77 61 79 20 69 6e 20 77 68 69 63 68 20  he way in which 
30d10 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74  the.** SQL funct
30d20 69 6f 6e 20 69 73 20 75 73 65 64 2e 20 20 5e 41  ion is used.  ^A
30d30 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
30d40 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 20 61 20  entation with a 
30d50 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 0a 2a 2a 20  non-negative.** 
30d60 6e 41 72 67 20 70 61 72 61 6d 65 74 65 72 20 69  nArg parameter i
30d70 73 20 61 20 62 65 74 74 65 72 20 6d 61 74 63 68  s a better match
30d80 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e   than a function
30d90 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
30da0 77 69 74 68 0a 2a 2a 20 61 20 6e 65 67 61 74 69  with.** a negati
30db0 76 65 20 6e 41 72 67 2e 20 20 5e 41 20 66 75 6e  ve nArg.  ^A fun
30dc0 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20  ction where the 
30dd0 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65  preferred text e
30de0 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74 63 68  ncoding.** match
30df0 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  es the database 
30e00 65 6e 63 6f 64 69 6e 67 20 69 73 20 61 20 62 65  encoding is a be
30e10 74 74 65 72 0a 2a 2a 20 6d 61 74 63 68 20 74 68  tter.** match th
30e20 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68  an a function wh
30e30 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67  ere the encoding
30e40 20 69 73 20 64 69 66 66 65 72 65 6e 74 2e 20 20   is different.  
30e50 0a 2a 2a 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20  .** ^A function 
30e60 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69  where the encodi
30e70 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 73  ng difference is
30e80 20 62 65 74 77 65 65 6e 20 55 54 46 31 36 6c 65   between UTF16le
30e90 20 61 6e 64 20 55 54 46 31 36 62 65 0a 2a 2a 20   and UTF16be.** 
30ea0 69 73 20 61 20 63 6c 6f 73 65 72 20 6d 61 74 63  is a closer matc
30eb0 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f  h than a functio
30ec0 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f  n where the enco
30ed0 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20  ding difference 
30ee0 69 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 55 54  is.** between UT
30ef0 46 38 20 61 6e 64 20 55 54 46 31 36 2e 0a 2a 2a  F8 and UTF16..**
30f00 0a 2a 2a 20 5e 42 75 69 6c 74 2d 69 6e 20 66 75  .** ^Built-in fu
30f10 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 6f  nctions may be o
30f20 76 65 72 6c 6f 61 64 65 64 20 62 79 20 6e 65 77  verloaded by new
30f30 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
30f40 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 2e 0a  ined functions..
30f50 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 70 70 6c 69 63  **.** ^An applic
30f60 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
30f70 6e 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74  nction is permit
30f80 74 65 64 20 74 6f 20 63 61 6c 6c 20 6f 74 68 65  ted to call othe
30f90 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65  r.** SQLite inte
30fa0 72 66 61 63 65 73 2e 20 20 48 6f 77 65 76 65 72  rfaces.  However
30fb0 2c 20 73 75 63 68 20 63 61 6c 6c 73 20 6d 75 73  , such calls mus
30fc0 74 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20 74  t not.** close t
30fd0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
30fe0 65 63 74 69 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c  ection nor final
30ff0 69 7a 65 20 6f 72 20 72 65 73 65 74 20 74 68 65  ize or reset the
31000 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61   prepared.** sta
31010 74 65 6d 65 6e 74 20 69 6e 20 77 68 69 63 68 20  tement in which 
31020 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  the function is 
31030 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49  running..*/.SQLI
31040 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
31050 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
31060 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  on(.  sqlite3 *d
31070 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  b,.  const char 
31080 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a  *zFunctionName,.
31090 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e    int nArg,.  in
310a0 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f  t eTextRep,.  vo
310b0 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64  id *pApp,.  void
310c0 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65   (*xFunc)(sqlite
310d0 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
310e0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
310f0 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29  .  void (*xStep)
31100 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
31110 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
31120 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
31130 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33  *xFinal)(sqlite3
31140 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 53 51  _context*).);.SQ
31150 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
31160 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
31170 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65  tion16(.  sqlite
31180 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 76  3 *db,.  const v
31190 6f 69 64 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61  oid *zFunctionNa
311a0 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a  me,.  int nArg,.
311b0 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a    int eTextRep,.
311c0 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20    void *pApp,.  
311d0 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71  void (*xFunc)(sq
311e0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
311f0 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
31200 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53  **),.  void (*xS
31210 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  tep)(sqlite3_con
31220 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
31230 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
31240 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c  id (*xFinal)(sql
31250 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29  ite3_context*).)
31260 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
31270 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
31280 66 75 6e 63 74 69 6f 6e 5f 76 32 28 0a 20 20 73  function_v2(.  s
31290 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f  qlite3 *db,.  co
312a0 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74  nst char *zFunct
312b0 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e  ionName,.  int n
312c0 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74  Arg,.  int eText
312d0 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70  Rep,.  void *pAp
312e0 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e  p,.  void (*xFun
312f0 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  c)(sqlite3_conte
31300 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
31310 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
31320 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65   (*xStep)(sqlite
31330 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
31340 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
31350 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c  .  void (*xFinal
31360 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
31370 74 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65  t*),.  void(*xDe
31380 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b  stroy)(void*).);
31390 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
313a0 3a 20 54 65 78 74 20 45 6e 63 6f 64 69 6e 67 73  : Text Encodings
313b0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
313c0 73 74 61 6e 74 20 64 65 66 69 6e 65 20 69 6e 74  stant define int
313d0 65 67 65 72 20 63 6f 64 65 73 20 74 68 61 74 20  eger codes that 
313e0 72 65 70 72 65 73 65 6e 74 20 74 68 65 20 76 61  represent the va
313f0 72 69 6f 75 73 0a 2a 2a 20 74 65 78 74 20 65 6e  rious.** text en
31400 63 6f 64 69 6e 67 73 20 73 75 70 70 6f 72 74 65  codings supporte
31410 64 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a  d by SQLite..*/.
31420 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
31430 54 46 38 20 20 20 20 20 20 20 20 20 20 20 31 0a  TF8           1.
31440 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
31450 54 46 31 36 4c 45 20 20 20 20 20 20 20 20 32 0a  TF16LE        2.
31460 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
31470 54 46 31 36 42 45 20 20 20 20 20 20 20 20 33 0a  TF16BE        3.
31480 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
31490 54 46 31 36 20 20 20 20 20 20 20 20 20 20 34 20  TF16          4 
314a0 20 20 20 2f 2a 20 55 73 65 20 6e 61 74 69 76 65     /* Use native
314b0 20 62 79 74 65 20 6f 72 64 65 72 20 2a 2f 0a 23   byte order */.#
314c0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e  define SQLITE_AN
314d0 59 20 20 20 20 20 20 20 20 20 20 20 20 35 20 20  Y            5  
314e0 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65    /* sqlite3_cre
314f0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 20 6f 6e 6c  ate_function onl
31500 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
31510 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45  ITE_UTF16_ALIGNE
31520 44 20 20 38 20 20 20 20 2f 2a 20 73 71 6c 69 74  D  8    /* sqlit
31530 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
31540 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a  ion only */../*.
31550 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 70  ** CAPI3REF: Dep
31560 72 65 63 61 74 65 64 20 46 75 6e 63 74 69 6f 6e  recated Function
31570 73 0a 2a 2a 20 44 45 50 52 45 43 41 54 45 44 0a  s.** DEPRECATED.
31580 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63  **.** These func
31590 74 69 6f 6e 73 20 61 72 65 20 5b 64 65 70 72 65  tions are [depre
315a0 63 61 74 65 64 5d 2e 20 20 49 6e 20 6f 72 64 65  cated].  In orde
315b0 72 20 74 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a  r to maintain.**
315c0 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61   backwards compa
315d0 74 69 62 69 6c 69 74 79 20 77 69 74 68 20 6f 6c  tibility with ol
315e0 64 65 72 20 63 6f 64 65 2c 20 74 68 65 73 65 20  der code, these 
315f0 66 75 6e 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e  functions contin
31600 75 65 20 0a 2a 2a 20 74 6f 20 62 65 20 73 75 70  ue .** to be sup
31610 70 6f 72 74 65 64 2e 20 20 48 6f 77 65 76 65 72  ported.  However
31620 2c 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f  , new applicatio
31630 6e 73 20 73 68 6f 75 6c 64 20 61 76 6f 69 64 0a  ns should avoid.
31640 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20 74 68  ** the use of th
31650 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20  ese functions.  
31660 54 6f 20 68 65 6c 70 20 65 6e 63 6f 75 72 61 67  To help encourag
31670 65 20 70 65 6f 70 6c 65 20 74 6f 20 61 76 6f 69  e people to avoi
31680 64 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65 73 65  d.** using these
31690 20 66 75 6e 63 74 69 6f 6e 73 2c 20 77 65 20 61   functions, we a
316a0 72 65 20 6e 6f 74 20 67 6f 69 6e 67 20 74 6f 20  re not going to 
316b0 74 65 6c 6c 20 79 6f 75 20 77 68 61 74 20 74 68  tell you what th
316c0 65 79 20 64 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65  ey do..*/.#ifnde
316d0 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 44 45  f SQLITE_OMIT_DE
316e0 50 52 45 43 41 54 45 44 0a 53 51 4c 49 54 45 5f  PRECATED.SQLITE_
316f0 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45  API SQLITE_DEPRE
31700 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65  CATED int sqlite
31710 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 75 6e  3_aggregate_coun
31720 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t(sqlite3_contex
31730 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  t*);.SQLITE_API 
31740 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
31750 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78  D int sqlite3_ex
31760 70 69 72 65 64 28 73 71 6c 69 74 65 33 5f 73 74  pired(sqlite3_st
31770 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  mt*);.SQLITE_API
31780 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54   SQLITE_DEPRECAT
31790 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 74  ED int sqlite3_t
317a0 72 61 6e 73 66 65 72 5f 62 69 6e 64 69 6e 67 73  ransfer_bindings
317b0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
317c0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
317d0 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54  SQLITE_API SQLIT
317e0 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74  E_DEPRECATED int
317f0 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f   sqlite3_global_
31800 72 65 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a 53  recover(void);.S
31810 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45  QLITE_API SQLITE
31820 5f 44 45 50 52 45 43 41 54 45 44 20 76 6f 69 64  _DEPRECATED void
31830 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 5f   sqlite3_thread_
31840 63 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a 53  cleanup(void);.S
31850 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45  QLITE_API SQLITE
31860 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20  _DEPRECATED int 
31870 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 61  sqlite3_memory_a
31880 6c 61 72 6d 28 76 6f 69 64 28 2a 29 28 76 6f 69  larm(void(*)(voi
31890 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  d*,sqlite3_int64
318a0 2c 69 6e 74 29 2c 76 6f 69 64 2a 2c 73 71 6c 69  ,int),void*,sqli
318b0 74 65 33 5f 69 6e 74 36 34 29 3b 0a 23 65 6e 64  te3_int64);.#end
318c0 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  if../*.** CAPI3R
318d0 45 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20 53 51  EF: Obtaining SQ
318e0 4c 20 46 75 6e 63 74 69 6f 6e 20 50 61 72 61 6d  L Function Param
318f0 65 74 65 72 20 56 61 6c 75 65 73 0a 2a 2a 0a 2a  eter Values.**.*
31900 2a 20 54 68 65 20 43 2d 6c 61 6e 67 75 61 67 65  * The C-language
31910 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
31920 6f 66 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  of SQL functions
31930 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 20   and aggregates 
31940 75 73 65 73 0a 2a 2a 20 74 68 69 73 20 73 65 74  uses.** this set
31950 20 6f 66 20 69 6e 74 65 72 66 61 63 65 20 72 6f   of interface ro
31960 75 74 69 6e 65 73 20 74 6f 20 61 63 63 65 73 73  utines to access
31970 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 76   the parameter v
31980 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74 68 65 20  alues on.** the 
31990 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72  function or aggr
319a0 65 67 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  egate..**.** The
319b0 20 78 46 75 6e 63 20 28 66 6f 72 20 73 63 61 6c   xFunc (for scal
319c0 61 72 20 66 75 6e 63 74 69 6f 6e 73 29 20 6f 72  ar functions) or
319d0 20 78 53 74 65 70 20 28 66 6f 72 20 61 67 67 72   xStep (for aggr
319e0 65 67 61 74 65 73 29 20 70 61 72 61 6d 65 74 65  egates) paramete
319f0 72 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65  rs.** to [sqlite
31a00 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
31a10 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  n()] and [sqlite
31a20 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
31a30 6e 31 36 28 29 5d 0a 2a 2a 20 64 65 66 69 6e 65  n16()].** define
31a40 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 20   callbacks that 
31a50 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51  implement the SQ
31a60 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20  L functions and 
31a70 61 67 67 72 65 67 61 74 65 73 2e 0a 2a 2a 20 54  aggregates..** T
31a80 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  he 3rd parameter
31a90 20 74 6f 20 74 68 65 73 65 20 63 61 6c 6c 62 61   to these callba
31aa0 63 6b 73 20 69 73 20 61 6e 20 61 72 72 61 79 20  cks is an array 
31ab0 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 0a 2a  of pointers to.*
31ac0 2a 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  * [protected sql
31ad0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
31ae0 63 74 73 2e 20 20 54 68 65 72 65 20 69 73 20 6f  cts.  There is o
31af0 6e 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ne [sqlite3_valu
31b00 65 5d 20 6f 62 6a 65 63 74 20 66 6f 72 0a 2a 2a  e] object for.**
31b10 20 65 61 63 68 20 70 61 72 61 6d 65 74 65 72 20   each parameter 
31b20 74 6f 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  to the SQL funct
31b30 69 6f 6e 2e 20 20 54 68 65 73 65 20 72 6f 75 74  ion.  These rout
31b40 69 6e 65 73 20 61 72 65 20 75 73 65 64 20 74 6f  ines are used to
31b50 0a 2a 2a 20 65 78 74 72 61 63 74 20 76 61 6c 75  .** extract valu
31b60 65 73 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c  es from the [sql
31b70 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
31b80 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  cts..**.** These
31b90 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6f   routines work o
31ba0 6e 6c 79 20 77 69 74 68 20 5b 70 72 6f 74 65 63  nly with [protec
31bb0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
31bc0 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 41  e] objects..** A
31bd0 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73  ny attempt to us
31be0 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  e these routines
31bf0 20 6f 6e 20 61 6e 20 5b 75 6e 70 72 6f 74 65 63   on an [unprotec
31c00 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
31c10 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 73  e].** object res
31c20 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65  ults in undefine
31c30 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a  d behavior..**.*
31c40 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
31c50 73 20 77 6f 72 6b 20 6a 75 73 74 20 6c 69 6b 65  s work just like
31c60 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69   the correspondi
31c70 6e 67 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73  ng [column acces
31c80 73 20 66 75 6e 63 74 69 6f 6e 73 5d 0a 2a 2a 20  s functions].** 
31c90 65 78 63 65 70 74 20 74 68 61 74 20 20 74 68 65  except that  the
31ca0 73 65 20 72 6f 75 74 69 6e 65 73 20 74 61 6b 65  se routines take
31cb0 20 61 20 73 69 6e 67 6c 65 20 5b 70 72 6f 74 65   a single [prote
31cc0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
31cd0 75 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 70 6f  ue] object.** po
31ce0 69 6e 74 65 72 20 69 6e 73 74 65 61 64 20 6f 66  inter instead of
31cf0 20 61 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74   a [sqlite3_stmt
31d00 2a 5d 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 61  *] pointer and a
31d10 6e 20 69 6e 74 65 67 65 72 20 63 6f 6c 75 6d 6e  n integer column
31d20 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e   number..**.** ^
31d30 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  The sqlite3_valu
31d40 65 5f 74 65 78 74 31 36 28 29 20 69 6e 74 65 72  e_text16() inter
31d50 66 61 63 65 20 65 78 74 72 61 63 74 73 20 61 20  face extracts a 
31d60 55 54 46 2d 31 36 20 73 74 72 69 6e 67 0a 2a 2a  UTF-16 string.**
31d70 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62   in the native b
31d80 79 74 65 2d 6f 72 64 65 72 20 6f 66 20 74 68 65  yte-order of the
31d90 20 68 6f 73 74 20 6d 61 63 68 69 6e 65 2e 20 20   host machine.  
31da0 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ^The.** sqlite3_
31db0 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 29  value_text16be()
31dc0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 61 6c   and sqlite3_val
31dd0 75 65 5f 74 65 78 74 31 36 6c 65 28 29 20 69 6e  ue_text16le() in
31de0 74 65 72 66 61 63 65 73 0a 2a 2a 20 65 78 74 72  terfaces.** extr
31df0 61 63 74 20 55 54 46 2d 31 36 20 73 74 72 69 6e  act UTF-16 strin
31e00 67 73 20 61 73 20 62 69 67 2d 65 6e 64 69 61 6e  gs as big-endian
31e10 20 61 6e 64 20 6c 69 74 74 6c 65 2d 65 6e 64 69   and little-endi
31e20 61 6e 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  an respectively.
31e30 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c  .**.** ^(The sql
31e40 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72  ite3_value_numer
31e50 69 63 5f 74 79 70 65 28 29 20 69 6e 74 65 72 66  ic_type() interf
31e60 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20  ace attempts to 
31e70 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69 63  apply.** numeric
31e80 20 61 66 66 69 6e 69 74 79 20 74 6f 20 74 68 65   affinity to the
31e90 20 76 61 6c 75 65 2e 20 20 54 68 69 73 20 6d 65   value.  This me
31ea0 61 6e 73 20 74 68 61 74 20 61 6e 20 61 74 74 65  ans that an atte
31eb0 6d 70 74 20 69 73 0a 2a 2a 20 6d 61 64 65 20 74  mpt is.** made t
31ec0 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61  o convert the va
31ed0 6c 75 65 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  lue to an intege
31ee0 72 20 6f 72 20 66 6c 6f 61 74 69 6e 67 20 70 6f  r or floating po
31ef0 69 6e 74 2e 20 20 49 66 0a 2a 2a 20 73 75 63 68  int.  If.** such
31f00 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73   a conversion is
31f10 20 70 6f 73 73 69 62 6c 65 20 77 69 74 68 6f 75   possible withou
31f20 74 20 6c 6f 73 73 20 6f 66 20 69 6e 66 6f 72 6d  t loss of inform
31f30 61 74 69 6f 6e 20 28 69 6e 20 6f 74 68 65 72 0a  ation (in other.
31f40 2a 2a 20 77 6f 72 64 73 2c 20 69 66 20 74 68 65  ** words, if the
31f50 20 76 61 6c 75 65 20 69 73 20 61 20 73 74 72 69   value is a stri
31f60 6e 67 20 74 68 61 74 20 6c 6f 6f 6b 73 20 6c 69  ng that looks li
31f70 6b 65 20 61 20 6e 75 6d 62 65 72 29 0a 2a 2a 20  ke a number).** 
31f80 74 68 65 6e 20 74 68 65 20 63 6f 6e 76 65 72 73  then the convers
31f90 69 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d 65 64  ion is performed
31fa0 2e 20 20 4f 74 68 65 72 77 69 73 65 20 6e 6f 20  .  Otherwise no 
31fb0 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72  conversion occur
31fc0 73 2e 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  s..** The [SQLIT
31fd0 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61  E_INTEGER | data
31fe0 74 79 70 65 5d 20 61 66 74 65 72 20 63 6f 6e 76  type] after conv
31ff0 65 72 73 69 6f 6e 20 69 73 20 72 65 74 75 72 6e  ersion is return
32000 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61  ed.)^.**.** Plea
32010 73 65 20 70 61 79 20 70 61 72 74 69 63 75 6c 61  se pay particula
32020 72 20 61 74 74 65 6e 74 69 6f 6e 20 74 6f 20 74  r attention to t
32030 68 65 20 66 61 63 74 20 74 68 61 74 20 74 68 65  he fact that the
32040 20 70 6f 69 6e 74 65 72 20 72 65 74 75 72 6e 65   pointer returne
32050 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74  d.** from [sqlit
32060 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 29 5d  e3_value_blob()]
32070 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  , [sqlite3_value
32080 5f 74 65 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20  _text()], or.** 
32090 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
320a0 65 78 74 31 36 28 29 5d 20 63 61 6e 20 62 65 20  ext16()] can be 
320b0 69 6e 76 61 6c 69 64 61 74 65 64 20 62 79 20 61  invalidated by a
320c0 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
320d0 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
320e0 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20  value_bytes()], 
320f0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  [sqlite3_value_b
32100 79 74 65 73 31 36 28 29 5d 2c 20 5b 73 71 6c 69  ytes16()], [sqli
32110 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29  te3_value_text()
32120 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65  ],.** or [sqlite
32130 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29  3_value_text16()
32140 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  ]..**.** These r
32150 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20  outines must be 
32160 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20  called from the 
32170 73 61 6d 65 20 74 68 72 65 61 64 20 61 73 0a 2a  same thread as.*
32180 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  * the SQL functi
32190 6f 6e 20 74 68 61 74 20 73 75 70 70 6c 69 65 64  on that supplied
321a0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   the [sqlite3_va
321b0 6c 75 65 2a 5d 20 70 61 72 61 6d 65 74 65 72 73  lue*] parameters
321c0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
321d0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
321e0 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73  te3_value_blob(s
321f0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
32200 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
32210 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
32220 65 73 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  es(sqlite3_value
32230 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  *);.SQLITE_API i
32240 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt sqlite3_value
32250 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74 65 33  _bytes16(sqlite3
32260 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45  _value*);.SQLITE
32270 5f 41 50 49 20 64 6f 75 62 6c 65 20 73 71 6c 69  _API double sqli
32280 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65  te3_value_double
32290 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
322a0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
322b0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69   sqlite3_value_i
322c0 6e 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt(sqlite3_value
322d0 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73  *);.SQLITE_API s
322e0 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
322f0 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36 34  ite3_value_int64
32300 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
32310 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  ;.SQLITE_API con
32320 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72  st unsigned char
32330 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   *sqlite3_value_
32340 74 65 78 74 28 73 71 6c 69 74 65 33 5f 76 61 6c  text(sqlite3_val
32350 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  ue*);.SQLITE_API
32360 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c   const void *sql
32370 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
32380 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  6(sqlite3_value*
32390 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  );.SQLITE_API co
323a0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
323b0 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65  3_value_text16le
323c0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
323d0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  ;.SQLITE_API con
323e0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
323f0 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28  _value_text16be(
32400 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
32410 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
32420 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79  sqlite3_value_ty
32430 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  pe(sqlite3_value
32440 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  *);.SQLITE_API i
32450 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt sqlite3_value
32460 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 73 71  _numeric_type(sq
32470 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a  lite3_value*);..
32480 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
32490 4f 62 74 61 69 6e 20 41 67 67 72 65 67 61 74 65  Obtain Aggregate
324a0 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78   Function Contex
324b0 74 0a 2a 2a 0a 2a 2a 20 49 6d 70 6c 65 6d 65 6e  t.**.** Implemen
324c0 74 61 74 69 6f 6e 73 20 6f 66 20 61 67 67 72 65  tations of aggre
324d0 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f  gate SQL functio
324e0 6e 73 20 75 73 65 20 74 68 69 73 0a 2a 2a 20 72  ns use this.** r
324f0 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 61  outine to alloca
32500 74 65 20 6d 65 6d 6f 72 79 20 66 6f 72 20 73 74  te memory for st
32510 6f 72 69 6e 67 20 74 68 65 69 72 20 73 74 61 74  oring their stat
32520 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  e..**.** ^The fi
32530 72 73 74 20 74 69 6d 65 20 74 68 65 20 73 71 6c  rst time the sql
32540 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
32550 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 74  ontext(C,N) rout
32560 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 0a 2a  ine is called .*
32570 2a 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c  * for a particul
32580 61 72 20 61 67 67 72 65 67 61 74 65 20 66 75 6e  ar aggregate fun
32590 63 74 69 6f 6e 2c 20 53 51 4c 69 74 65 0a 2a 2a  ction, SQLite.**
325a0 20 61 6c 6c 6f 63 61 74 65 73 20 4e 20 6f 66 20   allocates N of 
325b0 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f 65 73 20 6f  memory, zeroes o
325c0 75 74 20 74 68 61 74 20 6d 65 6d 6f 72 79 2c 20  ut that memory, 
325d0 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f  and returns a po
325e0 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  inter.** to the 
325f0 6e 65 77 20 6d 65 6d 6f 72 79 2e 20 5e 4f 6e 20  new memory. ^On 
32600 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65  second and subse
32610 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a 2a  quent calls to.*
32620 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  * sqlite3_aggreg
32630 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 66 6f  ate_context() fo
32640 72 20 74 68 65 20 73 61 6d 65 20 61 67 67 72 65  r the same aggre
32650 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e  gate function in
32660 73 74 61 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 73  stance,.** the s
32670 61 6d 65 20 62 75 66 66 65 72 20 69 73 20 72 65  ame buffer is re
32680 74 75 72 6e 65 64 2e 20 20 53 71 6c 69 74 65 33  turned.  Sqlite3
32690 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
326a0 78 74 28 29 20 69 73 20 6e 6f 72 6d 61 6c 6c 79  xt() is normally
326b0 0a 2a 2a 20 63 61 6c 6c 65 64 20 6f 6e 63 65 20  .** called once 
326c0 66 6f 72 20 65 61 63 68 20 69 6e 76 6f 63 61 74  for each invocat
326d0 69 6f 6e 20 6f 66 20 74 68 65 20 78 53 74 65 70  ion of the xStep
326e0 20 63 61 6c 6c 62 61 63 6b 20 61 6e 64 20 74 68   callback and th
326f0 65 6e 20 6f 6e 65 0a 2a 2a 20 6c 61 73 74 20 74  en one.** last t
32700 69 6d 65 20 77 68 65 6e 20 74 68 65 20 78 46 69  ime when the xFi
32710 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  nal callback is 
32720 69 6e 76 6f 6b 65 64 2e 20 20 5e 28 57 68 65 6e  invoked.  ^(When
32730 20 6e 6f 20 72 6f 77 73 20 6d 61 74 63 68 0a 2a   no rows match.*
32740 2a 20 61 6e 20 61 67 67 72 65 67 61 74 65 20 71  * an aggregate q
32750 75 65 72 79 2c 20 74 68 65 20 78 53 74 65 70 28  uery, the xStep(
32760 29 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68  ) callback of th
32770 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63  e aggregate func
32780 74 69 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  tion.** implemen
32790 74 61 74 69 6f 6e 20 69 73 20 6e 65 76 65 72 20  tation is never 
327a0 63 61 6c 6c 65 64 20 61 6e 64 20 78 46 69 6e 61  called and xFina
327b0 6c 28 29 20 69 73 20 63 61 6c 6c 65 64 20 65 78  l() is called ex
327c0 61 63 74 6c 79 20 6f 6e 63 65 2e 0a 2a 2a 20 49  actly once..** I
327d0 6e 20 74 68 6f 73 65 20 63 61 73 65 73 2c 20 73  n those cases, s
327e0 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
327f0 5f 63 6f 6e 74 65 78 74 28 29 20 6d 69 67 68 74  _context() might
32800 20 62 65 20 63 61 6c 6c 65 64 20 66 6f 72 20 74   be called for t
32810 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 69 6d 65  he.** first time
32820 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 78 46 69   from within xFi
32830 6e 61 6c 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  nal().)^.**.** ^
32840 54 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72  The sqlite3_aggr
32850 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c  egate_context(C,
32860 4e 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  N) routine retur
32870 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ns a NULL pointe
32880 72 20 69 66 20 4e 20 69 73 0a 2a 2a 20 6c 65 73  r if N is.** les
32890 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20  s than or equal 
328a0 74 6f 20 7a 65 72 6f 20 6f 72 20 69 66 20 61 20  to zero or if a 
328b0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65 20  memory allocate 
328c0 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 0a 2a 2a  error occurs..**
328d0 0a 2a 2a 20 5e 28 54 68 65 20 61 6d 6f 75 6e 74  .** ^(The amount
328e0 20 6f 66 20 73 70 61 63 65 20 61 6c 6c 6f 63 61   of space alloca
328f0 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 61  ted by sqlite3_a
32900 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
32910 28 43 2c 4e 29 20 69 73 0a 2a 2a 20 64 65 74 65  (C,N) is.** dete
32920 72 6d 69 6e 65 64 20 62 79 20 74 68 65 20 4e 20  rmined by the N 
32930 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 66 69 72  parameter on fir
32940 73 74 20 73 75 63 63 65 73 73 66 75 6c 20 63 61  st successful ca
32950 6c 6c 2e 20 20 43 68 61 6e 67 69 6e 67 20 74 68  ll.  Changing th
32960 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 4e 20  e.** value of N 
32970 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 61  in subsequent ca
32980 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 61 67  ll to sqlite3_ag
32990 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
329a0 29 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20  ) within.** the 
329b0 73 61 6d 65 20 61 67 67 72 65 67 61 74 65 20 66  same aggregate f
329c0 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65  unction instance
329d0 20 77 69 6c 6c 20 6e 6f 74 20 72 65 73 69 7a 65   will not resize
329e0 20 74 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61   the memory.** a
329f0 6c 6c 6f 63 61 74 69 6f 6e 2e 29 5e 0a 2a 2a 0a  llocation.)^.**.
32a00 2a 2a 20 5e 53 51 4c 69 74 65 20 61 75 74 6f 6d  ** ^SQLite autom
32a10 61 74 69 63 61 6c 6c 79 20 66 72 65 65 73 20 74  atically frees t
32a20 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
32a30 74 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69 74  ted by .** sqlit
32a40 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
32a50 74 65 78 74 28 29 20 77 68 65 6e 20 74 68 65 20  text() when the 
32a60 61 67 67 72 65 67 61 74 65 20 71 75 65 72 79 20  aggregate query 
32a70 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a  concludes..**.**
32a80 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   The first param
32a90 65 74 65 72 20 6d 75 73 74 20 62 65 20 61 20 63  eter must be a c
32aa0 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73  opy of the.** [s
32ab0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 7c  qlite3_context |
32ac0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63 6f   SQL function co
32ad0 6e 74 65 78 74 5d 20 74 68 61 74 20 69 73 20 74  ntext] that is t
32ae0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
32af0 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 78 53 74  er.** to the xSt
32b00 65 70 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c  ep or xFinal cal
32b10 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 74 68  lback routine th
32b20 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68  at implements th
32b30 65 20 61 67 67 72 65 67 61 74 65 0a 2a 2a 20 66  e aggregate.** f
32b40 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54  unction..**.** T
32b50 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74  his routine must
32b60 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20   be called from 
32b70 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20  the same thread 
32b80 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20  in which.** the 
32b90 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75  aggregate SQL fu
32ba0 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e  nction is runnin
32bb0 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  g..*/.SQLITE_API
32bc0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 61   void *sqlite3_a
32bd0 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
32be0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
32bf0 2a 2c 20 69 6e 74 20 6e 42 79 74 65 73 29 3b 0a  *, int nBytes);.
32c00 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
32c10 20 55 73 65 72 20 44 61 74 61 20 46 6f 72 20 46   User Data For F
32c20 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e  unctions.**.** ^
32c30 54 68 65 20 73 71 6c 69 74 65 33 5f 75 73 65 72  The sqlite3_user
32c40 5f 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63  _data() interfac
32c50 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79  e returns a copy
32c60 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74   of.** the point
32c70 65 72 20 74 68 61 74 20 77 61 73 20 74 68 65 20  er that was the 
32c80 70 55 73 65 72 44 61 74 61 20 70 61 72 61 6d 65  pUserData parame
32c90 74 65 72 20 28 74 68 65 20 35 74 68 20 70 61 72  ter (the 5th par
32ca0 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68  ameter).** of th
32cb0 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  e [sqlite3_creat
32cc0 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a  e_function()].**
32cd0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72   and [sqlite3_cr
32ce0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
32cf0 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74  )] routines that
32d00 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72   originally.** r
32d10 65 67 69 73 74 65 72 65 64 20 74 68 65 20 61 70  egistered the ap
32d20 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65  plication define
32d30 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a  d function..**.*
32d40 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d  * This routine m
32d50 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72  ust be called fr
32d60 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65  om the same thre
32d70 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74  ad in which.** t
32d80 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
32d90 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
32da0 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53  is running..*/.S
32db0 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a  QLITE_API void *
32dc0 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74  sqlite3_user_dat
32dd0 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  a(sqlite3_contex
32de0 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
32df0 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43  3REF: Database C
32e00 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f 72 20 46 75  onnection For Fu
32e10 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54  nctions.**.** ^T
32e20 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  he sqlite3_conte
32e30 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 20 69  xt_db_handle() i
32e40 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
32e50 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68   a copy of.** th
32e60 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  e pointer to the
32e70 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
32e80 63 74 69 6f 6e 5d 20 28 74 68 65 20 31 73 74 20  ction] (the 1st 
32e90 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66  parameter).** of
32ea0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72   the [sqlite3_cr
32eb0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
32ec0 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
32ed0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
32ee0 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74  16()] routines t
32ef0 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a  hat originally.*
32f00 2a 20 72 65 67 69 73 74 65 72 65 64 20 74 68 65  * registered the
32f10 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66   application def
32f20 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  ined function..*
32f30 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c  /.SQLITE_API sql
32f40 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 63 6f  ite3 *sqlite3_co
32f50 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28  ntext_db_handle(
32f60 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
32f70 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
32f80 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75 78  EF: Function Aux
32f90 69 6c 69 61 72 79 20 44 61 74 61 0a 2a 2a 0a 2a  iliary Data.**.*
32fa0 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  * The following 
32fb0 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61  two functions ma
32fc0 79 20 62 65 20 75 73 65 64 20 62 79 20 73 63 61  y be used by sca
32fd0 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  lar SQL function
32fe0 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74  s to.** associat
32ff0 65 20 6d 65 74 61 64 61 74 61 20 77 69 74 68 20  e metadata with 
33000 61 72 67 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e  argument values.
33010 20 49 66 20 74 68 65 20 73 61 6d 65 20 76 61 6c   If the same val
33020 75 65 20 69 73 20 70 61 73 73 65 64 20 74 6f 0a  ue is passed to.
33030 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f  ** multiple invo
33040 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  cations of the s
33050 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ame SQL function
33060 20 64 75 72 69 6e 67 20 71 75 65 72 79 20 65 78   during query ex
33070 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a  ecution, under.*
33080 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d 73 74 61  * some circumsta
33090 6e 63 65 73 20 74 68 65 20 61 73 73 6f 63 69 61  nces the associa
330a0 74 65 64 20 6d 65 74 61 64 61 74 61 20 6d 61 79  ted metadata may
330b0 20 62 65 20 70 72 65 73 65 72 76 65 64 2e 20 54   be preserved. T
330c0 68 69 73 20 6d 61 79 0a 2a 2a 20 62 65 20 75 73  his may.** be us
330d0 65 64 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c  ed, for example,
330e0 20 74 6f 20 61 64 64 20 61 20 72 65 67 75 6c 61   to add a regula
330f0 72 2d 65 78 70 72 65 73 73 69 6f 6e 20 6d 61 74  r-expression mat
33100 63 68 69 6e 67 20 73 63 61 6c 61 72 0a 2a 2a 20  ching scalar.** 
33110 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63 6f  function. The co
33120 6d 70 69 6c 65 64 20 76 65 72 73 69 6f 6e 20 6f  mpiled version o
33130 66 20 74 68 65 20 72 65 67 75 6c 61 72 20 65 78  f the regular ex
33140 70 72 65 73 73 69 6f 6e 20 69 73 20 73 74 6f 72  pression is stor
33150 65 64 20 61 73 0a 2a 2a 20 6d 65 74 61 64 61 74  ed as.** metadat
33160 61 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  a associated wit
33170 68 20 74 68 65 20 53 51 4c 20 76 61 6c 75 65 20  h the SQL value 
33180 70 61 73 73 65 64 20 61 73 20 74 68 65 20 72 65  passed as the re
33190 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e  gular expression
331a0 0a 2a 2a 20 70 61 74 74 65 72 6e 2e 20 20 54 68  .** pattern.  Th
331b0 65 20 63 6f 6d 70 69 6c 65 64 20 72 65 67 75 6c  e compiled regul
331c0 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61  ar expression ca
331d0 6e 20 62 65 20 72 65 75 73 65 64 20 6f 6e 20 6d  n be reused on m
331e0 75 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63  ultiple.** invoc
331f0 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61  ations of the sa
33200 6d 65 20 66 75 6e 63 74 69 6f 6e 20 73 6f 20 74  me function so t
33210 68 61 74 20 74 68 65 20 6f 72 69 67 69 6e 61 6c  hat the original
33220 20 70 61 74 74 65 72 6e 20 73 74 72 69 6e 67 0a   pattern string.
33230 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64  ** does not need
33240 20 74 6f 20 62 65 20 72 65 63 6f 6d 70 69 6c 65   to be recompile
33250 64 20 6f 6e 20 65 61 63 68 20 69 6e 76 6f 63 61  d on each invoca
33260 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  tion..**.** ^The
33270 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78   sqlite3_get_aux
33280 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65  data() interface
33290 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
332a0 65 72 20 74 6f 20 74 68 65 20 6d 65 74 61 64 61  er to the metada
332b0 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64  ta.** associated
332c0 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f   by the sqlite3_
332d0 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 66 75  set_auxdata() fu
332e0 6e 63 74 69 6f 6e 20 77 69 74 68 20 74 68 65 20  nction with the 
332f0 4e 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  Nth argument.** 
33300 76 61 6c 75 65 20 74 6f 20 74 68 65 20 61 70 70  value to the app
33310 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
33320 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 49 66 20 6e   function. ^If n
33330 6f 20 6d 65 74 61 64 61 74 61 20 68 61 73 20 62  o metadata has b
33340 65 65 6e 20 65 76 65 72 0a 2a 2a 20 62 65 65 6e  een ever.** been
33350 20 73 65 74 20 66 6f 72 20 74 68 65 20 4e 74 68   set for the Nth
33360 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65   argument of the
33370 20 66 75 6e 63 74 69 6f 6e 2c 20 6f 72 20 69 66   function, or if
33380 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69   the correspondi
33390 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70  ng.** function p
333a0 61 72 61 6d 65 74 65 72 20 68 61 73 20 63 68 61  arameter has cha
333b0 6e 67 65 64 20 73 69 6e 63 65 20 74 68 65 20 6d  nged since the m
333c0 65 74 61 2d 64 61 74 61 20 77 61 73 20 73 65 74  eta-data was set
333d0 2c 0a 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74 65  ,.** then sqlite
333e0 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_get_auxdata() 
333f0 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70  returns a NULL p
33400 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ointer..**.** ^T
33410 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  he sqlite3_set_a
33420 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61  uxdata() interfa
33430 63 65 20 73 61 76 65 73 20 74 68 65 20 6d 65 74  ce saves the met
33440 61 64 61 74 61 0a 2a 2a 20 70 6f 69 6e 74 65 64  adata.** pointed
33450 20 74 6f 20 62 79 20 69 74 73 20 33 72 64 20 70   to by its 3rd p
33460 61 72 61 6d 65 74 65 72 20 61 73 20 74 68 65 20  arameter as the 
33470 6d 65 74 61 64 61 74 61 20 66 6f 72 20 74 68 65  metadata for the
33480 20 4e 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e   N-th.** argumen
33490 74 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  t of the applica
334a0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
334b0 63 74 69 6f 6e 2e 20 20 53 75 62 73 65 71 75 65  ction.  Subseque
334c0 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73  nt.** calls to s
334d0 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61  qlite3_get_auxda
334e0 74 61 28 29 20 6d 69 67 68 74 20 72 65 74 75 72  ta() might retur
334f0 6e 20 74 68 69 73 20 64 61 74 61 2c 20 69 66 20  n this data, if 
33500 69 74 20 68 61 73 0a 2a 2a 20 6e 6f 74 20 62 65  it has.** not be
33510 65 6e 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a  en destroyed..**
33520 20 5e 49 66 20 69 74 20 69 73 20 6e 6f 74 20 4e   ^If it is not N
33530 55 4c 4c 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c  ULL, SQLite will
33540 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74   invoke the dest
33550 72 75 63 74 6f 72 0a 2a 2a 20 66 75 6e 63 74 69  ructor.** functi
33560 6f 6e 20 67 69 76 65 6e 20 62 79 20 74 68 65 20  on given by the 
33570 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  4th parameter to
33580 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
33590 64 61 74 61 28 29 20 6f 6e 0a 2a 2a 20 74 68 65  data() on.** the
335a0 20 6d 65 74 61 64 61 74 61 20 77 68 65 6e 20 74   metadata when t
335b0 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
335c0 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65   function parame
335d0 74 65 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20 6f  ter changes.** o
335e0 72 20 77 68 65 6e 20 74 68 65 20 53 51 4c 20 73  r when the SQL s
335f0 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 6c 65 74  tatement complet
33600 65 73 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f  es, whichever co
33610 6d 65 73 20 66 69 72 73 74 2e 0a 2a 2a 0a 2a 2a  mes first..**.**
33620 20 53 51 4c 69 74 65 20 69 73 20 66 72 65 65 20   SQLite is free 
33630 74 6f 20 63 61 6c 6c 20 74 68 65 20 64 65 73 74  to call the dest
33640 72 75 63 74 6f 72 20 61 6e 64 20 64 72 6f 70 20  ructor and drop 
33650 6d 65 74 61 64 61 74 61 20 6f 6e 20 61 6e 79 0a  metadata on any.
33660 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  ** parameter of 
33670 61 6e 79 20 66 75 6e 63 74 69 6f 6e 20 61 74 20  any function at 
33680 61 6e 79 20 74 69 6d 65 2e 20 20 5e 54 68 65 20  any time.  ^The 
33690 6f 6e 6c 79 20 67 75 61 72 61 6e 74 65 65 20 69  only guarantee i
336a0 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 64 65  s that.** the de
336b0 73 74 72 75 63 74 6f 72 20 77 69 6c 6c 20 62 65  structor will be
336c0 20 63 61 6c 6c 65 64 20 62 65 66 6f 72 65 20 74   called before t
336d0 68 65 20 6d 65 74 61 64 61 74 61 20 69 73 20 64  he metadata is d
336e0 72 6f 70 70 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ropped..**.** ^(
336f0 49 6e 20 70 72 61 63 74 69 63 65 2c 20 6d 65 74  In practice, met
33700 61 64 61 74 61 20 69 73 20 70 72 65 73 65 72 76  adata is preserv
33710 65 64 20 62 65 74 77 65 65 6e 20 66 75 6e 63 74  ed between funct
33720 69 6f 6e 20 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a  ion calls for.**
33730 20 65 78 70 72 65 73 73 69 6f 6e 73 20 74 68 61   expressions tha
33740 74 20 61 72 65 20 63 6f 6e 73 74 61 6e 74 20 61  t are constant a
33750 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20  t compile time. 
33760 54 68 69 73 20 69 6e 63 6c 75 64 65 73 20 6c 69  This includes li
33770 74 65 72 61 6c 0a 2a 2a 20 76 61 6c 75 65 73 20  teral.** values 
33780 61 6e 64 20 5b 70 61 72 61 6d 65 74 65 72 73 5d  and [parameters]
33790 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  .)^.**.** These 
337a0 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65  routines must be
337b0 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65   called from the
337c0 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20   same thread in 
337d0 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 53 51 4c  which.** the SQL
337e0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e   function is run
337f0 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  ning..*/.SQLITE_
33800 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  API void *sqlite
33810 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 73 71  3_get_auxdata(sq
33820 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
33830 69 6e 74 20 4e 29 3b 0a 53 51 4c 49 54 45 5f 41  int N);.SQLITE_A
33840 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  PI void sqlite3_
33850 73 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69  set_auxdata(sqli
33860 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
33870 74 20 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f 69 64  t N, void*, void
33880 20 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a   (*)(void*));...
33890 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
338a0 43 6f 6e 73 74 61 6e 74 73 20 44 65 66 69 6e 69  Constants Defini
338b0 6e 67 20 53 70 65 63 69 61 6c 20 44 65 73 74 72  ng Special Destr
338c0 75 63 74 6f 72 20 42 65 68 61 76 69 6f 72 0a 2a  uctor Behavior.*
338d0 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20 73  *.** These are s
338e0 70 65 63 69 61 6c 20 76 61 6c 75 65 73 20 66 6f  pecial values fo
338f0 72 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  r the destructor
33900 20 74 68 61 74 20 69 73 20 70 61 73 73 65 64 20   that is passed 
33910 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66 69 6e  in as the.** fin
33920 61 6c 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 72  al argument to r
33930 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71  outines like [sq
33940 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
33950 62 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 20 64  b()].  ^If the d
33960 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 61 72 67  estructor.** arg
33970 75 6d 65 6e 74 20 69 73 20 53 51 4c 49 54 45 5f  ument is SQLITE_
33980 53 54 41 54 49 43 2c 20 69 74 20 6d 65 61 6e 73  STATIC, it means
33990 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e   that the conten
339a0 74 20 70 6f 69 6e 74 65 72 20 69 73 20 63 6f 6e  t pointer is con
339b0 73 74 61 6e 74 0a 2a 2a 20 61 6e 64 20 77 69 6c  stant.** and wil
339c0 6c 20 6e 65 76 65 72 20 63 68 61 6e 67 65 2e 20  l never change. 
339d0 20 49 74 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65   It does not nee
339e0 64 20 74 6f 20 62 65 20 64 65 73 74 72 6f 79 65  d to be destroye
339f0 64 2e 20 20 5e 54 68 65 0a 2a 2a 20 53 51 4c 49  d.  ^The.** SQLI
33a00 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 76 61 6c  TE_TRANSIENT val
33a10 75 65 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  ue means that th
33a20 65 20 63 6f 6e 74 65 6e 74 20 77 69 6c 6c 20 6c  e content will l
33a30 69 6b 65 6c 79 20 63 68 61 6e 67 65 20 69 6e 0a  ikely change in.
33a40 2a 2a 20 74 68 65 20 6e 65 61 72 20 66 75 74 75  ** the near futu
33a50 72 65 20 61 6e 64 20 74 68 61 74 20 53 51 4c 69  re and that SQLi
33a60 74 65 20 73 68 6f 75 6c 64 20 6d 61 6b 65 20 69  te should make i
33a70 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63  ts own private c
33a80 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f  opy of.** the co
33a90 6e 74 65 6e 74 20 62 65 66 6f 72 65 20 72 65 74  ntent before ret
33aa0 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68  urning..**.** Th
33ab0 65 20 74 79 70 65 64 65 66 20 69 73 20 6e 65 63  e typedef is nec
33ac0 65 73 73 61 72 79 20 74 6f 20 77 6f 72 6b 20 61  essary to work a
33ad0 72 6f 75 6e 64 20 70 72 6f 62 6c 65 6d 73 20 69  round problems i
33ae0 6e 20 63 65 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b  n certain.** C++
33af0 20 63 6f 6d 70 69 6c 65 72 73 2e 20 20 53 65 65   compilers.  See
33b00 20 74 69 63 6b 65 74 20 23 32 31 39 31 2e 0a 2a   ticket #2191..*
33b10 2f 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20 28  /.typedef void (
33b20 2a 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63  *sqlite3_destruc
33b30 74 6f 72 5f 74 79 70 65 29 28 76 6f 69 64 2a 29  tor_type)(void*)
33b40 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ;.#define SQLITE
33b50 5f 53 54 41 54 49 43 20 20 20 20 20 20 28 28 73  _STATIC      ((s
33b60 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f  qlite3_destructo
33b70 72 5f 74 79 70 65 29 30 29 0a 23 64 65 66 69 6e  r_type)0).#defin
33b80 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45  e SQLITE_TRANSIE
33b90 4e 54 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64  NT   ((sqlite3_d
33ba0 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 2d  estructor_type)-
33bb0 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  1)../*.** CAPI3R
33bc0 45 46 3a 20 53 65 74 74 69 6e 67 20 54 68 65 20  EF: Setting The 
33bd0 52 65 73 75 6c 74 20 4f 66 20 41 6e 20 53 51 4c  Result Of An SQL
33be0 20 46 75 6e 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20   Function.**.** 
33bf0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
33c00 72 65 20 75 73 65 64 20 62 79 20 74 68 65 20 78  re used by the x
33c10 46 75 6e 63 20 6f 72 20 78 46 69 6e 61 6c 20 63  Func or xFinal c
33c20 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 0a 2a 2a  allbacks that.**
33c30 20 69 6d 70 6c 65 6d 65 6e 74 20 53 51 4c 20 66   implement SQL f
33c40 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67  unctions and agg
33c50 72 65 67 61 74 65 73 2e 20 20 53 65 65 0a 2a 2a  regates.  See.**
33c60 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
33c70 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64  _function()] and
33c80 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
33c90 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a  _function16()].*
33ca0 2a 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  * for additional
33cb0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a   information..**
33cc0 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69  .** These functi
33cd0 6f 6e 73 20 77 6f 72 6b 20 76 65 72 79 20 6d 75  ons work very mu
33ce0 63 68 20 6c 69 6b 65 20 74 68 65 20 5b 70 61 72  ch like the [par
33cf0 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 5d 20  ameter binding] 
33d00 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 66 75 6e  family of.** fun
33d10 63 74 69 6f 6e 73 20 75 73 65 64 20 74 6f 20 62  ctions used to b
33d20 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 68 6f  ind values to ho
33d30 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e  st parameters in
33d40 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
33d50 65 6e 74 73 2e 0a 2a 2a 20 52 65 66 65 72 20 74  ents..** Refer t
33d60 6f 20 74 68 65 20 5b 53 51 4c 20 70 61 72 61 6d  o the [SQL param
33d70 65 74 65 72 5d 20 64 6f 63 75 6d 65 6e 74 61 74  eter] documentat
33d80 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  ion for addition
33d90 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  al information..
33da0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
33db0 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29  e3_result_blob()
33dc0 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20   interface sets 
33dd0 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a  the result from.
33de0 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  ** an applicatio
33df0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
33e00 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 42 4c 4f  on to be the BLO
33e10 42 20 77 68 6f 73 65 20 63 6f 6e 74 65 6e 74 20  B whose content 
33e20 69 73 20 70 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f  is pointed.** to
33e30 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 70   by the second p
33e40 61 72 61 6d 65 74 65 72 20 61 6e 64 20 77 68 69  arameter and whi
33e50 63 68 20 69 73 20 4e 20 62 79 74 65 73 20 6c 6f  ch is N bytes lo
33e60 6e 67 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  ng where N is th
33e70 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d  e.** third param
33e80 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  eter..**.** ^The
33e90 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
33ea0 7a 65 72 6f 62 6c 6f 62 28 29 20 69 6e 74 65 72  zeroblob() inter
33eb0 66 61 63 65 73 20 73 65 74 20 74 68 65 20 72 65  faces set the re
33ec0 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61  sult of.** the a
33ed0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
33ee0 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
33ef0 65 20 61 20 42 4c 4f 42 20 63 6f 6e 74 61 69 6e  e a BLOB contain
33f00 69 6e 67 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a 20  ing all zero.** 
33f10 62 79 74 65 73 20 61 6e 64 20 4e 20 62 79 74 65  bytes and N byte
33f20 73 20 69 6e 20 73 69 7a 65 2c 20 77 68 65 72 65  s in size, where
33f30 20 4e 20 69 73 20 74 68 65 20 76 61 6c 75 65 20   N is the value 
33f40 6f 66 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  of the 2nd param
33f50 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  eter..**.** ^The
33f60 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
33f70 64 6f 75 62 6c 65 28 29 20 69 6e 74 65 72 66 61  double() interfa
33f80 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75  ce sets the resu
33f90 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70  lt from.** an ap
33fa0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
33fb0 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
33fc0 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e   a floating poin
33fd0 74 20 76 61 6c 75 65 20 73 70 65 63 69 66 69 65  t value specifie
33fe0 64 0a 2a 2a 20 62 79 20 69 74 73 20 32 6e 64 20  d.** by its 2nd 
33ff0 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
34000 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
34010 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20  ult_error() and 
34020 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
34030 72 72 6f 72 31 36 28 29 20 66 75 6e 63 74 69 6f  rror16() functio
34040 6e 73 0a 2a 2a 20 63 61 75 73 65 20 74 68 65 20  ns.** cause the 
34050 69 6d 70 6c 65 6d 65 6e 74 65 64 20 53 51 4c 20  implemented SQL 
34060 66 75 6e 63 74 69 6f 6e 20 74 6f 20 74 68 72 6f  function to thro
34070 77 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 2e 0a  w an exception..
34080 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20  ** ^SQLite uses 
34090 74 68 65 20 73 74 72 69 6e 67 20 70 6f 69 6e 74  the string point
340a0 65 64 20 74 6f 20 62 79 20 74 68 65 0a 2a 2a 20  ed to by the.** 
340b0 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66  2nd parameter of
340c0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
340d0 65 72 72 6f 72 28 29 20 6f 72 20 73 71 6c 69 74  error() or sqlit
340e0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
340f0 36 28 29 0a 2a 2a 20 61 73 20 74 68 65 20 74 65  6().** as the te
34100 78 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 6d  xt of an error m
34110 65 73 73 61 67 65 2e 20 20 5e 53 51 4c 69 74 65  essage.  ^SQLite
34120 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20   interprets the 
34130 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65  error.** message
34140 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c   string from sql
34150 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
34160 72 28 29 20 61 73 20 55 54 46 2d 38 2e 20 5e 53  r() as UTF-8. ^S
34170 51 4c 69 74 65 0a 2a 2a 20 69 6e 74 65 72 70 72  QLite.** interpr
34180 65 74 73 20 74 68 65 20 73 74 72 69 6e 67 20 66  ets the string f
34190 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75  rom sqlite3_resu
341a0 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 61 73 20  lt_error16() as 
341b0 55 54 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 65  UTF-16 in native
341c0 0a 2a 2a 20 62 79 74 65 20 6f 72 64 65 72 2e 20  .** byte order. 
341d0 20 5e 49 66 20 74 68 65 20 74 68 69 72 64 20 70   ^If the third p
341e0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
341f0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
34200 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  ().** or sqlite3
34210 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
34220 29 20 69 73 20 6e 65 67 61 74 69 76 65 20 74 68  ) is negative th
34230 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20  en SQLite takes 
34240 61 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20  as the error.** 
34250 6d 65 73 73 61 67 65 20 61 6c 6c 20 74 65 78 74  message all text
34260 20 75 70 20 74 68 72 6f 75 67 68 20 74 68 65 20   up through the 
34270 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61  first zero chara
34280 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  cter..** ^If the
34290 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
342a0 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75   to sqlite3_resu
342b0 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 0a 2a 2a  lt_error() or.**
342c0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
342d0 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e 6f 6e  error16() is non
342e0 2d 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 53  -negative then S
342f0 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68 61 74  QLite takes that
34300 20 6d 61 6e 79 0a 2a 2a 20 62 79 74 65 73 20 28   many.** bytes (
34310 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 29 20  not characters) 
34320 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72  from the 2nd par
34330 61 6d 65 74 65 72 20 61 73 20 74 68 65 20 65 72  ameter as the er
34340 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 20  ror message..** 
34350 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
34360 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20  ult_error() and 
34370 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
34380 72 72 6f 72 31 36 28 29 0a 2a 2a 20 72 6f 75 74  rror16().** rout
34390 69 6e 65 73 20 6d 61 6b 65 20 61 20 70 72 69 76  ines make a priv
343a0 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20  ate copy of the 
343b0 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65  error message te
343c0 78 74 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65  xt before.** the
343d0 79 20 72 65 74 75 72 6e 2e 20 20 48 65 6e 63 65  y return.  Hence
343e0 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 75  , the calling fu
343f0 6e 63 74 69 6f 6e 20 63 61 6e 20 64 65 61 6c 6c  nction can deall
34400 6f 63 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69  ocate or.** modi
34410 66 79 20 74 68 65 20 74 65 78 74 20 61 66 74 65  fy the text afte
34420 72 20 74 68 65 79 20 72 65 74 75 72 6e 20 77 69  r they return wi
34430 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e  thout harm..** ^
34440 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
34450 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 29 20  lt_error_code() 
34460 66 75 6e 63 74 69 6f 6e 20 63 68 61 6e 67 65 73  function changes
34470 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 0a   the error code.
34480 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 53  ** returned by S
34490 51 4c 69 74 65 20 61 73 20 61 20 72 65 73 75 6c  QLite as a resul
344a0 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 69 6e  t of an error in
344b0 20 61 20 66 75 6e 63 74 69 6f 6e 2e 20 20 5e 42   a function.  ^B
344c0 79 20 64 65 66 61 75 6c 74 2c 0a 2a 2a 20 74 68  y default,.** th
344d0 65 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20  e error code is 
344e0 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20 5e  SQLITE_ERROR.  ^
344f0 41 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  A subsequent cal
34500 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73  l to sqlite3_res
34510 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f  ult_error().** o
34520 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  r sqlite3_result
34530 5f 65 72 72 6f 72 31 36 28 29 20 72 65 73 65 74  _error16() reset
34540 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65  s the error code
34550 20 74 6f 20 53 51 4c 49 54 45 5f 45 52 52 4f 52   to SQLITE_ERROR
34560 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
34570 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 6f 6f 62  ite3_result_toob
34580 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 63  ig() interface c
34590 61 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20  auses SQLite to 
345a0 74 68 72 6f 77 20 61 6e 20 65 72 72 6f 72 0a 2a  throw an error.*
345b0 2a 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61  * indicating tha
345c0 74 20 61 20 73 74 72 69 6e 67 20 6f 72 20 42 4c  t a string or BL
345d0 4f 42 20 69 73 20 74 6f 6f 20 6c 6f 6e 67 20 74  OB is too long t
345e0 6f 20 72 65 70 72 65 73 65 6e 74 2e 0a 2a 2a 0a  o represent..**.
345f0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
34600 72 65 73 75 6c 74 5f 6e 6f 6d 65 6d 28 29 20 69  result_nomem() i
34610 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20  nterface causes 
34620 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20  SQLite to throw 
34630 61 6e 20 65 72 72 6f 72 0a 2a 2a 20 69 6e 64 69  an error.** indi
34640 63 61 74 69 6e 67 20 74 68 61 74 20 61 20 6d 65  cating that a me
34650 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
34660 66 61 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  failed..**.** ^T
34670 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
34680 74 5f 69 6e 74 28 29 20 69 6e 74 65 72 66 61 63  t_int() interfac
34690 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72  e sets the retur
346a0 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68  n value.** of th
346b0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
346c0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
346d0 6f 20 62 65 20 74 68 65 20 33 32 2d 62 69 74 20  o be the 32-bit 
346e0 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a  signed integer.*
346f0 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e  * value given in
34700 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e   the 2nd argumen
34710 74 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  t..** ^The sqlit
34720 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28  e3_result_int64(
34730 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
34740 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
34750 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c  e.** of the appl
34760 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
34770 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74  function to be t
34780 68 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  he 64-bit signed
34790 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75   integer.** valu
347a0 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32  e given in the 2
347b0 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  nd argument..**.
347c0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
347d0 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e  result_null() in
347e0 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
347f0 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a   return value.**
34800 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74   of the applicat
34810 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
34820 74 69 6f 6e 20 74 6f 20 62 65 20 4e 55 4c 4c 2e  tion to be NULL.
34830 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
34840 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28  te3_result_text(
34850 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  ), sqlite3_resul
34860 74 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 73  t_text16(),.** s
34870 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
34880 78 74 31 36 6c 65 28 29 2c 20 61 6e 64 20 73 71  xt16le(), and sq
34890 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
348a0 74 31 36 62 65 28 29 20 69 6e 74 65 72 66 61 63  t16be() interfac
348b0 65 73 0a 2a 2a 20 73 65 74 20 74 68 65 20 72 65  es.** set the re
348c0 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
348d0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
348e0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
348f0 6f 20 62 65 0a 2a 2a 20 61 20 74 65 78 74 20 73  o be.** a text s
34900 74 72 69 6e 67 20 77 68 69 63 68 20 69 73 20 72  tring which is r
34910 65 70 72 65 73 65 6e 74 65 64 20 61 73 20 55 54  epresented as UT
34920 46 2d 38 2c 20 55 54 46 2d 31 36 20 6e 61 74 69  F-8, UTF-16 nati
34930 76 65 20 62 79 74 65 20 6f 72 64 65 72 2c 0a 2a  ve byte order,.*
34940 2a 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 20  * UTF-16 little 
34950 65 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31  endian, or UTF-1
34960 36 20 62 69 67 20 65 6e 64 69 61 6e 2c 20 72 65  6 big endian, re
34970 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e  spectively..** ^
34980 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68 65  SQLite takes the
34990 20 74 65 78 74 20 72 65 73 75 6c 74 20 66 72 6f   text result fro
349a0 6d 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  m the applicatio
349b0 6e 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e  n from.** the 2n
349c0 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74  d parameter of t
349d0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
349e0 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63  t_text* interfac
349f0 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33  es..** ^If the 3
34a00 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
34a10 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  the sqlite3_resu
34a20 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61  lt_text* interfa
34a30 63 65 73 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69  ces.** is negati
34a40 76 65 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  ve, then SQLite 
34a50 74 61 6b 65 73 20 72 65 73 75 6c 74 20 74 65 78  takes result tex
34a60 74 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70  t from the 2nd p
34a70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 68 72 6f  arameter.** thro
34a80 75 67 68 20 74 68 65 20 66 69 72 73 74 20 7a 65  ugh the first ze
34a90 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a  ro character..**
34aa0 20 5e 49 66 20 74 68 65 20 33 72 64 20 70 61 72   ^If the 3rd par
34ab0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
34ac0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
34ad0 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  t* interfaces.**
34ae0 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65   is non-negative
34af0 2c 20 74 68 65 6e 20 61 73 20 6d 61 6e 79 20 62  , then as many b
34b00 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63  ytes (not charac
34b10 74 65 72 73 29 20 6f 66 20 74 68 65 20 74 65 78  ters) of the tex
34b20 74 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20  t.** pointed to 
34b30 62 79 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  by the 2nd param
34b40 65 74 65 72 20 61 72 65 20 74 61 6b 65 6e 20 61  eter are taken a
34b50 73 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  s the applicatio
34b60 6e 2d 64 65 66 69 6e 65 64 0a 2a 2a 20 66 75 6e  n-defined.** fun
34b70 63 74 69 6f 6e 20 72 65 73 75 6c 74 2e 0a 2a 2a  ction result..**
34b80 20 5e 49 66 20 74 68 65 20 34 74 68 20 70 61 72   ^If the 4th par
34b90 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
34ba0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
34bb0 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  t* interfaces.**
34bc0 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75   or sqlite3_resu
34bd0 6c 74 5f 62 6c 6f 62 20 69 73 20 61 20 6e 6f 6e  lt_blob is a non
34be0 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74  -NULL pointer, t
34bf0 68 65 6e 20 53 51 4c 69 74 65 20 63 61 6c 6c 73  hen SQLite calls
34c00 20 74 68 61 74 0a 2a 2a 20 66 75 6e 63 74 69 6f   that.** functio
34c10 6e 20 61 73 20 74 68 65 20 64 65 73 74 72 75 63  n as the destruc
34c20 74 6f 72 20 6f 6e 20 74 68 65 20 74 65 78 74 20  tor on the text 
34c30 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 20 77  or BLOB result w
34c40 68 65 6e 20 69 74 20 68 61 73 0a 2a 2a 20 66 69  hen it has.** fi
34c50 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 61  nished using tha
34c60 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66  t result..** ^If
34c70 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74   the 4th paramet
34c80 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  er to the sqlite
34c90 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69  3_result_text* i
34ca0 6e 74 65 72 66 61 63 65 73 20 6f 72 20 74 6f 0a  nterfaces or to.
34cb0 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  ** sqlite3_resul
34cc0 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70  t_blob is the sp
34cd0 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53  ecial constant S
34ce0 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 74 68  QLITE_STATIC, th
34cf0 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 73 73  en SQLite.** ass
34d00 75 6d 65 73 20 74 68 61 74 20 74 68 65 20 74 65  umes that the te
34d10 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c  xt or BLOB resul
34d20 74 20 69 73 20 69 6e 20 63 6f 6e 73 74 61 6e 74  t is in constant
34d30 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20   space and does 
34d40 6e 6f 74 0a 2a 2a 20 63 6f 70 79 20 74 68 65 20  not.** copy the 
34d50 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 70  content of the p
34d60 61 72 61 6d 65 74 65 72 20 6e 6f 72 20 63 61 6c  arameter nor cal
34d70 6c 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 6f  l a destructor o
34d80 6e 20 74 68 65 20 63 6f 6e 74 65 6e 74 0a 2a 2a  n the content.**
34d90 20 77 68 65 6e 20 69 74 20 68 61 73 20 66 69 6e   when it has fin
34da0 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 61 74  ished using that
34db0 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20   result..** ^If 
34dc0 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65  the 4th paramete
34dd0 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
34de0 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e  _result_text* in
34df0 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73  terfaces.** or s
34e00 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
34e10 6f 62 20 69 73 20 74 68 65 20 73 70 65 63 69 61  ob is the specia
34e20 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54  l constant SQLIT
34e30 45 5f 54 52 41 4e 53 49 45 4e 54 0a 2a 2a 20 74  E_TRANSIENT.** t
34e40 68 65 6e 20 53 51 4c 69 74 65 20 6d 61 6b 65 73  hen SQLite makes
34e50 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 72   a copy of the r
34e60 65 73 75 6c 74 20 69 6e 74 6f 20 73 70 61 63 65  esult into space
34e70 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 0a 2a   obtained from.*
34e80 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  * from [sqlite3_
34e90 6d 61 6c 6c 6f 63 28 29 5d 20 62 65 66 6f 72 65  malloc()] before
34ea0 20 69 74 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a   it returns..**.
34eb0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
34ec0 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69  result_value() i
34ed0 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68  nterface sets th
34ee0 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74  e result of.** t
34ef0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
34f00 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
34f10 74 6f 20 62 65 20 61 20 63 6f 70 79 20 74 68 65  to be a copy the
34f20 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64  .** [unprotected
34f30 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
34f40 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69 65 64  object specified
34f50 20 62 79 20 74 68 65 20 32 6e 64 20 70 61 72 61   by the 2nd para
34f60 6d 65 74 65 72 2e 20 20 5e 54 68 65 0a 2a 2a 20  meter.  ^The.** 
34f70 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
34f80 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63 65  alue() interface
34f90 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66   makes a copy of
34fa0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   the [sqlite3_va
34fb0 6c 75 65 5d 0a 2a 2a 20 73 6f 20 74 68 61 74 20  lue].** so that 
34fc0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  the [sqlite3_val
34fd0 75 65 5d 20 73 70 65 63 69 66 69 65 64 20 69 6e  ue] specified in
34fe0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d   the parameter m
34ff0 61 79 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20  ay change or.** 
35000 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 61  be deallocated a
35010 66 74 65 72 20 73 71 6c 69 74 65 33 5f 72 65 73  fter sqlite3_res
35020 75 6c 74 5f 76 61 6c 75 65 28 29 20 72 65 74 75  ult_value() retu
35030 72 6e 73 20 77 69 74 68 6f 75 74 20 68 61 72 6d  rns without harm
35040 2e 0a 2a 2a 20 5e 41 20 5b 70 72 6f 74 65 63 74  ..** ^A [protect
35050 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
35060 5d 20 6f 62 6a 65 63 74 20 6d 61 79 20 61 6c 77  ] object may alw
35070 61 79 73 20 62 65 20 75 73 65 64 20 77 68 65 72  ays be used wher
35080 65 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65  e an.** [unprote
35090 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
350a0 75 65 5d 20 6f 62 6a 65 63 74 20 69 73 20 72 65  ue] object is re
350b0 71 75 69 72 65 64 2c 20 73 6f 20 65 69 74 68 65  quired, so eithe
350c0 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20 5b 73 71  r.** kind of [sq
350d0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
350e0 65 63 74 20 63 61 6e 20 62 65 20 75 73 65 64 20  ect can be used 
350f0 77 69 74 68 20 74 68 69 73 20 69 6e 74 65 72 66  with this interf
35100 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  ace..**.** If th
35110 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
35120 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 77 69 74   called from wit
35130 68 69 6e 20 74 68 65 20 64 69 66 66 65 72 65 6e  hin the differen
35140 74 20 74 68 72 65 61 64 0a 2a 2a 20 74 68 61 6e  t thread.** than
35150 20 74 68 65 20 6f 6e 65 20 63 6f 6e 74 61 69 6e   the one contain
35160 69 6e 67 20 74 68 65 20 61 70 70 6c 69 63 61 74  ing the applicat
35170 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
35180 74 69 6f 6e 20 74 68 61 74 20 72 65 63 65 69 76  tion that receiv
35190 65 64 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74  ed.** the [sqlit
351a0 65 33 5f 63 6f 6e 74 65 78 74 5d 20 70 6f 69 6e  e3_context] poin
351b0 74 65 72 2c 20 74 68 65 20 72 65 73 75 6c 74 73  ter, the results
351c0 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a   are undefined..
351d0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  */.SQLITE_API vo
351e0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
351f0 74 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63  t_blob(sqlite3_c
35200 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76  ontext*, const v
35210 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28  oid*, int, void(
35220 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49  *)(void*));.SQLI
35230 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69  TE_API void sqli
35240 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c  te3_result_doubl
35250 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e(sqlite3_contex
35260 74 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a 53 51 4c  t*, double);.SQL
35270 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c  ITE_API void sql
35280 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
35290 72 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  r(sqlite3_contex
352a0 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c  t*, const char*,
352b0 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50   int);.SQLITE_AP
352c0 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  I void sqlite3_r
352d0 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 73 71  esult_error16(sq
352e0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
352f0 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
35300 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  );.SQLITE_API vo
35310 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
35320 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28 73  t_error_toobig(s
35330 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
35340 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  ;.SQLITE_API voi
35350 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
35360 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c  _error_nomem(sql
35370 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a  ite3_context*);.
35380 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
35390 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
353a0 72 72 6f 72 5f 63 6f 64 65 28 73 71 6c 69 74 65  rror_code(sqlite
353b0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29  3_context*, int)
353c0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  ;.SQLITE_API voi
353d0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
353e0 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e  _int(sqlite3_con
353f0 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c  text*, int);.SQL
35400 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c  ITE_API void sql
35410 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36  ite3_result_int6
35420 34 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  4(sqlite3_contex
35430 74 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  t*, sqlite3_int6
35440 34 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  4);.SQLITE_API v
35450 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
35460 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f  lt_null(sqlite3_
35470 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54  context*);.SQLIT
35480 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74  E_API void sqlit
35490 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 73  e3_result_text(s
354a0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
354b0 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e   const char*, in
354c0 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  t, void(*)(void*
354d0 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  ));.SQLITE_API v
354e0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
354f0 6c 74 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65  lt_text16(sqlite
35500 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
35510 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f  t void*, int, vo
35520 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53  id(*)(void*));.S
35530 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73  QLITE_API void s
35540 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
35550 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 63  xt16le(sqlite3_c
35560 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76  ontext*, const v
35570 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a  oid*, int,void(*
35580 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54  )(void*));.SQLIT
35590 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74  E_API void sqlit
355a0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
355b0 62 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  be(sqlite3_conte
355c0 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  xt*, const void*
355d0 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f  , int,void(*)(vo
355e0 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50  id*));.SQLITE_AP
355f0 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  I void sqlite3_r
35600 65 73 75 6c 74 5f 76 61 6c 75 65 28 73 71 6c 69  esult_value(sqli
35610 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71  te3_context*, sq
35620 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53  lite3_value*);.S
35630 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73  QLITE_API void s
35640 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65  qlite3_result_ze
35650 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63  roblob(sqlite3_c
35660 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 29 3b  ontext*, int n);
35670 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
35680 3a 20 44 65 66 69 6e 65 20 4e 65 77 20 43 6f 6c  : Define New Col
35690 6c 61 74 69 6e 67 20 53 65 71 75 65 6e 63 65 73  lating Sequences
356a0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75  .**.** ^These fu
356b0 6e 63 74 69 6f 6e 73 20 61 64 64 2c 20 72 65 6d  nctions add, rem
356c0 6f 76 65 2c 20 6f 72 20 6d 6f 64 69 66 79 20 61  ove, or modify a
356d0 20 5b 63 6f 6c 6c 61 74 69 6f 6e 5d 20 61 73 73   [collation] ass
356e0 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68 20  ociated.** with 
356f0 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
35700 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66  nnection] specif
35710 69 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74  ied as the first
35720 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a   argument..**.**
35730 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68   ^The name of th
35740 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 20 61  e collation is a
35750 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a   UTF-8 string.**
35760 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65   for sqlite3_cre
35770 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 20  ate_collation() 
35780 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 72 65 61  and sqlite3_crea
35790 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
357a0 29 0a 2a 2a 20 61 6e 64 20 61 20 55 54 46 2d 31  ).** and a UTF-1
357b0 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69  6 string in nati
357c0 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 66 6f  ve byte order fo
357d0 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  r sqlite3_create
357e0 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e 0a  _collation16()..
357f0 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6f 6e 20 6e 61  ** ^Collation na
35800 6d 65 73 20 74 68 61 74 20 63 6f 6d 70 61 72 65  mes that compare
35810 20 65 71 75 61 6c 20 61 63 63 6f 72 64 69 6e 67   equal according
35820 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 72   to [sqlite3_str
35830 6e 69 63 6d 70 28 29 5d 20 61 72 65 0a 2a 2a 20  nicmp()] are.** 
35840 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 20 62 65  considered to be
35850 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 2e 0a   the same name..
35860 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 74 68 69 72  **.** ^(The thir
35870 64 20 61 72 67 75 6d 65 6e 74 20 28 65 54 65 78  d argument (eTex
35880 74 52 65 70 29 20 6d 75 73 74 20 62 65 20 6f 6e  tRep) must be on
35890 65 20 6f 66 20 74 68 65 20 63 6f 6e 73 74 61 6e  e of the constan
358a0 74 73 3a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  ts:.** <ul>.** <
358b0 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 38  li> [SQLITE_UTF8
358c0 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  ],.** <li> [SQLI
358d0 54 45 5f 55 54 46 31 36 4c 45 5d 2c 0a 2a 2a 20  TE_UTF16LE],.** 
358e0 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46  <li> [SQLITE_UTF
358f0 31 36 42 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  16BE],.** <li> [
35900 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 2c 20 6f  SQLITE_UTF16], o
35910 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  r.** <li> [SQLIT
35920 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d  E_UTF16_ALIGNED]
35930 2e 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20  ..** </ul>)^.** 
35940 5e 54 68 65 20 65 54 65 78 74 52 65 70 20 61 72  ^The eTextRep ar
35950 67 75 6d 65 6e 74 20 64 65 74 65 72 6d 69 6e 65  gument determine
35960 73 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 6f  s the encoding o
35970 66 20 73 74 72 69 6e 67 73 20 70 61 73 73 65 64  f strings passed
35980 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61  .** to the colla
35990 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61  ting function ca
359a0 6c 6c 62 61 63 6b 2c 20 78 43 61 6c 6c 62 61 63  llback, xCallbac
359b0 6b 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  k..** ^The [SQLI
359c0 54 45 5f 55 54 46 31 36 5d 20 61 6e 64 20 5b 53  TE_UTF16] and [S
359d0 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47  QLITE_UTF16_ALIG
359e0 4e 45 44 5d 20 76 61 6c 75 65 73 20 66 6f 72 20  NED] values for 
359f0 65 54 65 78 74 52 65 70 0a 2a 2a 20 66 6f 72 63  eTextRep.** forc
35a00 65 20 73 74 72 69 6e 67 73 20 74 6f 20 62 65 20  e strings to be 
35a10 55 54 46 31 36 20 77 69 74 68 20 6e 61 74 69 76  UTF16 with nativ
35a20 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a  e byte order..**
35a30 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 55 54   ^The [SQLITE_UT
35a40 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20 76 61 6c  F16_ALIGNED] val
35a50 75 65 20 66 6f 72 20 65 54 65 78 74 52 65 70 20  ue for eTextRep 
35a60 66 6f 72 63 65 73 20 73 74 72 69 6e 67 73 20 74  forces strings t
35a70 6f 20 62 65 67 69 6e 0a 2a 2a 20 6f 6e 20 61 6e  o begin.** on an
35a80 20 65 76 65 6e 20 62 79 74 65 20 61 64 64 72 65   even byte addre
35a90 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  ss..**.** ^The f
35aa0 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c 20  ourth argument, 
35ab0 70 41 72 67 2c 20 69 73 20 61 6e 20 61 70 70 6c  pArg, is an appl
35ac0 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69  ication data poi
35ad0 6e 74 65 72 20 74 68 61 74 20 69 73 20 70 61 73  nter that is pas
35ae0 73 65 64 0a 2a 2a 20 74 68 72 6f 75 67 68 20 61  sed.** through a
35af0 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  s the first argu
35b00 6d 65 6e 74 20 74 6f 20 74 68 65 20 63 6f 6c 6c  ment to the coll
35b10 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63  ating function c
35b20 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e  allback..**.** ^
35b30 54 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65  The fifth argume
35b40 6e 74 2c 20 78 43 61 6c 6c 62 61 63 6b 2c 20 69  nt, xCallback, i
35b50 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
35b60 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  he collating fun
35b70 63 74 69 6f 6e 2e 0a 2a 2a 20 5e 4d 75 6c 74 69  ction..** ^Multi
35b80 70 6c 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  ple collating fu
35b90 6e 63 74 69 6f 6e 73 20 63 61 6e 20 62 65 20 72  nctions can be r
35ba0 65 67 69 73 74 65 72 65 64 20 75 73 69 6e 67 20  egistered using 
35bb0 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 75  the same name bu
35bc0 74 0a 2a 2a 20 77 69 74 68 20 64 69 66 66 65 72  t.** with differ
35bd0 65 6e 74 20 65 54 65 78 74 52 65 70 20 70 61 72  ent eTextRep par
35be0 61 6d 65 74 65 72 73 20 61 6e 64 20 53 51 4c 69  ameters and SQLi
35bf0 74 65 20 77 69 6c 6c 20 75 73 65 20 77 68 69 63  te will use whic
35c00 68 65 76 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f  hever.** functio
35c10 6e 20 72 65 71 75 69 72 65 73 20 74 68 65 20 6c  n requires the l
35c20 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64  east amount of d
35c30 61 74 61 20 74 72 61 6e 73 66 6f 72 6d 61 74 69  ata transformati
35c40 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 78  on..** ^If the x
35c50 43 61 6c 6c 62 61 63 6b 20 61 72 67 75 6d 65 6e  Callback argumen
35c60 74 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74  t is NULL then t
35c70 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  he collating fun
35c80 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 64 65 6c 65  ction is.** dele
35c90 74 65 64 2e 20 20 5e 57 68 65 6e 20 61 6c 6c 20  ted.  ^When all 
35ca0 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
35cb0 6f 6e 73 20 68 61 76 69 6e 67 20 74 68 65 20 73  ons having the s
35cc0 61 6d 65 20 6e 61 6d 65 20 61 72 65 20 64 65 6c  ame name are del
35cd0 65 74 65 64 2c 0a 2a 2a 20 74 68 61 74 20 63 6f  eted,.** that co
35ce0 6c 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 20 6c 6f  llation is no lo
35cf0 6e 67 65 72 20 75 73 61 62 6c 65 2e 0a 2a 2a 0a  nger usable..**.
35d00 2a 2a 20 5e 54 68 65 20 63 6f 6c 6c 61 74 69 6e  ** ^The collatin
35d10 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62  g function callb
35d20 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77  ack is invoked w
35d30 69 74 68 20 61 20 63 6f 70 79 20 6f 66 20 74 68  ith a copy of th
35d40 65 20 70 41 72 67 20 0a 2a 2a 20 61 70 70 6c 69  e pArg .** appli
35d50 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e  cation data poin
35d60 74 65 72 20 61 6e 64 20 77 69 74 68 20 74 77 6f  ter and with two
35d70 20 73 74 72 69 6e 67 73 20 69 6e 20 74 68 65 20   strings in the 
35d80 65 6e 63 6f 64 69 6e 67 20 73 70 65 63 69 66 69  encoding specifi
35d90 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 65 54 65  ed.** by the eTe
35da0 78 74 52 65 70 20 61 72 67 75 6d 65 6e 74 2e 20  xtRep argument. 
35db0 20 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66   The collating f
35dc0 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 72 65 74  unction must ret
35dd0 75 72 6e 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65  urn an.** intege
35de0 72 20 74 68 61 74 20 69 73 20 6e 65 67 61 74 69  r that is negati
35df0 76 65 2c 20 7a 65 72 6f 2c 20 6f 72 20 70 6f 73  ve, zero, or pos
35e00 69 74 69 76 65 0a 2a 2a 20 69 66 20 74 68 65 20  itive.** if the 
35e10 66 69 72 73 74 20 73 74 72 69 6e 67 20 69 73 20  first string is 
35e20 6c 65 73 73 20 74 68 61 6e 2c 20 65 71 75 61 6c  less than, equal
35e30 20 74 6f 2c 20 6f 72 20 67 72 65 61 74 65 72 20   to, or greater 
35e40 74 68 61 6e 20 74 68 65 20 73 65 63 6f 6e 64 2c  than the second,
35e50 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79  .** respectively
35e60 2e 20 20 41 20 63 6f 6c 6c 61 74 69 6e 67 20 66  .  A collating f
35e70 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 61 6c 77  unction must alw
35e80 61 79 73 20 72 65 74 75 72 6e 20 74 68 65 20 73  ays return the s
35e90 61 6d 65 20 61 6e 73 77 65 72 0a 2a 2a 20 67 69  ame answer.** gi
35ea0 76 65 6e 20 74 68 65 20 73 61 6d 65 20 69 6e 70  ven the same inp
35eb0 75 74 73 2e 20 20 49 66 20 74 77 6f 20 6f 72 20  uts.  If two or 
35ec0 6d 6f 72 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66  more collating f
35ed0 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 72 65 67  unctions are reg
35ee0 69 73 74 65 72 65 64 0a 2a 2a 20 74 6f 20 74 68  istered.** to th
35ef0 65 20 73 61 6d 65 20 63 6f 6c 6c 61 74 69 6f 6e  e same collation
35f00 20 6e 61 6d 65 20 28 75 73 69 6e 67 20 64 69 66   name (using dif
35f10 66 65 72 65 6e 74 20 65 54 65 78 74 52 65 70 20  ferent eTextRep 
35f20 76 61 6c 75 65 73 29 20 74 68 65 6e 20 61 6c 6c  values) then all
35f30 0a 2a 2a 20 6d 75 73 74 20 67 69 76 65 20 61 6e  .** must give an
35f40 20 65 71 75 69 76 61 6c 65 6e 74 20 61 6e 73 77   equivalent answ
35f50 65 72 20 77 68 65 6e 20 69 6e 76 6f 6b 65 64 20  er when invoked 
35f60 77 69 74 68 20 65 71 75 69 76 61 6c 65 6e 74 20  with equivalent 
35f70 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 20  strings..** The 
35f80 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
35f90 6f 6e 20 6d 75 73 74 20 6f 62 65 79 20 74 68 65  on must obey the
35fa0 20 66 6f 6c 6c 6f 77 69 6e 67 20 70 72 6f 70 65   following prope
35fb0 72 74 69 65 73 20 66 6f 72 20 61 6c 6c 0a 2a 2a  rties for all.**
35fc0 20 73 74 72 69 6e 67 73 20 41 2c 20 42 2c 20 61   strings A, B, a
35fd0 6e 64 20 43 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e  nd C:.**.** <ol>
35fe0 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 3d 3d 42  .** <li> If A==B
35ff0 20 74 68 65 6e 20 42 3d 3d 41 2e 0a 2a 2a 20 3c   then B==A..** <
36000 6c 69 3e 20 49 66 20 41 3d 3d 42 20 61 6e 64 20  li> If A==B and 
36010 42 3d 3d 43 20 74 68 65 6e 20 41 3d 3d 43 2e 0a  B==C then A==C..
36020 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 26 6c 74 3b  ** <li> If A&lt;
36030 42 20 54 48 45 4e 20 42 26 67 74 3b 41 2e 0a 2a  B THEN B&gt;A..*
36040 2a 20 3c 6c 69 3e 20 49 66 20 41 26 6c 74 3b 42  * <li> If A&lt;B
36050 20 61 6e 64 20 42 26 6c 74 3b 43 20 74 68 65 6e   and B&lt;C then
36060 20 41 26 6c 74 3b 43 2e 0a 2a 2a 20 3c 2f 6f 6c   A&lt;C..** </ol
36070 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 63 6f 6c  >.**.** If a col
36080 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  lating function 
36090 66 61 69 6c 73 20 61 6e 79 20 6f 66 20 74 68 65  fails any of the
360a0 20 61 62 6f 76 65 20 63 6f 6e 73 74 72 61 69 6e   above constrain
360b0 74 73 20 61 6e 64 20 74 68 61 74 0a 2a 2a 20 63  ts and that.** c
360c0 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
360d0 6e 20 69 73 20 20 72 65 67 69 73 74 65 72 65 64  n is  registered
360e0 20 61 6e 64 20 75 73 65 64 2c 20 74 68 65 6e 20   and used, then 
360f0 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20  the behavior of 
36100 53 51 4c 69 74 65 0a 2a 2a 20 69 73 20 75 6e 64  SQLite.** is und
36110 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  efined..**.** ^T
36120 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  he sqlite3_creat
36130 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29  e_collation_v2()
36140 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69   works like sqli
36150 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
36160 74 69 6f 6e 28 29 0a 2a 2a 20 77 69 74 68 20 74  tion().** with t
36170 68 65 20 61 64 64 69 74 69 6f 6e 20 74 68 61 74  he addition that
36180 20 74 68 65 20 78 44 65 73 74 72 6f 79 20 63 61   the xDestroy ca
36190 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
361a0 64 20 6f 6e 20 70 41 72 67 20 77 68 65 6e 0a 2a  d on pArg when.*
361b0 2a 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20  * the collating 
361c0 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 65 6c 65  function is dele
361d0 74 65 64 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69  ted..** ^Collati
361e0 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65  ng functions are
361f0 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 74 68   deleted when th
36200 65 79 20 61 72 65 20 6f 76 65 72 72 69 64 64 65  ey are overridde
36210 6e 20 62 79 20 6c 61 74 65 72 0a 2a 2a 20 63 61  n by later.** ca
36220 6c 6c 73 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61  lls to the colla
36230 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 66 75  tion creation fu
36240 6e 63 74 69 6f 6e 73 20 6f 72 20 77 68 65 6e 20  nctions or when 
36250 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  the.** [database
36260 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20   connection] is 
36270 63 6c 6f 73 65 64 20 75 73 69 6e 67 20 5b 73 71  closed using [sq
36280 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a  lite3_close()]..
36290 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 44 65 73 74  **.** ^The xDest
362a0 72 6f 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  roy callback is 
362b0 3c 75 3e 6e 6f 74 3c 2f 75 3e 20 63 61 6c 6c 65  <u>not</u> calle
362c0 64 20 69 66 20 74 68 65 20 0a 2a 2a 20 73 71 6c  d if the .** sql
362d0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
362e0 61 74 69 6f 6e 5f 76 32 28 29 20 66 75 6e 63 74  ation_v2() funct
362f0 69 6f 6e 20 66 61 69 6c 73 2e 20 20 41 70 70 6c  ion fails.  Appl
36300 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 69 6e  ications that in
36310 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  voke.** sqlite3_
36320 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
36330 5f 76 32 28 29 20 77 69 74 68 20 61 20 6e 6f 6e  _v2() with a non
36340 2d 4e 55 4c 4c 20 78 44 65 73 74 72 6f 79 20 61  -NULL xDestroy a
36350 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 0a  rgument should .
36360 2a 2a 20 63 68 65 63 6b 20 74 68 65 20 72 65 74  ** check the ret
36370 75 72 6e 20 63 6f 64 65 20 61 6e 64 20 64 69 73  urn code and dis
36380 70 6f 73 65 20 6f 66 20 74 68 65 20 61 70 70 6c  pose of the appl
36390 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69  ication data poi
363a0 6e 74 65 72 0a 2a 2a 20 74 68 65 6d 73 65 6c 76  nter.** themselv
363b0 65 73 20 72 61 74 68 65 72 20 74 68 61 6e 20 65  es rather than e
363c0 78 70 65 63 74 69 6e 67 20 53 51 4c 69 74 65 20  xpecting SQLite 
363d0 74 6f 20 64 65 61 6c 20 77 69 74 68 20 69 74 20  to deal with it 
363e0 66 6f 72 20 74 68 65 6d 2e 0a 2a 2a 20 54 68 69  for them..** Thi
363f0 73 20 69 73 20 64 69 66 66 65 72 65 6e 74 20 66  s is different f
36400 72 6f 6d 20 65 76 65 72 79 20 6f 74 68 65 72 20  rom every other 
36410 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
36420 2e 20 20 54 68 65 20 69 6e 63 6f 6e 73 69 73 74  .  The inconsist
36430 65 6e 63 79 20 0a 2a 2a 20 69 73 20 75 6e 66 6f  ency .** is unfo
36440 72 74 75 6e 61 74 65 20 62 75 74 20 63 61 6e 6e  rtunate but cann
36450 6f 74 20 62 65 20 63 68 61 6e 67 65 64 20 77 69  ot be changed wi
36460 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 62  thout breaking b
36470 61 63 6b 77 61 72 64 73 20 0a 2a 2a 20 63 6f 6d  ackwards .** com
36480 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a  patibility..**.*
36490 2a 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b 73 71  * See also:  [sq
364a0 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
364b0 6e 65 65 64 65 64 28 29 5d 20 61 6e 64 20 5b 73  needed()] and [s
364c0 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
364d0 5f 6e 65 65 64 65 64 31 36 28 29 5d 2e 0a 2a 2f  _needed16()]..*/
364e0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
364f0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
36500 6f 6c 6c 61 74 69 6f 6e 28 0a 20 20 73 71 6c 69  ollation(.  sqli
36510 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63  te3*, .  const c
36520 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69  har *zName, .  i
36530 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20  nt eTextRep, .  
36540 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20 69 6e  void *pArg,.  in
36550 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69  t(*xCompare)(voi
36560 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69  d*,int,const voi
36570 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69  d*,int,const voi
36580 64 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  d*).);.SQLITE_AP
36590 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72  I int sqlite3_cr
365a0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
365b0 32 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a  2(.  sqlite3*, .
365c0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e    const char *zN
365d0 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78  ame, .  int eTex
365e0 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70  tRep, .  void *p
365f0 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d  Arg,.  int(*xCom
36600 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c  pare)(void*,int,
36610 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c  const void*,int,
36620 63 6f 6e 73 74 20 76 6f 69 64 2a 29 2c 0a 20 20  const void*),.  
36630 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28  void(*xDestroy)(
36640 76 6f 69 64 2a 29 0a 29 3b 0a 53 51 4c 49 54 45  void*).);.SQLITE
36650 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
36660 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
36670 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  n16(.  sqlite3*,
36680 20 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a   .  const void *
36690 7a 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 65 54 65  zName,.  int eTe
366a0 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a  xtRep, .  void *
366b0 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f  pArg,.  int(*xCo
366c0 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74  mpare)(void*,int
366d0 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74  ,const void*,int
366e0 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b  ,const void*).);
366f0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
36700 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 4e 65 65 64  : Collation Need
36710 65 64 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a  ed Callbacks.**.
36720 2a 2a 20 5e 54 6f 20 61 76 6f 69 64 20 68 61 76  ** ^To avoid hav
36730 69 6e 67 20 74 6f 20 72 65 67 69 73 74 65 72 20  ing to register 
36740 61 6c 6c 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65  all collation se
36750 71 75 65 6e 63 65 73 20 62 65 66 6f 72 65 20 61  quences before a
36760 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 61 6e   database.** can
36770 20 62 65 20 75 73 65 64 2c 20 61 20 73 69 6e 67   be used, a sing
36780 6c 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  le callback func
36790 74 69 6f 6e 20 6d 61 79 20 62 65 20 72 65 67 69  tion may be regi
367a0 73 74 65 72 65 64 20 77 69 74 68 20 74 68 65 0a  stered with the.
367b0 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
367c0 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 62 65 20 69  nection] to be i
367d0 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20  nvoked whenever 
367e0 61 6e 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c  an undefined col
367f0 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e  lation.** sequen
36800 63 65 20 69 73 20 72 65 71 75 69 72 65 64 2e 0a  ce is required..
36810 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 75  **.** ^If the fu
36820 6e 63 74 69 6f 6e 20 69 73 20 72 65 67 69 73 74  nction is regist
36830 65 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 73  ered using the s
36840 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
36850 5f 6e 65 65 64 65 64 28 29 20 41 50 49 2c 0a 2a  _needed() API,.*
36860 2a 20 74 68 65 6e 20 69 74 20 69 73 20 70 61 73  * then it is pas
36870 73 65 64 20 74 68 65 20 6e 61 6d 65 73 20 6f 66  sed the names of
36880 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61   undefined colla
36890 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 61  tion sequences a
368a0 73 20 73 74 72 69 6e 67 73 0a 2a 2a 20 65 6e 63  s strings.** enc
368b0 6f 64 65 64 20 69 6e 20 55 54 46 2d 38 2e 20 5e  oded in UTF-8. ^
368c0 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  If sqlite3_colla
368d0 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 20  tion_needed16() 
368e0 69 73 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 20  is used,.** the 
368f0 6e 61 6d 65 73 20 61 72 65 20 70 61 73 73 65 64  names are passed
36900 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6d 61   as UTF-16 in ma
36910 63 68 69 6e 65 20 6e 61 74 69 76 65 20 62 79 74  chine native byt
36920 65 20 6f 72 64 65 72 2e 0a 2a 2a 20 5e 41 20 63  e order..** ^A c
36930 61 6c 6c 20 74 6f 20 65 69 74 68 65 72 20 66 75  all to either fu
36940 6e 63 74 69 6f 6e 20 72 65 70 6c 61 63 65 73 20  nction replaces 
36950 74 68 65 20 65 78 69 73 74 69 6e 67 20 63 6f 6c  the existing col
36960 6c 61 74 69 6f 6e 2d 6e 65 65 64 65 64 20 63 61  lation-needed ca
36970 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 28  llback..**.** ^(
36980 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63  When the callbac
36990 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 74 68  k is invoked, th
369a0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
369b0 20 70 61 73 73 65 64 20 69 73 20 61 20 63 6f 70   passed is a cop
369c0 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 65 63 6f  y.** of the seco
369d0 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  nd argument to s
369e0 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
369f0 5f 6e 65 65 64 65 64 28 29 20 6f 72 0a 2a 2a 20  _needed() or.** 
36a00 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
36a10 6e 5f 6e 65 65 64 65 64 31 36 28 29 2e 20 20 54  n_needed16().  T
36a20 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
36a30 6e 74 20 69 73 20 74 68 65 20 64 61 74 61 62 61  nt is the databa
36a40 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  se.** connection
36a50 2e 20 20 54 68 65 20 74 68 69 72 64 20 61 72 67  .  The third arg
36a60 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20  ument is one of 
36a70 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b  [SQLITE_UTF8], [
36a80 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c  SQLITE_UTF16BE],
36a90 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55  .** or [SQLITE_U
36aa0 54 46 31 36 4c 45 5d 2c 20 69 6e 64 69 63 61 74  TF16LE], indicat
36ab0 69 6e 67 20 74 68 65 20 6d 6f 73 74 20 64 65 73  ing the most des
36ac0 69 72 61 62 6c 65 20 66 6f 72 6d 20 6f 66 20 74  irable form of t
36ad0 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20  he collation.** 
36ae0 73 65 71 75 65 6e 63 65 20 66 75 6e 63 74 69 6f  sequence functio
36af0 6e 20 72 65 71 75 69 72 65 64 2e 20 20 54 68 65  n required.  The
36b00 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
36b10 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  r is the name of
36b20 20 74 68 65 0a 2a 2a 20 72 65 71 75 69 72 65 64   the.** required
36b30 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   collation seque
36b40 6e 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65  nce.)^.**.** The
36b50 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
36b60 6f 6e 20 73 68 6f 75 6c 64 20 72 65 67 69 73 74  on should regist
36b70 65 72 20 74 68 65 20 64 65 73 69 72 65 64 20 63  er the desired c
36b80 6f 6c 6c 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a  ollation using.*
36b90 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  * [sqlite3_creat
36ba0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 5d 2c 20  e_collation()], 
36bb0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
36bc0 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 5d 2c 20  collation16()], 
36bd0 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  or.** [sqlite3_c
36be0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
36bf0 76 32 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45  v2()]..*/.SQLITE
36c00 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
36c10 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
36c20 64 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a  d(.  sqlite3*, .
36c30 20 20 76 6f 69 64 2a 2c 20 0a 20 20 76 6f 69 64    void*, .  void
36c40 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65  (*)(void*,sqlite
36c50 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 70 2c  3*,int eTextRep,
36c60 63 6f 6e 73 74 20 63 68 61 72 2a 29 0a 29 3b 0a  const char*).);.
36c70 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
36c80 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
36c90 5f 6e 65 65 64 65 64 31 36 28 0a 20 20 73 71 6c  _needed16(.  sql
36ca0 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c  ite3*, .  void*,
36cb0 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  .  void(*)(void*
36cc0 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54  ,sqlite3*,int eT
36cd0 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 76 6f 69  extRep,const voi
36ce0 64 2a 29 0a 29 3b 0a 0a 23 69 66 64 65 66 20 53  d*).);..#ifdef S
36cf0 51 4c 49 54 45 5f 48 41 53 5f 43 4f 44 45 43 0a  QLITE_HAS_CODEC.
36d00 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68  /*.** Specify th
36d10 65 20 6b 65 79 20 66 6f 72 20 61 6e 20 65 6e 63  e key for an enc
36d20 72 79 70 74 65 64 20 64 61 74 61 62 61 73 65 2e  rypted database.
36d30 20 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73    This routine s
36d40 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 63 61 6c 6c  hould be.** call
36d50 65 64 20 72 69 67 68 74 20 61 66 74 65 72 20 73  ed right after s
36d60 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 2e 0a 2a  qlite3_open()..*
36d70 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f  *.** The code to
36d80 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20   implement this 
36d90 41 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c  API is not avail
36da0 61 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c  able in the publ
36db0 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66  ic release.** of
36dc0 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 53 51 4c 49   SQLite..*/.SQLI
36dd0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
36de0 65 33 5f 6b 65 79 28 0a 20 20 73 71 6c 69 74 65  e3_key(.  sqlite
36df0 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
36e00 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
36e10 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79  base to be rekey
36e20 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  ed */.  const vo
36e30 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b  id *pKey, int nK
36e40 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6b 65  ey     /* The ke
36e50 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  y */.);../*.** C
36e60 68 61 6e 67 65 20 74 68 65 20 6b 65 79 20 6f 6e  hange the key on
36e70 20 61 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73   an open databas
36e80 65 2e 20 20 49 66 20 74 68 65 20 63 75 72 72 65  e.  If the curre
36e90 6e 74 20 64 61 74 61 62 61 73 65 20 69 73 20 6e  nt database is n
36ea0 6f 74 0a 2a 2a 20 65 6e 63 72 79 70 74 65 64 2c  ot.** encrypted,
36eb0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69   this routine wi
36ec0 6c 6c 20 65 6e 63 72 79 70 74 20 69 74 2e 20 20  ll encrypt it.  
36ed0 49 66 20 70 4e 65 77 3d 3d 30 20 6f 72 20 6e 4e  If pNew==0 or nN
36ee0 65 77 3d 3d 30 2c 20 74 68 65 0a 2a 2a 20 64 61  ew==0, the.** da
36ef0 74 61 62 61 73 65 20 69 73 20 64 65 63 72 79 70  tabase is decryp
36f00 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  ted..**.** The c
36f10 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  ode to implement
36f20 20 74 68 69 73 20 41 50 49 20 69 73 20 6e 6f 74   this API is not
36f30 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68   available in th
36f40 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61 73 65  e public release
36f50 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  .** of SQLite..*
36f60 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
36f70 20 73 71 6c 69 74 65 33 5f 72 65 6b 65 79 28 0a   sqlite3_rekey(.
36f80 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
36f90 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
36fa0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20   /* Database to 
36fb0 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20  be rekeyed */.  
36fc0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79  const void *pKey
36fd0 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f  , int nKey     /
36fe0 2a 20 54 68 65 20 6e 65 77 20 6b 65 79 20 2a 2f  * The new key */
36ff0 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69  .);../*.** Speci
37000 66 79 20 74 68 65 20 61 63 74 69 76 61 74 69 6f  fy the activatio
37010 6e 20 6b 65 79 20 66 6f 72 20 61 20 53 45 45 20  n key for a SEE 
37020 64 61 74 61 62 61 73 65 2e 20 20 55 6e 6c 65 73  database.  Unles
37030 73 20 0a 2a 2a 20 61 63 74 69 76 61 74 65 64 2c  s .** activated,
37040 20 6e 6f 6e 65 20 6f 66 20 74 68 65 20 53 45 45   none of the SEE
37050 20 72 6f 75 74 69 6e 65 73 20 77 69 6c 6c 20 77   routines will w
37060 6f 72 6b 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ork..*/.SQLITE_A
37070 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  PI void sqlite3_
37080 61 63 74 69 76 61 74 65 5f 73 65 65 28 0a 20 20  activate_see(.  
37090 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 73  const char *zPas
370a0 73 50 68 72 61 73 65 20 20 20 20 20 20 20 20 2f  sPhrase        /
370b0 2a 20 41 63 74 69 76 61 74 69 6f 6e 20 70 68 72  * Activation phr
370c0 61 73 65 20 2a 2f 0a 29 3b 0a 23 65 6e 64 69 66  ase */.);.#endif
370d0 0a 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f  ..#ifdef SQLITE_
370e0 45 4e 41 42 4c 45 5f 43 45 52 4f 44 0a 2f 2a 0a  ENABLE_CEROD./*.
370f0 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65 20 61  ** Specify the a
37100 63 74 69 76 61 74 69 6f 6e 20 6b 65 79 20 66 6f  ctivation key fo
37110 72 20 61 20 43 45 52 4f 44 20 64 61 74 61 62 61  r a CEROD databa
37120 73 65 2e 20 20 55 6e 6c 65 73 73 20 0a 2a 2a 20  se.  Unless .** 
37130 61 63 74 69 76 61 74 65 64 2c 20 6e 6f 6e 65 20  activated, none 
37140 6f 66 20 74 68 65 20 43 45 52 4f 44 20 72 6f 75  of the CEROD rou
37150 74 69 6e 65 73 20 77 69 6c 6c 20 77 6f 72 6b 2e  tines will work.
37160 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  .*/.SQLITE_API v
37170 6f 69 64 20 73 71 6c 69 74 65 33 5f 61 63 74 69  oid sqlite3_acti
37180 76 61 74 65 5f 63 65 72 6f 64 28 0a 20 20 63 6f  vate_cerod(.  co
37190 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 73 73 50  nst char *zPassP
371a0 68 72 61 73 65 20 20 20 20 20 20 20 20 2f 2a 20  hrase        /* 
371b0 41 63 74 69 76 61 74 69 6f 6e 20 70 68 72 61 73  Activation phras
371c0 65 20 2a 2f 0a 29 3b 0a 23 65 6e 64 69 66 0a 0a  e */.);.#endif..
371d0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
371e0 53 75 73 70 65 6e 64 20 45 78 65 63 75 74 69 6f  Suspend Executio
371f0 6e 20 46 6f 72 20 41 20 53 68 6f 72 74 20 54 69  n For A Short Ti
37200 6d 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  me.**.** The sql
37210 69 74 65 33 5f 73 6c 65 65 70 28 29 20 66 75 6e  ite3_sleep() fun
37220 63 74 69 6f 6e 20 63 61 75 73 65 73 20 74 68 65  ction causes the
37230 20 63 75 72 72 65 6e 74 20 74 68 72 65 61 64 20   current thread 
37240 74 6f 20 73 75 73 70 65 6e 64 20 65 78 65 63 75  to suspend execu
37250 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20 61 74 20 6c  tion.** for at l
37260 65 61 73 74 20 61 20 6e 75 6d 62 65 72 20 6f 66  east a number of
37270 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 73 70   milliseconds sp
37280 65 63 69 66 69 65 64 20 69 6e 20 69 74 73 20 70  ecified in its p
37290 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
372a0 49 66 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67  If the operating
372b0 20 73 79 73 74 65 6d 20 64 6f 65 73 20 6e 6f 74   system does not
372c0 20 73 75 70 70 6f 72 74 20 73 6c 65 65 70 20 72   support sleep r
372d0 65 71 75 65 73 74 73 20 77 69 74 68 0a 2a 2a 20  equests with.** 
372e0 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 74 69 6d 65  millisecond time
372f0 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 20 74 68 65   resolution, the
37300 6e 20 74 68 65 20 74 69 6d 65 20 77 69 6c 6c 20  n the time will 
37310 62 65 20 72 6f 75 6e 64 65 64 20 75 70 20 74 6f  be rounded up to
37320 0a 2a 2a 20 74 68 65 20 6e 65 61 72 65 73 74 20  .** the nearest 
37330 73 65 63 6f 6e 64 2e 20 54 68 65 20 6e 75 6d 62  second. The numb
37340 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e  er of millisecon
37350 64 73 20 6f 66 20 73 6c 65 65 70 20 61 63 74 75  ds of sleep actu
37360 61 6c 6c 79 0a 2a 2a 20 72 65 71 75 65 73 74 65  ally.** requeste
37370 64 20 66 72 6f 6d 20 74 68 65 20 6f 70 65 72 61  d from the opera
37380 74 69 6e 67 20 73 79 73 74 65 6d 20 69 73 20 72  ting system is r
37390 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  eturned..**.** ^
373a0 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74  SQLite implement
373b0 73 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  s this interface
373c0 20 62 79 20 63 61 6c 6c 69 6e 67 20 74 68 65 20   by calling the 
373d0 78 53 6c 65 65 70 28 29 0a 2a 2a 20 6d 65 74 68  xSleep().** meth
373e0 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c  od of the defaul
373f0 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  t [sqlite3_vfs] 
37400 6f 62 6a 65 63 74 2e 20 20 49 66 20 74 68 65 20  object.  If the 
37410 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 0a  xSleep() method.
37420 2a 2a 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c  ** of the defaul
37430 74 20 56 46 53 20 69 73 20 6e 6f 74 20 69 6d 70  t VFS is not imp
37440 6c 65 6d 65 6e 74 65 64 20 63 6f 72 72 65 63 74  lemented correct
37450 6c 79 2c 20 6f 72 20 6e 6f 74 20 69 6d 70 6c 65  ly, or not imple
37460 6d 65 6e 74 65 64 20 61 74 0a 2a 2a 20 61 6c 6c  mented at.** all
37470 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  , then the behav
37480 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 73  ior of sqlite3_s
37490 6c 65 65 70 28 29 20 6d 61 79 20 64 65 76 69 61  leep() may devia
374a0 74 65 20 66 72 6f 6d 20 74 68 65 20 64 65 73 63  te from the desc
374b0 72 69 70 74 69 6f 6e 0a 2a 2a 20 69 6e 20 74 68  ription.** in th
374c0 65 20 70 72 65 76 69 6f 75 73 20 70 61 72 61 67  e previous parag
374d0 72 61 70 68 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45  raphs..*/.SQLITE
374e0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
374f0 5f 73 6c 65 65 70 28 69 6e 74 29 3b 0a 0a 2f 2a  _sleep(int);../*
37500 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61  .** CAPI3REF: Na
37510 6d 65 20 4f 66 20 54 68 65 20 46 6f 6c 64 65 72  me Of The Folder
37520 20 48 6f 6c 64 69 6e 67 20 54 65 6d 70 6f 72 61   Holding Tempora
37530 72 79 20 46 69 6c 65 73 0a 2a 2a 0a 2a 2a 20 5e  ry Files.**.** ^
37540 28 49 66 20 74 68 69 73 20 67 6c 6f 62 61 6c 20  (If this global 
37550 76 61 72 69 61 62 6c 65 20 69 73 20 6d 61 64 65  variable is made
37560 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 61 20 73   to point to a s
37570 74 72 69 6e 67 20 77 68 69 63 68 20 69 73 0a 2a  tring which is.*
37580 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 61 20  * the name of a 
37590 66 6f 6c 64 65 72 20 28 61 2e 6b 2e 61 2e 20 64  folder (a.k.a. d
375a0 69 72 65 63 74 6f 72 79 29 2c 20 74 68 65 6e 20  irectory), then 
375b0 61 6c 6c 20 74 65 6d 70 6f 72 61 72 79 20 66 69  all temporary fi
375c0 6c 65 73 0a 2a 2a 20 63 72 65 61 74 65 64 20 62  les.** created b
375d0 79 20 53 51 4c 69 74 65 20 77 68 65 6e 20 75 73  y SQLite when us
375e0 69 6e 67 20 61 20 62 75 69 6c 74 2d 69 6e 20 5b  ing a built-in [
375f0 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 56 46  sqlite3_vfs | VF
37600 53 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 70 6c  S].** will be pl
37610 61 63 65 64 20 69 6e 20 74 68 61 74 20 64 69 72  aced in that dir
37620 65 63 74 6f 72 79 2e 29 5e 20 20 5e 49 66 20 74  ectory.)^  ^If t
37630 68 69 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20  his variable.** 
37640 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
37650 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 70  r, then SQLite p
37660 65 72 66 6f 72 6d 73 20 61 20 73 65 61 72 63 68  erforms a search
37670 20 66 6f 72 20 61 6e 20 61 70 70 72 6f 70 72 69   for an appropri
37680 61 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79  ate.** temporary
37690 20 66 69 6c 65 20 64 69 72 65 63 74 6f 72 79 2e   file directory.
376a0 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74  .**.** It is not
376b0 20 73 61 66 65 20 74 6f 20 72 65 61 64 20 6f 72   safe to read or
376c0 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61 72   modify this var
376d0 69 61 62 6c 65 20 69 6e 20 6d 6f 72 65 20 74 68  iable in more th
376e0 61 6e 20 6f 6e 65 0a 2a 2a 20 74 68 72 65 61 64  an one.** thread
376f0 20 61 74 20 61 20 74 69 6d 65 2e 20 20 49 74 20   at a time.  It 
37700 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 72  is not safe to r
37710 65 61 64 20 6f 72 20 6d 6f 64 69 66 79 20 74 68  ead or modify th
37720 69 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69  is variable.** i
37730 66 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  f a [database co
37740 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 69  nnection] is bei
37750 6e 67 20 75 73 65 64 20 61 74 20 74 68 65 20 73  ng used at the s
37760 61 6d 65 20 74 69 6d 65 20 69 6e 20 61 20 73 65  ame time in a se
37770 70 61 72 61 74 65 0a 2a 2a 20 74 68 72 65 61 64  parate.** thread
37780 2e 0a 2a 2a 20 49 74 20 69 73 20 69 6e 74 65 6e  ..** It is inten
37790 64 65 64 20 74 68 61 74 20 74 68 69 73 20 76 61  ded that this va
377a0 72 69 61 62 6c 65 20 62 65 20 73 65 74 20 6f 6e  riable be set on
377b0 63 65 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f 66  ce.** as part of
377c0 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c   process initial
377d0 69 7a 61 74 69 6f 6e 20 61 6e 64 20 62 65 66 6f  ization and befo
377e0 72 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e  re any SQLite in
377f0 74 65 72 66 61 63 65 0a 2a 2a 20 72 6f 75 74 69  terface.** routi
37800 6e 65 73 20 68 61 76 65 20 62 65 65 6e 20 63 61  nes have been ca
37810 6c 6c 65 64 20 61 6e 64 20 74 68 61 74 20 74 68  lled and that th
37820 69 73 20 76 61 72 69 61 62 6c 65 20 72 65 6d 61  is variable rema
37830 69 6e 20 75 6e 63 68 61 6e 67 65 64 0a 2a 2a 20  in unchanged.** 
37840 74 68 65 72 65 61 66 74 65 72 2e 0a 2a 2a 0a 2a  thereafter..**.*
37850 2a 20 5e 54 68 65 20 5b 74 65 6d 70 5f 73 74 6f  * ^The [temp_sto
37860 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61  re_directory pra
37870 67 6d 61 5d 20 6d 61 79 20 6d 6f 64 69 66 79 20  gma] may modify 
37880 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 61 6e  this variable an
37890 64 20 63 61 75 73 65 0a 2a 2a 20 69 74 20 74 6f  d cause.** it to
378a0 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79   point to memory
378b0 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b   obtained from [
378c0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 2e  sqlite3_malloc].
378d0 20 20 5e 46 75 72 74 68 65 72 6d 6f 72 65 2c 0a    ^Furthermore,.
378e0 2a 2a 20 74 68 65 20 5b 74 65 6d 70 5f 73 74 6f  ** the [temp_sto
378f0 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61  re_directory pra
37900 67 6d 61 5d 20 61 6c 77 61 79 73 20 61 73 73 75  gma] always assu
37910 6d 65 73 20 74 68 61 74 20 61 6e 79 20 73 74 72  mes that any str
37920 69 6e 67 0a 2a 2a 20 74 68 61 74 20 74 68 69 73  ing.** that this
37930 20 76 61 72 69 61 62 6c 65 20 70 6f 69 6e 74 73   variable points
37940 20 74 6f 20 69 73 20 68 65 6c 64 20 69 6e 20 6d   to is held in m
37950 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66  emory obtained f
37960 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  rom .** [sqlite3
37970 5f 6d 61 6c 6c 6f 63 5d 20 61 6e 64 20 74 68 65  _malloc] and the
37980 20 70 72 61 67 6d 61 20 6d 61 79 20 61 74 74 65   pragma may atte
37990 6d 70 74 20 74 6f 20 66 72 65 65 20 74 68 61 74  mpt to free that
379a0 20 6d 65 6d 6f 72 79 0a 2a 2a 20 75 73 69 6e 67   memory.** using
379b0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5d 2e   [sqlite3_free].
379c0 0a 2a 2a 20 48 65 6e 63 65 2c 20 69 66 20 74 68  .** Hence, if th
379d0 69 73 20 76 61 72 69 61 62 6c 65 20 69 73 20 6d  is variable is m
379e0 6f 64 69 66 69 65 64 20 64 69 72 65 63 74 6c 79  odified directly
379f0 2c 20 65 69 74 68 65 72 20 69 74 20 73 68 6f 75  , either it shou
37a00 6c 64 20 62 65 0a 2a 2a 20 6d 61 64 65 20 4e 55  ld be.** made NU
37a10 4c 4c 20 6f 72 20 6d 61 64 65 20 74 6f 20 70 6f  LL or made to po
37a20 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  int to memory ob
37a30 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
37a40 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 0a 2a 2a 20  ite3_malloc].** 
37a50 6f 72 20 65 6c 73 65 20 74 68 65 20 75 73 65 20  or else the use 
37a60 6f 66 20 74 68 65 20 5b 74 65 6d 70 5f 73 74 6f  of the [temp_sto
37a70 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61  re_directory pra
37a80 67 6d 61 5d 20 73 68 6f 75 6c 64 20 62 65 20 61  gma] should be a
37a90 76 6f 69 64 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54  voided..*/.SQLIT
37aa0 45 5f 41 50 49 20 63 68 61 72 20 2a 73 71 6c 69  E_API char *sqli
37ab0 74 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f  te3_temp_directo
37ac0 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  ry;../*.** CAPI3
37ad0 52 45 46 3a 20 54 65 73 74 20 46 6f 72 20 41 75  REF: Test For Au
37ae0 74 6f 2d 43 6f 6d 6d 69 74 20 4d 6f 64 65 0a 2a  to-Commit Mode.*
37af0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 75 74  * KEYWORDS: {aut
37b00 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 7d 0a 2a 2a  ocommit mode}.**
37b10 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
37b20 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28  _get_autocommit(
37b30 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
37b40 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 20 6f 72 0a  rns non-zero or.
37b50 2a 2a 20 7a 65 72 6f 20 69 66 20 74 68 65 20 67  ** zero if the g
37b60 69 76 65 6e 20 64 61 74 61 62 61 73 65 20 63 6f  iven database co
37b70 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 72 20 69  nnection is or i
37b80 73 20 6e 6f 74 20 69 6e 20 61 75 74 6f 63 6f 6d  s not in autocom
37b90 6d 69 74 20 6d 6f 64 65 2c 0a 2a 2a 20 72 65 73  mit mode,.** res
37ba0 70 65 63 74 69 76 65 6c 79 2e 20 20 5e 41 75 74  pectively.  ^Aut
37bb0 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20  ocommit mode is 
37bc0 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a  on by default..*
37bd0 2a 20 5e 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f  * ^Autocommit mo
37be0 64 65 20 69 73 20 64 69 73 61 62 6c 65 64 20 62  de is disabled b
37bf0 79 20 61 20 5b 42 45 47 49 4e 5d 20 73 74 61 74  y a [BEGIN] stat
37c00 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 41 75 74 6f 63  ement..** ^Autoc
37c10 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 72 65  ommit mode is re
37c20 2d 65 6e 61 62 6c 65 64 20 62 79 20 61 20 5b 43  -enabled by a [C
37c30 4f 4d 4d 49 54 5d 20 6f 72 20 5b 52 4f 4c 4c 42  OMMIT] or [ROLLB
37c40 41 43 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 63  ACK]..**.** If c
37c50 65 72 74 61 69 6e 20 6b 69 6e 64 73 20 6f 66 20  ertain kinds of 
37c60 65 72 72 6f 72 73 20 6f 63 63 75 72 20 6f 6e 20  errors occur on 
37c70 61 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68  a statement with
37c80 69 6e 20 61 20 6d 75 6c 74 69 2d 73 74 61 74 65  in a multi-state
37c90 6d 65 6e 74 0a 2a 2a 20 74 72 61 6e 73 61 63 74  ment.** transact
37ca0 69 6f 6e 20 28 65 72 72 6f 72 73 20 69 6e 63 6c  ion (errors incl
37cb0 75 64 69 6e 67 20 5b 53 51 4c 49 54 45 5f 46 55  uding [SQLITE_FU
37cc0 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f 49 4f 45  LL], [SQLITE_IOE
37cd0 52 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  RR],.** [SQLITE_
37ce0 4e 4f 4d 45 4d 5d 2c 20 5b 53 51 4c 49 54 45 5f  NOMEM], [SQLITE_
37cf0 42 55 53 59 5d 2c 20 61 6e 64 20 5b 53 51 4c 49  BUSY], and [SQLI
37d00 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 29 20 74  TE_INTERRUPT]) t
37d10 68 65 6e 20 74 68 65 0a 2a 2a 20 74 72 61 6e 73  hen the.** trans
37d20 61 63 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20  action might be 
37d30 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f  rolled back auto
37d40 6d 61 74 69 63 61 6c 6c 79 2e 20 20 54 68 65 20  matically.  The 
37d50 6f 6e 6c 79 20 77 61 79 20 74 6f 0a 2a 2a 20 66  only way to.** f
37d60 69 6e 64 20 6f 75 74 20 77 68 65 74 68 65 72 20  ind out whether 
37d70 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 63  SQLite automatic
37d80 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b  ally rolled back
37d90 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e   the transaction
37da0 20 61 66 74 65 72 0a 2a 2a 20 61 6e 20 65 72 72   after.** an err
37db0 6f 72 20 69 73 20 74 6f 20 75 73 65 20 74 68 69  or is to use thi
37dc0 73 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a  s function..**.*
37dd0 2a 20 49 66 20 61 6e 6f 74 68 65 72 20 74 68 72  * If another thr
37de0 65 61 64 20 63 68 61 6e 67 65 73 20 74 68 65 20  ead changes the 
37df0 61 75 74 6f 63 6f 6d 6d 69 74 20 73 74 61 74 75  autocommit statu
37e00 73 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  s of the databas
37e10 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  e.** connection 
37e20 77 68 69 6c 65 20 74 68 69 73 20 72 6f 75 74 69  while this routi
37e30 6e 65 20 69 73 20 72 75 6e 6e 69 6e 67 2c 20 74  ne is running, t
37e40 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76  hen the return v
37e50 61 6c 75 65 0a 2a 2a 20 69 73 20 75 6e 64 65 66  alue.** is undef
37e60 69 6e 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  ined..*/.SQLITE_
37e70 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
37e80 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 73  get_autocommit(s
37e90 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
37ea0 20 43 41 50 49 33 52 45 46 3a 20 46 69 6e 64 20   CAPI3REF: Find 
37eb0 54 68 65 20 44 61 74 61 62 61 73 65 20 48 61 6e  The Database Han
37ec0 64 6c 65 20 4f 66 20 41 20 50 72 65 70 61 72 65  dle Of A Prepare
37ed0 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a  d Statement.**.*
37ee0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64  * ^The sqlite3_d
37ef0 62 5f 68 61 6e 64 6c 65 20 69 6e 74 65 72 66 61  b_handle interfa
37f00 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b  ce returns the [
37f10 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
37f20 69 6f 6e 5d 20 68 61 6e 64 6c 65 0a 2a 2a 20 74  ion] handle.** t
37f30 6f 20 77 68 69 63 68 20 61 20 5b 70 72 65 70 61  o which a [prepa
37f40 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 62  red statement] b
37f50 65 6c 6f 6e 67 73 2e 20 20 5e 54 68 65 20 5b 64  elongs.  ^The [d
37f60 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
37f70 6f 6e 5d 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  on].** returned 
37f80 62 79 20 73 71 6c 69 74 65 33 5f 64 62 5f 68 61  by sqlite3_db_ha
37f90 6e 64 6c 65 20 69 73 20 74 68 65 20 73 61 6d 65  ndle is the same
37fa0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
37fb0 63 74 69 6f 6e 5d 0a 2a 2a 20 74 68 61 74 20 77  ction].** that w
37fc0 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67  as the first arg
37fd0 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20  ument.** to the 
37fe0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
37ff0 5f 76 32 28 29 5d 20 63 61 6c 6c 20 28 6f 72 20  _v2()] call (or 
38000 69 74 73 20 76 61 72 69 61 6e 74 73 29 20 74 68  its variants) th
38010 61 74 20 77 61 73 20 75 73 65 64 20 74 6f 0a 2a  at was used to.*
38020 2a 20 63 72 65 61 74 65 20 74 68 65 20 73 74 61  * create the sta
38030 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 66 69  tement in the fi
38040 72 73 74 20 70 6c 61 63 65 2e 0a 2a 2f 0a 53 51  rst place..*/.SQ
38050 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33  LITE_API sqlite3
38060 20 2a 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e   *sqlite3_db_han
38070 64 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  dle(sqlite3_stmt
38080 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
38090 52 45 46 3a 20 46 69 6e 64 20 74 68 65 20 6e 65  REF: Find the ne
380a0 78 74 20 70 72 65 70 61 72 65 64 20 73 74 61 74  xt prepared stat
380b0 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  ement.**.** ^Thi
380c0 73 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  s interface retu
380d0 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
380e0 20 74 68 65 20 6e 65 78 74 20 5b 70 72 65 70 61   the next [prepa
380f0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61  red statement] a
38100 66 74 65 72 0a 2a 2a 20 70 53 74 6d 74 20 61 73  fter.** pStmt as
38110 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
38120 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
38130 65 63 74 69 6f 6e 5d 20 70 44 62 2e 20 20 5e 49  ection] pDb.  ^I
38140 66 20 70 53 74 6d 74 20 69 73 20 4e 55 4c 4c 0a  f pStmt is NULL.
38150 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 69 6e 74  ** then this int
38160 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
38170 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
38180 66 69 72 73 74 20 70 72 65 70 61 72 65 64 20 73  first prepared s
38190 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 61 73 73 6f  tatement.** asso
381a0 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
381b0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
381c0 69 6f 6e 20 70 44 62 2e 20 20 5e 49 66 20 6e 6f  ion pDb.  ^If no
381d0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
381e0 65 6e 74 0a 2a 2a 20 73 61 74 69 73 66 69 65 73  ent.** satisfies
381f0 20 74 68 65 20 63 6f 6e 64 69 74 69 6f 6e 73 20   the conditions 
38200 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c  of this routine,
38210 20 69 74 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c   it returns NULL
38220 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 64 61 74  ..**.** The [dat
38230 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
38240 5d 20 70 6f 69 6e 74 65 72 20 44 20 69 6e 20 61  ] pointer D in a
38250 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c   call to.** [sql
38260 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 44  ite3_next_stmt(D
38270 2c 53 29 5d 20 6d 75 73 74 20 72 65 66 65 72 20  ,S)] must refer 
38280 74 6f 20 61 6e 20 6f 70 65 6e 20 64 61 74 61 62  to an open datab
38290 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
382a0 6e 20 61 6e 64 20 69 6e 20 70 61 72 74 69 63 75  n and in particu
382b0 6c 61 72 20 6d 75 73 74 20 6e 6f 74 20 62 65 20  lar must not be 
382c0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
382d0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71  */.SQLITE_API sq
382e0 6c 69 74 65 33 5f 73 74 6d 74 20 2a 73 71 6c 69  lite3_stmt *sqli
382f0 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 73 71  te3_next_stmt(sq
38300 6c 69 74 65 33 20 2a 70 44 62 2c 20 73 71 6c 69  lite3 *pDb, sqli
38310 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
38320 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
38330 46 3a 20 43 6f 6d 6d 69 74 20 41 6e 64 20 52 6f  F: Commit And Ro
38340 6c 6c 62 61 63 6b 20 4e 6f 74 69 66 69 63 61 74  llback Notificat
38350 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a  ion Callbacks.**
38360 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
38370 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 20 69  _commit_hook() i
38380 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65  nterface registe
38390 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  rs a callback.**
383a0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
383b0 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72  invoked whenever
383c0 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69   a transaction i
383d0 73 20 5b 43 4f 4d 4d 49 54 20 7c 20 63 6f 6d 6d  s [COMMIT | comm
383e0 69 74 74 65 64 5d 2e 0a 2a 2a 20 5e 41 6e 79 20  itted]..** ^Any 
383f0 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20  callback set by 
38400 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20  a previous call 
38410 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69  to sqlite3_commi
38420 74 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20  t_hook().** for 
38430 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
38440 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
38450 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20 5e  overridden..** ^
38460 54 68 65 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c  The sqlite3_roll
38470 62 61 63 6b 5f 68 6f 6f 6b 28 29 20 69 6e 74 65  back_hook() inte
38480 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20  rface registers 
38490 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75  a callback.** fu
384a0 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76  nction to be inv
384b0 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 20  oked whenever a 
384c0 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 5b  transaction is [
384d0 52 4f 4c 4c 42 41 43 4b 20 7c 20 72 6f 6c 6c 65  ROLLBACK | rolle
384e0 64 20 62 61 63 6b 5d 2e 0a 2a 2a 20 5e 41 6e 79  d back]..** ^Any
384f0 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79   callback set by
38500 20 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c   a previous call
38510 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c   to sqlite3_roll
38520 62 61 63 6b 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66  back_hook().** f
38530 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  or the same data
38540 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
38550 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a  is overridden..*
38560 2a 20 5e 54 68 65 20 70 41 72 67 20 61 72 67 75  * ^The pArg argu
38570 6d 65 6e 74 20 69 73 20 70 61 73 73 65 64 20 74  ment is passed t
38580 68 72 6f 75 67 68 20 74 6f 20 74 68 65 20 63 61  hrough to the ca
38590 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 49 66 20 74  llback..** ^If t
385a0 68 65 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 20 61  he callback on a
385b0 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 66 75 6e   commit hook fun
385c0 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 6e 6f  ction returns no
385d0 6e 2d 7a 65 72 6f 2c 0a 2a 2a 20 74 68 65 6e 20  n-zero,.** then 
385e0 74 68 65 20 63 6f 6d 6d 69 74 20 69 73 20 63 6f  the commit is co
385f0 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61 20 72  nverted into a r
38600 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e  ollback..**.** ^
38610 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d  The sqlite3_comm
38620 69 74 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29 20 61  it_hook(D,C,P) a
38630 6e 64 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62  nd sqlite3_rollb
38640 61 63 6b 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29 20  ack_hook(D,C,P) 
38650 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 74  functions.** ret
38660 75 72 6e 20 74 68 65 20 50 20 61 72 67 75 6d 65  urn the P argume
38670 6e 74 20 66 72 6f 6d 20 74 68 65 20 70 72 65 76  nt from the prev
38680 69 6f 75 73 20 63 61 6c 6c 20 6f 66 20 74 68 65  ious call of the
38690 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 0a 2a   same function.*
386a0 2a 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64  * on the same [d
386b0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
386c0 6f 6e 5d 20 44 2c 20 6f 72 20 4e 55 4c 4c 20 66  on] D, or NULL f
386d0 6f 72 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20  or.** the first 
386e0 63 61 6c 6c 20 66 6f 72 20 65 61 63 68 20 66 75  call for each fu
386f0 6e 63 74 69 6f 6e 20 6f 6e 20 44 2e 0a 2a 2a 0a  nction on D..**.
38700 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20  ** The callback 
38710 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d  implementation m
38720 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68  ust not do anyth
38730 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f  ing that will mo
38740 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61  dify.** the data
38750 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
38760 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65  that invoked the
38770 20 63 61 6c 6c 62 61 63 6b 2e 20 20 41 6e 79 20   callback.  Any 
38780 61 63 74 69 6f 6e 73 0a 2a 2a 20 74 6f 20 6d 6f  actions.** to mo
38790 64 69 66 79 20 74 68 65 20 64 61 74 61 62 61 73  dify the databas
387a0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73  e connection mus
387b0 74 20 62 65 20 64 65 66 65 72 72 65 64 20 75 6e  t be deferred un
387c0 74 69 6c 20 61 66 74 65 72 20 74 68 65 0a 2a 2a  til after the.**
387d0 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 6