System.Data.SQLite
Hex Artifact Content
Not logged in

Artifact 4718451fbf6ec3ed7f7302ae1ba4da4219333bc3:


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 38 2e 37 2e 20 20 42  ersion 3.8.7.  B
00b0: 79 20 63 6f 6d 62 69 6e 69 6e 67 20 61 6c 6c 20  y combining all 
00c0: 74 68 65 20 69 6e 64 69 76 69 64 75 61 6c 20 43  the individual C
00d0: 20 63 6f 64 65 20 66 69 6c 65 73 20 69 6e 74 6f   code files into
00e0: 20 74 68 69 73 20 0a 2a 2a 20 73 69 6e 67 6c 65   this .** single
00f0: 20 6c 61 72 67 65 20 66 69 6c 65 2c 20 74 68 65   large file, the
0100: 20 65 6e 74 69 72 65 20 63 6f 64 65 20 63 61 6e   entire code can
0110: 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 61 73 20   be compiled as 
0120: 61 20 73 69 6e 67 6c 65 20 74 72 61 6e 73 6c 61  a single transla
0130: 74 69 6f 6e 0a 2a 2a 20 75 6e 69 74 2e 20 20 54  tion.** unit.  T
0140: 68 69 73 20 61 6c 6c 6f 77 73 20 6d 61 6e 79 20  his allows many 
0150: 63 6f 6d 70 69 6c 65 72 73 20 74 6f 20 64 6f 20  compilers to do 
0160: 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 73 20 74 68  optimizations th
0170: 61 74 20 77 6f 75 6c 64 20 6e 6f 74 20 62 65 0a  at would not be.
0180: 2a 2a 20 70 6f 73 73 69 62 6c 65 20 69 66 20 74  ** possible if t
0190: 68 65 20 66 69 6c 65 73 20 77 65 72 65 20 63 6f  he files were co
01a0: 6d 70 69 6c 65 64 20 73 65 70 61 72 61 74 65 6c  mpiled separatel
01b0: 79 2e 20 20 50 65 72 66 6f 72 6d 61 6e 63 65 20  y.  Performance 
01c0: 69 6d 70 72 6f 76 65 6d 65 6e 74 73 0a 2a 2a 20  improvements.** 
01d0: 6f 66 20 35 25 20 6f 72 20 6d 6f 72 65 20 61 72  of 5% or more ar
01e0: 65 20 63 6f 6d 6d 6f 6e 6c 79 20 73 65 65 6e 20  e commonly seen 
01f0: 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63  when SQLite is c
0200: 6f 6d 70 69 6c 65 64 20 61 73 20 61 20 73 69 6e  ompiled as a sin
0210: 67 6c 65 0a 2a 2a 20 74 72 61 6e 73 6c 61 74 69  gle.** translati
0220: 6f 6e 20 75 6e 69 74 2e 0a 2a 2a 0a 2a 2a 20 54  on unit..**.** T
0230: 68 69 73 20 66 69 6c 65 20 69 73 20 61 6c 6c 20  his file is all 
0240: 79 6f 75 20 6e 65 65 64 20 74 6f 20 63 6f 6d 70  you need to comp
0250: 69 6c 65 20 53 51 4c 69 74 65 2e 20 20 54 6f 20  ile SQLite.  To 
0260: 75 73 65 20 53 51 4c 69 74 65 20 69 6e 20 6f 74  use SQLite in ot
0270: 68 65 72 0a 2a 2a 20 70 72 6f 67 72 61 6d 73 2c  her.** programs,
0280: 20 79 6f 75 20 6e 65 65 64 20 74 68 69 73 20 66   you need this f
0290: 69 6c 65 20 61 6e 64 20 74 68 65 20 22 73 71 6c  ile and the "sql
02a0: 69 74 65 33 2e 68 22 20 68 65 61 64 65 72 20 66  ite3.h" header f
02b0: 69 6c 65 20 74 68 61 74 20 64 65 66 69 6e 65 73  ile that defines
02c0: 0a 2a 2a 20 74 68 65 20 70 72 6f 67 72 61 6d 6d  .** the programm
02d0: 69 6e 67 20 69 6e 74 65 72 66 61 63 65 20 74 6f  ing interface to
02e0: 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72   the SQLite libr
02f0: 61 72 79 2e 20 20 28 49 66 20 79 6f 75 20 64 6f  ary.  (If you do
0300: 20 6e 6f 74 20 68 61 76 65 20 0a 2a 2a 20 74 68   not have .** th
0310: 65 20 22 73 71 6c 69 74 65 33 2e 68 22 20 68 65  e "sqlite3.h" he
0320: 61 64 65 72 20 66 69 6c 65 20 61 74 20 68 61 6e  ader file at han
0330: 64 2c 20 79 6f 75 20 77 69 6c 6c 20 66 69 6e 64  d, you will find
0340: 20 61 20 63 6f 70 79 20 65 6d 62 65 64 64 65 64   a copy embedded
0350: 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20 74   within.** the t
0360: 65 78 74 20 6f 66 20 74 68 69 73 20 66 69 6c 65  ext of this file
0370: 2e 20 20 53 65 61 72 63 68 20 66 6f 72 20 22 42  .  Search for "B
0380: 65 67 69 6e 20 66 69 6c 65 20 73 71 6c 69 74 65  egin file sqlite
0390: 33 2e 68 22 20 74 6f 20 66 69 6e 64 20 74 68 65  3.h" to find the
03a0: 20 73 74 61 72 74 0a 2a 2a 20 6f 66 20 74 68 65   start.** of the
03b0: 20 65 6d 62 65 64 64 65 64 20 73 71 6c 69 74 65   embedded sqlite
03c0: 33 2e 68 20 68 65 61 64 65 72 20 66 69 6c 65 2e  3.h header file.
03d0: 29 20 41 64 64 69 74 69 6f 6e 61 6c 20 63 6f 64  ) Additional cod
03e0: 65 20 66 69 6c 65 73 20 6d 61 79 20 62 65 20 6e  e files may be n
03f0: 65 65 64 65 64 0a 2a 2a 20 69 66 20 79 6f 75 20  eeded.** if you 
0400: 77 61 6e 74 20 61 20 77 72 61 70 70 65 72 20 74  want a wrapper t
0410: 6f 20 69 6e 74 65 72 66 61 63 65 20 53 51 4c 69  o interface SQLi
0420: 74 65 20 77 69 74 68 20 79 6f 75 72 20 63 68 6f  te with your cho
0430: 69 63 65 20 6f 66 20 70 72 6f 67 72 61 6d 6d 69  ice of programmi
0440: 6e 67 0a 2a 2a 20 6c 61 6e 67 75 61 67 65 2e 20  ng.** language. 
0450: 54 68 65 20 63 6f 64 65 20 66 6f 72 20 74 68 65  The code for the
0460: 20 22 73 71 6c 69 74 65 33 22 20 63 6f 6d 6d 61   "sqlite3" comma
0470: 6e 64 2d 6c 69 6e 65 20 73 68 65 6c 6c 20 69 73  nd-line shell is
0480: 20 61 6c 73 6f 20 69 6e 20 61 0a 2a 2a 20 73 65   also in a.** se
0490: 70 61 72 61 74 65 20 66 69 6c 65 2e 20 54 68 69  parate file. Thi
04a0: 73 20 66 69 6c 65 20 63 6f 6e 74 61 69 6e 73 20  s file contains 
04b0: 6f 6e 6c 79 20 63 6f 64 65 20 66 6f 72 20 74 68  only code for th
04c0: 65 20 63 6f 72 65 20 53 51 4c 69 74 65 20 6c 69  e core SQLite li
04d0: 62 72 61 72 79 2e 0a 2a 2f 0a 23 64 65 66 69 6e  brary..*/.#defin
04e0: 65 20 53 51 4c 49 54 45 5f 43 4f 52 45 20 31 0a  e SQLITE_CORE 1.
04f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
0500: 4d 41 4c 47 41 4d 41 54 49 4f 4e 20 31 0a 23 69  MALGAMATION 1.#i
0510: 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 50 52 49  fndef SQLITE_PRI
0520: 56 41 54 45 0a 23 20 64 65 66 69 6e 65 20 53 51  VATE.# define SQ
0530: 4c 49 54 45 5f 50 52 49 56 41 54 45 20 73 74 61  LITE_PRIVATE sta
0540: 74 69 63 0a 23 65 6e 64 69 66 0a 23 69 66 6e 64  tic.#endif.#ifnd
0550: 65 66 20 53 51 4c 49 54 45 5f 41 50 49 0a 23 20  ef SQLITE_API.# 
0560: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 50  define SQLITE_AP
0570: 49 0a 23 65 6e 64 69 66 0a 2f 2a 2a 2a 2a 2a 2a  I.#endif./******
0580: 2a 2a 2a 2a 2a 2a 2a 2a 20 42 65 67 69 6e 20 66  ******** Begin f
0590: 69 6c 65 20 73 71 6c 69 74 65 49 6e 74 2e 68 20  ile sqliteInt.h 
05a0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
05b0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
05c0: 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a 0a 2a 2a 20 32  *******/./*.** 2
05d0: 30 30 31 20 53 65 70 74 65 6d 62 65 72 20 31 35  001 September 15
05e0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f  .**.** The autho
05f0: 72 20 64 69 73 63 6c 61 69 6d 73 20 63 6f 70 79  r disclaims copy
0600: 72 69 67 68 74 20 74 6f 20 74 68 69 73 20 73 6f  right to this so
0610: 75 72 63 65 20 63 6f 64 65 2e 20 20 49 6e 20 70  urce code.  In p
0620: 6c 61 63 65 20 6f 66 0a 2a 2a 20 61 20 6c 65 67  lace of.** a leg
0630: 61 6c 20 6e 6f 74 69 63 65 2c 20 68 65 72 65 20  al notice, here 
0640: 69 73 20 61 20 62 6c 65 73 73 69 6e 67 3a 0a 2a  is a blessing:.*
0650: 2a 0a 2a 2a 20 20 20 20 4d 61 79 20 79 6f 75 20  *.**    May you 
0660: 64 6f 20 67 6f 6f 64 20 61 6e 64 20 6e 6f 74 20  do good and not 
0670: 65 76 69 6c 2e 0a 2a 2a 20 20 20 20 4d 61 79 20  evil..**    May 
0680: 79 6f 75 20 66 69 6e 64 20 66 6f 72 67 69 76 65  you find forgive
0690: 6e 65 73 73 20 66 6f 72 20 79 6f 75 72 73 65 6c  ness for yoursel
06a0: 66 20 61 6e 64 20 66 6f 72 67 69 76 65 20 6f 74  f and forgive ot
06b0: 68 65 72 73 2e 0a 2a 2a 20 20 20 20 4d 61 79 20  hers..**    May 
06c0: 79 6f 75 20 73 68 61 72 65 20 66 72 65 65 6c 79  you share freely
06d0: 2c 20 6e 65 76 65 72 20 74 61 6b 69 6e 67 20 6d  , never taking m
06e0: 6f 72 65 20 74 68 61 6e 20 79 6f 75 20 67 69 76  ore than you giv
06f0: 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  e..**.**********
0700: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0710: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0720: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0730: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a  ***************.
0740: 2a 2a 20 49 6e 74 65 72 6e 61 6c 20 69 6e 74 65  ** Internal inte
0750: 72 66 61 63 65 20 64 65 66 69 6e 69 74 69 6f 6e  rface definition
0760: 73 20 66 6f 72 20 53 51 4c 69 74 65 2e 0a 2a 2a  s for SQLite..**
0770: 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53 51 4c  .*/.#ifndef _SQL
0780: 49 54 45 49 4e 54 5f 48 5f 0a 23 64 65 66 69 6e  ITEINT_H_.#defin
0790: 65 20 5f 53 51 4c 49 54 45 49 4e 54 5f 48 5f 0a  e _SQLITEINT_H_.
07a0: 0a 2f 2a 0a 2a 2a 20 54 68 65 73 65 20 23 64 65  ./*.** These #de
07b0: 66 69 6e 65 73 20 73 68 6f 75 6c 64 20 65 6e 61  fines should ena
07c0: 62 6c 65 20 3e 32 47 42 20 66 69 6c 65 20 73 75  ble >2GB file su
07d0: 70 70 6f 72 74 20 6f 6e 20 50 4f 53 49 58 20 69  pport on POSIX i
07e0: 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79  f the.** underly
07f0: 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79  ing operating sy
0800: 73 74 65 6d 20 73 75 70 70 6f 72 74 73 20 69 74  stem supports it
0810: 2e 20 20 49 66 20 74 68 65 20 4f 53 20 6c 61 63  .  If the OS lac
0820: 6b 73 0a 2a 2a 20 6c 61 72 67 65 20 66 69 6c 65  ks.** large file
0830: 20 73 75 70 70 6f 72 74 2c 20 6f 72 20 69 66 20   support, or if 
0840: 74 68 65 20 4f 53 20 69 73 20 77 69 6e 64 6f 77  the OS is window
0850: 73 2c 20 74 68 65 73 65 20 73 68 6f 75 6c 64 20  s, these should 
0860: 62 65 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 0a 2a 2a  be no-ops..**.**
0870: 20 54 69 63 6b 65 74 20 23 32 37 33 39 3a 20 20   Ticket #2739:  
0880: 54 68 65 20 5f 4c 41 52 47 45 46 49 4c 45 5f 53  The _LARGEFILE_S
0890: 4f 55 52 43 45 20 6d 61 63 72 6f 20 6d 75 73 74  OURCE macro must
08a0: 20 61 70 70 65 61 72 20 62 65 66 6f 72 65 20 61   appear before a
08b0: 6e 79 0a 2a 2a 20 73 79 73 74 65 6d 20 23 69 6e  ny.** system #in
08c0: 63 6c 75 64 65 73 2e 20 20 48 65 6e 63 65 2c 20  cludes.  Hence, 
08d0: 74 68 69 73 20 62 6c 6f 63 6b 20 6f 66 20 63 6f  this block of co
08e0: 64 65 20 6d 75 73 74 20 62 65 20 74 68 65 20 76  de must be the v
08f0: 65 72 79 20 66 69 72 73 74 0a 2a 2a 20 63 6f 64  ery first.** cod
0900: 65 20 69 6e 20 61 6c 6c 20 73 6f 75 72 63 65 20  e in all source 
0910: 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 4c 61 72  files..**.** Lar
0920: 67 65 20 66 69 6c 65 20 73 75 70 70 6f 72 74 20  ge file support 
0930: 63 61 6e 20 62 65 20 64 69 73 61 62 6c 65 64 20  can be disabled 
0940: 75 73 69 6e 67 20 74 68 65 20 2d 44 53 51 4c 49  using the -DSQLI
0950: 54 45 5f 44 49 53 41 42 4c 45 5f 4c 46 53 20 73  TE_DISABLE_LFS s
0960: 77 69 74 63 68 0a 2a 2a 20 6f 6e 20 74 68 65 20  witch.** on the 
0970: 63 6f 6d 70 69 6c 65 72 20 63 6f 6d 6d 61 6e 64  compiler command
0980: 20 6c 69 6e 65 2e 20 20 54 68 69 73 20 69 73 20   line.  This is 
0990: 6e 65 63 65 73 73 61 72 79 20 69 66 20 79 6f 75  necessary if you
09a0: 20 61 72 65 20 63 6f 6d 70 69 6c 69 6e 67 0a 2a   are compiling.*
09b0: 2a 20 6f 6e 20 61 20 72 65 63 65 6e 74 20 6d 61  * on a recent ma
09c0: 63 68 69 6e 65 20 28 65 78 3a 20 52 65 64 20 48  chine (ex: Red H
09d0: 61 74 20 37 2e 32 29 20 62 75 74 20 79 6f 75 20  at 7.2) but you 
09e0: 77 61 6e 74 20 79 6f 75 72 20 63 6f 64 65 20 74  want your code t
09f0: 6f 20 77 6f 72 6b 0a 2a 2a 20 6f 6e 20 61 6e 20  o work.** on an 
0a00: 6f 6c 64 65 72 20 6d 61 63 68 69 6e 65 20 28 65  older machine (e
0a10: 78 3a 20 52 65 64 20 48 61 74 20 36 2e 30 29 2e  x: Red Hat 6.0).
0a20: 20 20 49 66 20 79 6f 75 20 63 6f 6d 70 69 6c 65    If you compile
0a30: 20 6f 6e 20 52 65 64 20 48 61 74 20 37 2e 32 0a   on Red Hat 7.2.
0a40: 2a 2a 20 77 69 74 68 6f 75 74 20 74 68 69 73 20  ** without this 
0a50: 6f 70 74 69 6f 6e 2c 20 4c 46 53 20 69 73 20 65  option, LFS is e
0a60: 6e 61 62 6c 65 2e 20 20 42 75 74 20 4c 46 53 20  nable.  But LFS 
0a70: 64 6f 65 73 20 6e 6f 74 20 65 78 69 73 74 20 69  does not exist i
0a80: 6e 20 74 68 65 20 6b 65 72 6e 65 6c 0a 2a 2a 20  n the kernel.** 
0a90: 69 6e 20 52 65 64 20 48 61 74 20 36 2e 30 2c 20  in Red Hat 6.0, 
0aa0: 73 6f 20 74 68 65 20 63 6f 64 65 20 77 6f 6e 27  so the code won'
0ab0: 74 20 77 6f 72 6b 2e 20 20 48 65 6e 63 65 2c 20  t work.  Hence, 
0ac0: 66 6f 72 20 6d 61 78 69 6d 75 6d 20 62 69 6e 61  for maximum bina
0ad0: 72 79 0a 2a 2a 20 70 6f 72 74 61 62 69 6c 69 74  ry.** portabilit
0ae0: 79 20 79 6f 75 20 73 68 6f 75 6c 64 20 6f 6d 69  y you should omi
0af0: 74 20 4c 46 53 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  t LFS..**.** The
0b00: 20 70 72 65 76 69 6f 75 73 20 70 61 72 61 67 72   previous paragr
0b10: 61 70 68 20 77 61 73 20 77 72 69 74 74 65 6e 20  aph was written 
0b20: 69 6e 20 32 30 30 35 2e 20 20 28 54 68 69 73 20  in 2005.  (This 
0b30: 70 61 72 61 67 72 61 70 68 20 69 73 20 77 72 69  paragraph is wri
0b40: 74 74 65 6e 0a 2a 2a 20 6f 6e 20 32 30 30 38 2d  tten.** on 2008-
0b50: 31 31 2d 32 38 2e 29 20 54 68 65 73 65 20 64 61  11-28.) These da
0b60: 79 73 2c 20 61 6c 6c 20 4c 69 6e 75 78 20 6b 65  ys, all Linux ke
0b70: 72 6e 65 6c 73 20 73 75 70 70 6f 72 74 20 6c 61  rnels support la
0b80: 72 67 65 20 66 69 6c 65 73 2c 20 73 6f 0a 2a 2a  rge files, so.**
0b90: 20 79 6f 75 20 73 68 6f 75 6c 64 20 70 72 6f 62   you should prob
0ba0: 61 62 6c 79 20 6c 65 61 76 65 20 4c 46 53 20 65  ably leave LFS e
0bb0: 6e 61 62 6c 65 64 2e 20 20 42 75 74 20 73 6f 6d  nabled.  But som
0bc0: 65 20 65 6d 62 65 64 64 65 64 20 70 6c 61 74 66  e embedded platf
0bd0: 6f 72 6d 73 20 6d 69 67 68 74 0a 2a 2a 20 6c 61  orms might.** la
0be0: 63 6b 20 4c 46 53 20 69 6e 20 77 68 69 63 68 20  ck LFS in which 
0bf0: 63 61 73 65 20 74 68 65 20 53 51 4c 49 54 45 5f  case the SQLITE_
0c00: 44 49 53 41 42 4c 45 5f 4c 46 53 20 6d 61 63 72  DISABLE_LFS macr
0c10: 6f 20 6d 69 67 68 74 20 73 74 69 6c 6c 20 62 65  o might still be
0c20: 20 75 73 65 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 53   useful..**.** S
0c30: 69 6d 69 6c 61 72 20 69 73 20 74 72 75 65 20 66  imilar is true f
0c40: 6f 72 20 4d 61 63 20 4f 53 20 58 2e 20 20 4c 46  or Mac OS X.  LF
0c50: 53 20 69 73 20 6f 6e 6c 79 20 73 75 70 70 6f 72  S is only suppor
0c60: 74 65 64 20 6f 6e 20 4d 61 63 20 4f 53 20 58 20  ted on Mac OS X 
0c70: 39 20 61 6e 64 20 6c 61 74 65 72 2e 0a 2a 2f 0a  9 and later..*/.
0c80: 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 44  #ifndef SQLITE_D
0c90: 49 53 41 42 4c 45 5f 4c 46 53 0a 23 20 64 65 66  ISABLE_LFS.# def
0ca0: 69 6e 65 20 5f 4c 41 52 47 45 5f 46 49 4c 45 20  ine _LARGE_FILE 
0cb0: 20 20 20 20 20 20 31 0a 23 20 69 66 6e 64 65 66        1.# ifndef
0cc0: 20 5f 46 49 4c 45 5f 4f 46 46 53 45 54 5f 42 49   _FILE_OFFSET_BI
0cd0: 54 53 0a 23 20 20 20 64 65 66 69 6e 65 20 5f 46  TS.#   define _F
0ce0: 49 4c 45 5f 4f 46 46 53 45 54 5f 42 49 54 53 20  ILE_OFFSET_BITS 
0cf0: 36 34 0a 23 20 65 6e 64 69 66 0a 23 20 64 65 66  64.# endif.# def
0d00: 69 6e 65 20 5f 4c 41 52 47 45 46 49 4c 45 5f 53  ine _LARGEFILE_S
0d10: 4f 55 52 43 45 20 31 0a 23 65 6e 64 69 66 0a 0a  OURCE 1.#endif..
0d20: 2f 2a 20 4e 65 65 64 65 64 20 66 6f 72 20 76 61  /* Needed for va
0d30: 72 69 6f 75 73 20 64 65 66 69 6e 69 74 69 6f 6e  rious definition
0d40: 73 2e 2e 2e 20 2a 2f 0a 23 69 66 20 64 65 66 69  s... */.#if defi
0d50: 6e 65 64 28 5f 5f 47 4e 55 43 5f 5f 29 20 26 26  ned(__GNUC__) &&
0d60: 20 21 64 65 66 69 6e 65 64 28 5f 47 4e 55 5f 53   !defined(_GNU_S
0d70: 4f 55 52 43 45 29 0a 23 20 64 65 66 69 6e 65 20  OURCE).# define 
0d80: 5f 47 4e 55 5f 53 4f 55 52 43 45 0a 23 65 6e 64  _GNU_SOURCE.#end
0d90: 69 66 0a 0a 23 69 66 20 64 65 66 69 6e 65 64 28  if..#if defined(
0da0: 5f 5f 4f 70 65 6e 42 53 44 5f 5f 29 20 26 26 20  __OpenBSD__) && 
0db0: 21 64 65 66 69 6e 65 64 28 5f 42 53 44 5f 53 4f  !defined(_BSD_SO
0dc0: 55 52 43 45 29 0a 23 20 64 65 66 69 6e 65 20 5f  URCE).# define _
0dd0: 42 53 44 5f 53 4f 55 52 43 45 0a 23 65 6e 64 69  BSD_SOURCE.#endi
0de0: 66 0a 0a 2f 2a 0a 2a 2a 20 46 6f 72 20 4d 69 6e  f../*.** For Min
0df0: 47 57 2c 20 63 68 65 63 6b 20 74 6f 20 73 65 65  GW, check to see
0e00: 20 69 66 20 77 65 20 63 61 6e 20 69 6e 63 6c 75   if we can inclu
0e10: 64 65 20 74 68 65 20 68 65 61 64 65 72 20 66 69  de the header fi
0e20: 6c 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69 74  le containing it
0e30: 73 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 69 6e 66  s.** version inf
0e40: 6f 72 6d 61 74 69 6f 6e 2c 20 61 6d 6f 6e 67 20  ormation, among 
0e50: 6f 74 68 65 72 20 74 68 69 6e 67 73 2e 20 20 4e  other things.  N
0e60: 6f 72 6d 61 6c 6c 79 2c 20 74 68 69 73 20 69 6e  ormally, this in
0e70: 74 65 72 6e 61 6c 20 4d 69 6e 47 57 0a 2a 2a 20  ternal MinGW.** 
0e80: 68 65 61 64 65 72 20 66 69 6c 65 20 77 6f 75 6c  header file woul
0e90: 64 20 5b 6f 6e 6c 79 5d 20 62 65 20 69 6e 63 6c  d [only] be incl
0ea0: 75 64 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c  uded automatical
0eb0: 6c 79 20 62 79 20 6f 74 68 65 72 20 4d 69 6e 47  ly by other MinG
0ec0: 57 20 68 65 61 64 65 72 0a 2a 2a 20 66 69 6c 65  W header.** file
0ed0: 73 3b 20 68 6f 77 65 76 65 72 2c 20 74 68 65 20  s; however, the 
0ee0: 63 6f 6e 74 61 69 6e 65 64 20 76 65 72 73 69 6f  contained versio
0ef0: 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73  n information is
0f00: 20 6e 6f 77 20 72 65 71 75 69 72 65 64 20 62 79   now required by
0f10: 20 74 68 69 73 0a 2a 2a 20 68 65 61 64 65 72 20   this.** header 
0f20: 66 69 6c 65 20 74 6f 20 77 6f 72 6b 20 61 72 6f  file to work aro
0f30: 75 6e 64 20 62 69 6e 61 72 79 20 63 6f 6d 70 61  und binary compa
0f40: 74 69 62 69 6c 69 74 79 20 69 73 73 75 65 73 20  tibility issues 
0f50: 28 73 65 65 20 62 65 6c 6f 77 29 20 61 6e 64 0a  (see below) and.
0f60: 2a 2a 20 74 68 69 73 20 69 73 20 74 68 65 20 6f  ** this is the o
0f70: 6e 6c 79 20 6b 6e 6f 77 6e 20 77 61 79 20 74 6f  nly known way to
0f80: 20 72 65 6c 69 61 62 6c 79 20 6f 62 74 61 69 6e   reliably obtain
0f90: 20 69 74 2e 20 20 54 68 69 73 20 65 6e 74 69 72   it.  This entir
0fa0: 65 20 23 69 66 20 62 6c 6f 63 6b 0a 2a 2a 20 77  e #if block.** w
0fb0: 6f 75 6c 64 20 62 65 20 63 6f 6d 70 6c 65 74 65  ould be complete
0fc0: 6c 79 20 75 6e 6e 65 63 65 73 73 61 72 79 20 69  ly unnecessary i
0fd0: 66 20 74 68 65 72 65 20 77 61 73 20 61 6e 79 20  f there was any 
0fe0: 6f 74 68 65 72 20 77 61 79 20 6f 66 20 64 65 74  other way of det
0ff0: 65 63 74 69 6e 67 0a 2a 2a 20 4d 69 6e 47 57 20  ecting.** MinGW 
1000: 76 69 61 20 74 68 65 69 72 20 70 72 65 70 72 6f  via their prepro
1010: 63 65 73 73 6f 72 20 28 65 2e 67 2e 20 69 66 20  cessor (e.g. if 
1020: 74 68 65 79 20 63 75 73 74 6f 6d 69 7a 65 64 20  they customized 
1030: 74 68 65 69 72 20 47 43 43 20 74 6f 20 64 65 66  their GCC to def
1040: 69 6e 65 0a 2a 2a 20 73 6f 6d 65 20 4d 69 6e 47  ine.** some MinG
1050: 57 2d 73 70 65 63 69 66 69 63 20 6d 61 63 72 6f  W-specific macro
1060: 73 29 2e 20 20 57 68 65 6e 20 63 6f 6d 70 69 6c  s).  When compil
1070: 69 6e 67 20 66 6f 72 20 4d 69 6e 47 57 2c 20 65  ing for MinGW, e
1080: 69 74 68 65 72 20 74 68 65 0a 2a 2a 20 5f 48 41  ither the.** _HA
1090: 56 45 5f 4d 49 4e 47 57 5f 48 20 6f 72 20 5f 48  VE_MINGW_H or _H
10a0: 41 56 45 5f 5f 4d 49 4e 47 57 5f 48 20 28 6e 6f  AVE__MINGW_H (no
10b0: 74 65 20 74 68 65 20 65 78 74 72 61 20 75 6e 64  te the extra und
10c0: 65 72 73 63 6f 72 65 29 20 6d 61 63 72 6f 20 6d  erscore) macro m
10d0: 75 73 74 20 62 65 0a 2a 2a 20 64 65 66 69 6e 65  ust be.** define
10e0: 64 3b 20 6f 74 68 65 72 77 69 73 65 2c 20 64 65  d; otherwise, de
10f0: 74 65 63 74 69 6f 6e 20 6f 66 20 63 6f 6e 64 69  tection of condi
1100: 74 69 6f 6e 73 20 73 70 65 63 69 66 69 63 20 74  tions specific t
1110: 6f 20 4d 69 6e 47 57 20 77 69 6c 6c 20 62 65 0a  o MinGW will be.
1120: 2a 2a 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2f 0a  ** disabled..*/.
1130: 23 69 66 20 64 65 66 69 6e 65 64 28 5f 48 41 56  #if defined(_HAV
1140: 45 5f 4d 49 4e 47 57 5f 48 29 0a 23 20 69 6e 63  E_MINGW_H).# inc
1150: 6c 75 64 65 20 22 6d 69 6e 67 77 2e 68 22 0a 23  lude "mingw.h".#
1160: 65 6c 69 66 20 64 65 66 69 6e 65 64 28 5f 48 41  elif defined(_HA
1170: 56 45 5f 5f 4d 49 4e 47 57 5f 48 29 0a 23 20 69  VE__MINGW_H).# i
1180: 6e 63 6c 75 64 65 20 22 5f 6d 69 6e 67 77 2e 68  nclude "_mingw.h
1190: 22 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20  ".#endif../*.** 
11a0: 46 6f 72 20 4d 69 6e 47 57 20 76 65 72 73 69 6f  For MinGW versio
11b0: 6e 20 34 2e 78 20 28 61 6e 64 20 68 69 67 68 65  n 4.x (and highe
11c0: 72 29 2c 20 63 68 65 63 6b 20 74 6f 20 73 65 65  r), check to see
11d0: 20 69 66 20 74 68 65 20 5f 55 53 45 5f 33 32 42   if the _USE_32B
11e0: 49 54 5f 54 49 4d 45 5f 54 0a 2a 2a 20 64 65 66  IT_TIME_T.** def
11f0: 69 6e 65 20 69 73 20 72 65 71 75 69 72 65 64 20  ine is required 
1200: 74 6f 20 6d 61 69 6e 74 61 69 6e 20 62 69 6e 61  to maintain bina
1210: 72 79 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ry compatibility
1220: 20 77 69 74 68 20 74 68 65 20 4d 53 56 43 20 72   with the MSVC r
1230: 75 6e 74 69 6d 65 0a 2a 2a 20 6c 69 62 72 61 72  untime.** librar
1240: 79 20 69 6e 20 75 73 65 20 28 65 2e 67 2e 20 66  y in use (e.g. f
1250: 6f 72 20 57 69 6e 64 6f 77 73 20 58 50 29 2e 0a  or Windows XP)..
1260: 2a 2f 0a 23 69 66 20 21 64 65 66 69 6e 65 64 28  */.#if !defined(
1270: 5f 55 53 45 5f 33 32 42 49 54 5f 54 49 4d 45 5f  _USE_32BIT_TIME_
1280: 54 29 20 26 26 20 21 64 65 66 69 6e 65 64 28 5f  T) && !defined(_
1290: 55 53 45 5f 36 34 42 49 54 5f 54 49 4d 45 5f 54  USE_64BIT_TIME_T
12a0: 29 20 26 26 20 5c 0a 20 20 20 20 64 65 66 69 6e  ) && \.    defin
12b0: 65 64 28 5f 57 49 4e 33 32 29 20 26 26 20 21 64  ed(_WIN32) && !d
12c0: 65 66 69 6e 65 64 28 5f 57 49 4e 36 34 29 20 26  efined(_WIN64) &
12d0: 26 20 5c 0a 20 20 20 20 64 65 66 69 6e 65 64 28  & \.    defined(
12e0: 5f 5f 4d 49 4e 47 57 5f 4d 41 4a 4f 52 5f 56 45  __MINGW_MAJOR_VE
12f0: 52 53 49 4f 4e 29 20 26 26 20 5f 5f 4d 49 4e 47  RSION) && __MING
1300: 57 5f 4d 41 4a 4f 52 5f 56 45 52 53 49 4f 4e 20  W_MAJOR_VERSION 
1310: 3e 3d 20 34 20 26 26 20 5c 0a 20 20 20 20 64 65  >= 4 && \.    de
1320: 66 69 6e 65 64 28 5f 5f 4d 53 56 43 52 54 5f 5f  fined(__MSVCRT__
1330: 29 0a 23 20 64 65 66 69 6e 65 20 5f 55 53 45 5f  ).# define _USE_
1340: 33 32 42 49 54 5f 54 49 4d 45 5f 54 0a 23 65 6e  32BIT_TIME_T.#en
1350: 64 69 66 0a 0a 2f 2a 20 54 68 65 20 70 75 62 6c  dif../* The publ
1360: 69 63 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  ic SQLite interf
1370: 61 63 65 2e 20 20 54 68 65 20 5f 46 49 4c 45 5f  ace.  The _FILE_
1380: 4f 46 46 53 45 54 5f 42 49 54 53 20 6d 61 63 72  OFFSET_BITS macr
1390: 6f 20 6d 75 73 74 20 61 70 70 65 61 72 0a 2a 2a  o must appear.**
13a0: 20 66 69 72 73 74 20 69 6e 20 51 4e 58 2e 20 20   first in QNX.  
13b0: 41 6c 73 6f 2c 20 74 68 65 20 5f 55 53 45 5f 33  Also, the _USE_3
13c0: 32 42 49 54 5f 54 49 4d 45 5f 54 20 6d 61 63 72  2BIT_TIME_T macr
13d0: 6f 20 6d 75 73 74 20 61 70 70 65 61 72 20 66 69  o must appear fi
13e0: 72 73 74 20 66 6f 72 0a 2a 2a 20 4d 69 6e 47 57  rst for.** MinGW
13f0: 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ..*/./**********
1400: 2a 2a 2a 2a 20 49 6e 63 6c 75 64 65 20 73 71 6c  **** Include sql
1410: 69 74 65 33 2e 68 20 69 6e 20 74 68 65 20 6d 69  ite3.h in the mi
1420: 64 64 6c 65 20 6f 66 20 73 71 6c 69 74 65 49 6e  ddle of sqliteIn
1430: 74 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  t.h ************
1440: 2a 2a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ***/./**********
1450: 2a 2a 2a 2a 20 42 65 67 69 6e 20 66 69 6c 65 20  **** Begin file 
1460: 73 71 6c 69 74 65 33 2e 68 20 2a 2a 2a 2a 2a 2a  sqlite3.h ******
1470: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1480: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1490: 2a 2a 2a 2f 0a 2f 2a 0a 2a 2a 20 32 30 30 31 20  ***/./*.** 2001 
14a0: 53 65 70 74 65 6d 62 65 72 20 31 35 0a 2a 2a 0a  September 15.**.
14b0: 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 20 64 69  ** The author di
14c0: 73 63 6c 61 69 6d 73 20 63 6f 70 79 72 69 67 68  sclaims copyrigh
14d0: 74 20 74 6f 20 74 68 69 73 20 73 6f 75 72 63 65  t to this source
14e0: 20 63 6f 64 65 2e 20 20 49 6e 20 70 6c 61 63 65   code.  In place
14f0: 20 6f 66 0a 2a 2a 20 61 20 6c 65 67 61 6c 20 6e   of.** a legal n
1500: 6f 74 69 63 65 2c 20 68 65 72 65 20 69 73 20 61  otice, here is a
1510: 20 62 6c 65 73 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a   blessing:.**.**
1520: 20 20 20 20 4d 61 79 20 79 6f 75 20 64 6f 20 67      May you do g
1530: 6f 6f 64 20 61 6e 64 20 6e 6f 74 20 65 76 69 6c  ood and not evil
1540: 2e 0a 2a 2a 20 20 20 20 4d 61 79 20 79 6f 75 20  ..**    May you 
1550: 66 69 6e 64 20 66 6f 72 67 69 76 65 6e 65 73 73  find forgiveness
1560: 20 66 6f 72 20 79 6f 75 72 73 65 6c 66 20 61 6e   for yourself an
1570: 64 20 66 6f 72 67 69 76 65 20 6f 74 68 65 72 73  d forgive others
1580: 2e 0a 2a 2a 20 20 20 20 4d 61 79 20 79 6f 75 20  ..**    May you 
1590: 73 68 61 72 65 20 66 72 65 65 6c 79 2c 20 6e 65  share freely, ne
15a0: 76 65 72 20 74 61 6b 69 6e 67 20 6d 6f 72 65 20  ver taking more 
15b0: 74 68 61 6e 20 79 6f 75 20 67 69 76 65 2e 0a 2a  than you give..*
15c0: 2a 0a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  *.**************
15d0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
15e0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
15f0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1600: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54  ***********.** T
1610: 68 69 73 20 68 65 61 64 65 72 20 66 69 6c 65 20  his header file 
1620: 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65  defines the inte
1630: 72 66 61 63 65 20 74 68 61 74 20 74 68 65 20 53  rface that the S
1640: 51 4c 69 74 65 20 6c 69 62 72 61 72 79 0a 2a 2a  QLite library.**
1650: 20 70 72 65 73 65 6e 74 73 20 74 6f 20 63 6c 69   presents to cli
1660: 65 6e 74 20 70 72 6f 67 72 61 6d 73 2e 20 20 49  ent programs.  I
1670: 66 20 61 20 43 2d 66 75 6e 63 74 69 6f 6e 2c 20  f a C-function, 
1680: 73 74 72 75 63 74 75 72 65 2c 20 64 61 74 61 74  structure, datat
1690: 79 70 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6e 73 74  ype,.** or const
16a0: 61 6e 74 20 64 65 66 69 6e 69 74 69 6f 6e 20 64  ant definition d
16b0: 6f 65 73 20 6e 6f 74 20 61 70 70 65 61 72 20 69  oes not appear i
16c0: 6e 20 74 68 69 73 20 66 69 6c 65 2c 20 74 68 65  n this file, the
16d0: 6e 20 69 74 20 69 73 0a 2a 2a 20 6e 6f 74 20 61  n it is.** not a
16e0: 20 70 75 62 6c 69 73 68 65 64 20 41 50 49 20 6f   published API o
16f0: 66 20 53 51 4c 69 74 65 2c 20 69 73 20 73 75 62  f SQLite, is sub
1700: 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 77  ject to change w
1710: 69 74 68 6f 75 74 0a 2a 2a 20 6e 6f 74 69 63 65  ithout.** notice
1720: 2c 20 61 6e 64 20 73 68 6f 75 6c 64 20 6e 6f 74  , and should not
1730: 20 62 65 20 72 65 66 65 72 65 6e 63 65 64 20 62   be referenced b
1740: 79 20 70 72 6f 67 72 61 6d 73 20 74 68 61 74 20  y programs that 
1750: 75 73 65 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a  use SQLite..**.*
1760: 2a 20 53 6f 6d 65 20 6f 66 20 74 68 65 20 64 65  * Some of the de
1770: 66 69 6e 69 74 69 6f 6e 73 20 74 68 61 74 20 61  finitions that a
1780: 72 65 20 69 6e 20 74 68 69 73 20 66 69 6c 65 20  re in this file 
1790: 61 72 65 20 6d 61 72 6b 65 64 20 61 73 0a 2a 2a  are marked as.**
17a0: 20 22 65 78 70 65 72 69 6d 65 6e 74 61 6c 22 2e   "experimental".
17b0: 20 20 45 78 70 65 72 69 6d 65 6e 74 61 6c 20 69    Experimental i
17c0: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 6e 6f  nterfaces are no
17d0: 72 6d 61 6c 6c 79 20 6e 65 77 0a 2a 2a 20 66 65  rmally new.** fe
17e0: 61 74 75 72 65 73 20 72 65 63 65 6e 74 6c 79 20  atures recently 
17f0: 61 64 64 65 64 20 74 6f 20 53 51 4c 69 74 65 2e  added to SQLite.
1800: 20 20 57 65 20 64 6f 20 6e 6f 74 20 61 6e 74 69    We do not anti
1810: 63 69 70 61 74 65 20 63 68 61 6e 67 65 73 0a 2a  cipate changes.*
1820: 2a 20 74 6f 20 65 78 70 65 72 69 6d 65 6e 74 61  * to experimenta
1830: 6c 20 69 6e 74 65 72 66 61 63 65 73 20 62 75 74  l interfaces but
1840: 20 72 65 73 65 72 76 65 20 74 68 65 20 72 69 67   reserve the rig
1850: 68 74 20 74 6f 20 6d 61 6b 65 20 6d 69 6e 6f 72  ht to make minor
1860: 20 63 68 61 6e 67 65 73 0a 2a 2a 20 69 66 20 65   changes.** if e
1870: 78 70 65 72 69 65 6e 63 65 20 66 72 6f 6d 20 75  xperience from u
1880: 73 65 20 22 69 6e 20 74 68 65 20 77 69 6c 64 22  se "in the wild"
1890: 20 73 75 67 67 65 73 74 20 73 75 63 68 20 63 68   suggest such ch
18a0: 61 6e 67 65 73 20 61 72 65 20 70 72 75 64 65 6e  anges are pruden
18b0: 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f 66 66  t..**.** The off
18c0: 69 63 69 61 6c 20 43 2d 6c 61 6e 67 75 61 67 65  icial C-language
18d0: 20 41 50 49 20 64 6f 63 75 6d 65 6e 74 61 74 69   API documentati
18e0: 6f 6e 20 66 6f 72 20 53 51 4c 69 74 65 20 69 73  on for SQLite is
18f0: 20 64 65 72 69 76 65 64 0a 2a 2a 20 66 72 6f 6d   derived.** from
1900: 20 63 6f 6d 6d 65 6e 74 73 20 69 6e 20 74 68 69   comments in thi
1910: 73 20 66 69 6c 65 2e 20 20 54 68 69 73 20 66 69  s file.  This fi
1920: 6c 65 20 69 73 20 74 68 65 20 61 75 74 68 6f 72  le is the author
1930: 69 74 61 74 69 76 65 20 73 6f 75 72 63 65 0a 2a  itative source.*
1940: 2a 20 6f 6e 20 68 6f 77 20 53 51 4c 69 74 65 20  * on how SQLite 
1950: 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 73  interfaces are s
1960: 75 70 70 6f 73 65 20 74 6f 20 6f 70 65 72 61 74  uppose to operat
1970: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d  e..**.** The nam
1980: 65 20 6f 66 20 74 68 69 73 20 66 69 6c 65 20 75  e of this file u
1990: 6e 64 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69  nder configurati
19a0: 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 20 69 73  on management is
19b0: 20 22 73 71 6c 69 74 65 2e 68 2e 69 6e 22 2e 0a   "sqlite.h.in"..
19c0: 2a 2a 20 54 68 65 20 6d 61 6b 65 66 69 6c 65 20  ** The makefile 
19d0: 6d 61 6b 65 73 20 73 6f 6d 65 20 6d 69 6e 6f 72  makes some minor
19e0: 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 69 73   changes to this
19f0: 20 66 69 6c 65 20 28 73 75 63 68 20 61 73 20 69   file (such as i
1a00: 6e 73 65 72 74 69 6e 67 0a 2a 2a 20 74 68 65 20  nserting.** the 
1a10: 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 29 20  version number) 
1a20: 61 6e 64 20 63 68 61 6e 67 65 73 20 69 74 73 20  and changes its 
1a30: 6e 61 6d 65 20 74 6f 20 22 73 71 6c 69 74 65 33  name to "sqlite3
1a40: 2e 68 22 20 61 73 0a 2a 2a 20 70 61 72 74 20 6f  .h" as.** part o
1a50: 66 20 74 68 65 20 62 75 69 6c 64 20 70 72 6f 63  f the build proc
1a60: 65 73 73 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20  ess..*/.#ifndef 
1a70: 5f 53 51 4c 49 54 45 33 5f 48 5f 0a 23 64 65 66  _SQLITE3_H_.#def
1a80: 69 6e 65 20 5f 53 51 4c 49 54 45 33 5f 48 5f 0a  ine _SQLITE3_H_.
1a90: 23 69 6e 63 6c 75 64 65 20 3c 73 74 64 61 72 67  #include <stdarg
1aa0: 2e 68 3e 20 20 20 20 20 2f 2a 20 4e 65 65 64 65  .h>     /* Neede
1ab0: 64 20 66 6f 72 20 74 68 65 20 64 65 66 69 6e 69  d for the defini
1ac0: 74 69 6f 6e 20 6f 66 20 76 61 5f 6c 69 73 74 20  tion of va_list 
1ad0: 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 4d 61 6b 65 20 73  */../*.** Make s
1ae0: 75 72 65 20 77 65 20 63 61 6e 20 63 61 6c 6c 20  ure we can call 
1af0: 74 68 69 73 20 73 74 75 66 66 20 66 72 6f 6d 20  this stuff from 
1b00: 43 2b 2b 2e 0a 2a 2f 0a 23 69 66 20 30 0a 65 78  C++..*/.#if 0.ex
1b10: 74 65 72 6e 20 22 43 22 20 7b 0a 23 65 6e 64 69  tern "C" {.#endi
1b20: 66 0a 0a 0a 2f 2a 0a 2a 2a 20 41 64 64 20 74 68  f.../*.** Add th
1b30: 65 20 61 62 69 6c 69 74 79 20 74 6f 20 6f 76 65  e ability to ove
1b40: 72 72 69 64 65 20 27 65 78 74 65 72 6e 27 0a 2a  rride 'extern'.*
1b50: 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45  /.#ifndef SQLITE
1b60: 5f 45 58 54 45 52 4e 0a 23 20 64 65 66 69 6e 65  _EXTERN.# define
1b70: 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20 65   SQLITE_EXTERN e
1b80: 78 74 65 72 6e 0a 23 65 6e 64 69 66 0a 0a 23 69  xtern.#endif..#i
1b90: 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 41 50 49  fndef SQLITE_API
1ba0: 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45  .# define SQLITE
1bb0: 5f 41 50 49 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a  _API.#endif.../*
1bc0: 0a 2a 2a 20 54 68 65 73 65 20 6e 6f 2d 6f 70 20  .** These no-op 
1bd0: 6d 61 63 72 6f 73 20 61 72 65 20 75 73 65 64 20  macros are used 
1be0: 69 6e 20 66 72 6f 6e 74 20 6f 66 20 69 6e 74 65  in front of inte
1bf0: 72 66 61 63 65 73 20 74 6f 20 6d 61 72 6b 20 74  rfaces to mark t
1c00: 68 6f 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63  hose.** interfac
1c10: 65 73 20 61 73 20 65 69 74 68 65 72 20 64 65 70  es as either dep
1c20: 72 65 63 61 74 65 64 20 6f 72 20 65 78 70 65 72  recated or exper
1c30: 69 6d 65 6e 74 61 6c 2e 20 20 4e 65 77 20 61 70  imental.  New ap
1c40: 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68  plications.** sh
1c50: 6f 75 6c 64 20 6e 6f 74 20 75 73 65 20 64 65 70  ould not use dep
1c60: 72 65 63 61 74 65 64 20 69 6e 74 65 72 66 61 63  recated interfac
1c70: 65 73 20 2d 20 74 68 65 79 20 61 72 65 20 73 75  es - they are su
1c80: 70 70 6f 72 74 20 66 6f 72 20 62 61 63 6b 77 61  pport for backwa
1c90: 72 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69  rds.** compatibi
1ca0: 6c 69 74 79 20 6f 6e 6c 79 2e 20 20 41 70 70 6c  lity only.  Appl
1cb0: 69 63 61 74 69 6f 6e 20 77 72 69 74 65 72 73 20  ication writers 
1cc0: 73 68 6f 75 6c 64 20 62 65 20 61 77 61 72 65 20  should be aware 
1cd0: 74 68 61 74 0a 2a 2a 20 65 78 70 65 72 69 6d 65  that.** experime
1ce0: 6e 74 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20  ntal interfaces 
1cf0: 61 72 65 20 73 75 62 6a 65 63 74 20 74 6f 20 63  are subject to c
1d00: 68 61 6e 67 65 20 69 6e 20 70 6f 69 6e 74 20 72  hange in point r
1d10: 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 54  eleases..**.** T
1d20: 68 65 73 65 20 6d 61 63 72 6f 73 20 75 73 65 64  hese macros used
1d30: 20 74 6f 20 72 65 73 6f 6c 76 65 20 74 6f 20 76   to resolve to v
1d40: 61 72 69 6f 75 73 20 6b 69 6e 64 73 20 6f 66 20  arious kinds of 
1d50: 63 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20 74  compiler magic t
1d60: 68 61 74 0a 2a 2a 20 77 6f 75 6c 64 20 67 65 6e  hat.** would gen
1d70: 65 72 61 74 65 20 77 61 72 6e 69 6e 67 20 6d 65  erate warning me
1d80: 73 73 61 67 65 73 20 77 68 65 6e 20 74 68 65 79  ssages when they
1d90: 20 77 65 72 65 20 75 73 65 64 2e 20 20 42 75 74   were used.  But
1da0: 20 74 68 61 74 0a 2a 2a 20 63 6f 6d 70 69 6c 65   that.** compile
1db0: 72 20 6d 61 67 69 63 20 65 6e 64 65 64 20 75 70  r magic ended up
1dc0: 20 67 65 6e 65 72 61 74 69 6e 67 20 73 75 63 68   generating such
1dd0: 20 61 20 66 6c 75 72 72 79 20 6f 66 20 62 75 67   a flurry of bug
1de0: 20 72 65 70 6f 72 74 73 0a 2a 2a 20 74 68 61 74   reports.** that
1df0: 20 77 65 20 68 61 76 65 20 74 61 6b 65 6e 20 69   we have taken i
1e00: 74 20 61 6c 6c 20 6f 75 74 20 61 6e 64 20 67 6f  t all out and go
1e10: 6e 65 20 62 61 63 6b 20 74 6f 20 75 73 69 6e 67  ne back to using
1e20: 20 73 69 6d 70 6c 65 0a 2a 2a 20 6e 6f 6f 70 20   simple.** noop 
1e30: 6d 61 63 72 6f 73 2e 0a 2a 2f 0a 23 64 65 66 69  macros..*/.#defi
1e40: 6e 65 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43  ne SQLITE_DEPREC
1e50: 41 54 45 44 0a 23 64 65 66 69 6e 65 20 53 51 4c  ATED.#define SQL
1e60: 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c  ITE_EXPERIMENTAL
1e70: 0a 0a 2f 2a 0a 2a 2a 20 45 6e 73 75 72 65 20 74  ../*.** Ensure t
1e80: 68 65 73 65 20 73 79 6d 62 6f 6c 73 20 77 65 72  hese symbols wer
1e90: 65 20 6e 6f 74 20 64 65 66 69 6e 65 64 20 62 79  e not defined by
1ea0: 20 73 6f 6d 65 20 70 72 65 76 69 6f 75 73 20 68   some previous h
1eb0: 65 61 64 65 72 20 66 69 6c 65 2e 0a 2a 2f 0a 23  eader file..*/.#
1ec0: 69 66 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52  ifdef SQLITE_VER
1ed0: 53 49 4f 4e 0a 23 20 75 6e 64 65 66 20 53 51 4c  SION.# undef SQL
1ee0: 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23 65 6e 64  ITE_VERSION.#end
1ef0: 69 66 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45  if.#ifdef SQLITE
1f00: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a  _VERSION_NUMBER.
1f10: 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 56  # undef SQLITE_V
1f20: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23 65  ERSION_NUMBER.#e
1f30: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ndif../*.** CAPI
1f40: 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69  3REF: Compile-Ti
1f50: 6d 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69  me Library Versi
1f60: 6f 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 0a 2a 2a  on Numbers.**.**
1f70: 20 5e 28 54 68 65 20 5b 53 51 4c 49 54 45 5f 56   ^(The [SQLITE_V
1f80: 45 52 53 49 4f 4e 5d 20 43 20 70 72 65 70 72 6f  ERSION] C prepro
1f90: 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 69 6e 20  cessor macro in 
1fa0: 74 68 65 20 73 71 6c 69 74 65 33 2e 68 20 68 65  the sqlite3.h he
1fb0: 61 64 65 72 0a 2a 2a 20 65 76 61 6c 75 61 74 65  ader.** evaluate
1fc0: 73 20 74 6f 20 61 20 73 74 72 69 6e 67 20 6c 69  s to a string li
1fd0: 74 65 72 61 6c 20 74 68 61 74 20 69 73 20 74 68  teral that is th
1fe0: 65 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  e SQLite version
1ff0: 20 69 6e 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 61   in the.** forma
2000: 74 20 22 58 2e 59 2e 5a 22 20 77 68 65 72 65 20  t "X.Y.Z" where 
2010: 58 20 69 73 20 74 68 65 20 6d 61 6a 6f 72 20 76  X is the major v
2020: 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 61  ersion number (a
2030: 6c 77 61 79 73 20 33 20 66 6f 72 0a 2a 2a 20 53  lways 3 for.** S
2040: 51 4c 69 74 65 33 29 20 61 6e 64 20 59 20 69 73  QLite3) and Y is
2050: 20 74 68 65 20 6d 69 6e 6f 72 20 76 65 72 73 69   the minor versi
2060: 6f 6e 20 6e 75 6d 62 65 72 20 61 6e 64 20 5a 20  on number and Z 
2070: 69 73 20 74 68 65 20 72 65 6c 65 61 73 65 20 6e  is the release n
2080: 75 6d 62 65 72 2e 29 5e 0a 2a 2a 20 5e 28 54 68  umber.)^.** ^(Th
2090: 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  e [SQLITE_VERSIO
20a0: 4e 5f 4e 55 4d 42 45 52 5d 20 43 20 70 72 65 70  N_NUMBER] C prep
20b0: 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 72  rocessor macro r
20c0: 65 73 6f 6c 76 65 73 20 74 6f 20 61 6e 20 69 6e  esolves to an in
20d0: 74 65 67 65 72 0a 2a 2a 20 77 69 74 68 20 74 68  teger.** with th
20e0: 65 20 76 61 6c 75 65 20 28 58 2a 31 30 30 30 30  e value (X*10000
20f0: 30 30 20 2b 20 59 2a 31 30 30 30 20 2b 20 5a 29  00 + Y*1000 + Z)
2100: 20 77 68 65 72 65 20 58 2c 20 59 2c 20 61 6e 64   where X, Y, and
2110: 20 5a 20 61 72 65 20 74 68 65 20 73 61 6d 65 0a   Z are the same.
2120: 2a 2a 20 6e 75 6d 62 65 72 73 20 75 73 65 64 20  ** numbers used 
2130: 69 6e 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49  in [SQLITE_VERSI
2140: 4f 4e 5d 2e 29 5e 0a 2a 2a 20 54 68 65 20 53 51  ON].)^.** The SQ
2150: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d  LITE_VERSION_NUM
2160: 42 45 52 20 66 6f 72 20 61 6e 79 20 67 69 76 65  BER for any give
2170: 6e 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c  n release of SQL
2180: 69 74 65 20 77 69 6c 6c 20 61 6c 73 6f 0a 2a 2a  ite will also.**
2190: 20 62 65 20 6c 61 72 67 65 72 20 74 68 61 6e 20   be larger than 
21a0: 74 68 65 20 72 65 6c 65 61 73 65 20 66 72 6f 6d  the release from
21b0: 20 77 68 69 63 68 20 69 74 20 69 73 20 64 65 72   which it is der
21c0: 69 76 65 64 2e 20 20 45 69 74 68 65 72 20 59 20  ived.  Either Y 
21d0: 77 69 6c 6c 0a 2a 2a 20 62 65 20 68 65 6c 64 20  will.** be held 
21e0: 63 6f 6e 73 74 61 6e 74 20 61 6e 64 20 5a 20 77  constant and Z w
21f0: 69 6c 6c 20 62 65 20 69 6e 63 72 65 6d 65 6e 74  ill be increment
2200: 65 64 20 6f 72 20 65 6c 73 65 20 59 20 77 69 6c  ed or else Y wil
2210: 6c 20 62 65 20 69 6e 63 72 65 6d 65 6e 74 65 64  l be incremented
2220: 0a 2a 2a 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62  .** and Z will b
2230: 65 20 72 65 73 65 74 20 74 6f 20 7a 65 72 6f 2e  e reset to zero.
2240: 0a 2a 2a 0a 2a 2a 20 53 69 6e 63 65 20 76 65 72  .**.** Since ver
2250: 73 69 6f 6e 20 33 2e 36 2e 31 38 2c 20 53 51 4c  sion 3.6.18, SQL
2260: 69 74 65 20 73 6f 75 72 63 65 20 63 6f 64 65 20  ite source code 
2270: 68 61 73 20 62 65 65 6e 20 73 74 6f 72 65 64 20  has been stored 
2280: 69 6e 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65  in the.** <a hre
2290: 66 3d 22 68 74 74 70 3a 2f 2f 77 77 77 2e 66 6f  f="http://www.fo
22a0: 73 73 69 6c 2d 73 63 6d 2e 6f 72 67 2f 22 3e 46  ssil-scm.org/">F
22b0: 6f 73 73 69 6c 20 63 6f 6e 66 69 67 75 72 61 74  ossil configurat
22c0: 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 0a 2a  ion management.*
22d0: 2a 20 73 79 73 74 65 6d 3c 2f 61 3e 2e 20 20 5e  * system</a>.  ^
22e0: 54 68 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43  The SQLITE_SOURC
22f0: 45 5f 49 44 20 6d 61 63 72 6f 20 65 76 61 6c 75  E_ID macro evalu
2300: 61 74 65 73 20 74 6f 0a 2a 2a 20 61 20 73 74 72  ates to.** a str
2310: 69 6e 67 20 77 68 69 63 68 20 69 64 65 6e 74 69  ing which identi
2320: 66 69 65 73 20 61 20 70 61 72 74 69 63 75 6c 61  fies a particula
2330: 72 20 63 68 65 63 6b 2d 69 6e 20 6f 66 20 53 51  r check-in of SQ
2340: 4c 69 74 65 0a 2a 2a 20 77 69 74 68 69 6e 20 69  Lite.** within i
2350: 74 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ts configuration
2360: 20 6d 61 6e 61 67 65 6d 65 6e 74 20 73 79 73 74   management syst
2370: 65 6d 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45  em.  ^The SQLITE
2380: 5f 53 4f 55 52 43 45 5f 49 44 0a 2a 2a 20 73 74  _SOURCE_ID.** st
2390: 72 69 6e 67 20 63 6f 6e 74 61 69 6e 73 20 74 68  ring contains th
23a0: 65 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20  e date and time 
23b0: 6f 66 20 74 68 65 20 63 68 65 63 6b 2d 69 6e 20  of the check-in 
23c0: 28 55 54 43 29 20 61 6e 64 20 61 6e 20 53 48 41  (UTC) and an SHA
23d0: 31 0a 2a 2a 20 68 61 73 68 20 6f 66 20 74 68 65  1.** hash of the
23e0: 20 65 6e 74 69 72 65 20 73 6f 75 72 63 65 20 74   entire source t
23f0: 72 65 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ree..**.** See a
2400: 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 6c 69  lso: [sqlite3_li
2410: 62 76 65 72 73 69 6f 6e 28 29 5d 2c 0a 2a 2a 20  bversion()],.** 
2420: 5b 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73  [sqlite3_libvers
2430: 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 5d 2c 20 5b  ion_number()], [
2440: 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64  sqlite3_sourceid
2450: 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f  ()],.** [sqlite_
2460: 76 65 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b  version()] and [
2470: 73 71 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64  sqlite_source_id
2480: 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ()]..*/.#define 
2490: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20 20  SQLITE_VERSION  
24a0: 20 20 20 20 20 20 22 33 2e 38 2e 37 22 0a 23 64        "3.8.7".#d
24b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 45 52  efine SQLITE_VER
24c0: 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 33 30 30 38  SION_NUMBER 3008
24d0: 30 30 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  007.#define SQLI
24e0: 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 20 20 20  TE_SOURCE_ID    
24f0: 20 20 22 32 30 31 34 2d 31 30 2d 30 38 20 31 35    "2014-10-08 15
2500: 3a 35 33 3a 32 31 20 36 34 38 33 64 34 32 36 63  :53:21 6483d426c
2510: 34 63 35 63 37 37 32 63 64 34 39 34 31 32 65 61  4c5c772cd49412ea
2520: 33 37 65 30 66 61 37 61 30 33 37 38 39 30 34 22  37e0fa7a0378904"
2530: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2540: 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61  : Run-Time Libra
2550: 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65  ry Version Numbe
2560: 72 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  rs.** KEYWORDS: 
2570: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 2c  sqlite3_version,
2580: 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69   sqlite3_sourcei
2590: 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e  d.**.** These in
25a0: 74 65 72 66 61 63 65 73 20 70 72 6f 76 69 64 65  terfaces provide
25b0: 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d   the same inform
25c0: 61 74 69 6f 6e 20 61 73 20 74 68 65 20 5b 53 51  ation as the [SQ
25d0: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 2c 0a 2a  LITE_VERSION],.*
25e0: 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  * [SQLITE_VERSIO
25f0: 4e 5f 4e 55 4d 42 45 52 5d 2c 20 61 6e 64 20 5b  N_NUMBER], and [
2600: 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44  SQLITE_SOURCE_ID
2610: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C preprocessor
2620: 20 6d 61 63 72 6f 73 0a 2a 2a 20 62 75 74 20 61   macros.** but a
2630: 72 65 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  re associated wi
2640: 74 68 20 74 68 65 20 6c 69 62 72 61 72 79 20 69  th the library i
2650: 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 68 65  nstead of the he
2660: 61 64 65 72 20 66 69 6c 65 2e 20 20 5e 28 43 61  ader file.  ^(Ca
2670: 75 74 69 6f 75 73 0a 2a 2a 20 70 72 6f 67 72 61  utious.** progra
2680: 6d 6d 65 72 73 20 6d 69 67 68 74 20 69 6e 63 6c  mmers might incl
2690: 75 64 65 20 61 73 73 65 72 74 28 29 20 73 74 61  ude assert() sta
26a0: 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 69 72  tements in their
26b0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 0a   application to.
26c0: 2a 2a 20 76 65 72 69 66 79 20 74 68 61 74 20 76  ** verify that v
26d0: 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62  alues returned b
26e0: 79 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63  y these interfac
26f0: 65 73 20 6d 61 74 63 68 20 74 68 65 20 6d 61 63  es match the mac
2700: 72 6f 73 20 69 6e 0a 2a 2a 20 74 68 65 20 68 65  ros in.** the he
2710: 61 64 65 72 2c 20 61 6e 64 20 74 68 75 73 20 69  ader, and thus i
2720: 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20 61  nsure that the a
2730: 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 0a 2a 2a  pplication is.**
2740: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6d   compiled with m
2750: 61 74 63 68 69 6e 67 20 6c 69 62 72 61 72 79 20  atching library 
2760: 61 6e 64 20 68 65 61 64 65 72 20 66 69 6c 65 73  and header files
2770: 2e 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  ..**.** <blockqu
2780: 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 61 73 73  ote><pre>.** ass
2790: 65 72 74 28 20 73 71 6c 69 74 65 33 5f 6c 69 62  ert( sqlite3_lib
27a0: 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29  version_number()
27b0: 3d 3d 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  ==SQLITE_VERSION
27c0: 5f 4e 55 4d 42 45 52 20 29 3b 0a 2a 2a 20 61 73  _NUMBER );.** as
27d0: 73 65 72 74 28 20 73 74 72 63 6d 70 28 73 71 6c  sert( strcmp(sql
27e0: 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29 2c  ite3_sourceid(),
27f0: 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44  SQLITE_SOURCE_ID
2800: 29 3d 3d 30 20 29 3b 0a 2a 2a 20 61 73 73 65 72  )==0 );.** asser
2810: 74 28 20 73 74 72 63 6d 70 28 73 71 6c 69 74 65  t( strcmp(sqlite
2820: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 2c 53  3_libversion(),S
2830: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 29 3d 3d  QLITE_VERSION)==
2840: 30 20 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  0 );.** </pre></
2850: 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a  blockquote>)^.**
2860: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2870: 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e  _version[] strin
2880: 67 20 63 6f 6e 73 74 61 6e 74 20 63 6f 6e 74 61  g constant conta
2890: 69 6e 73 20 74 68 65 20 74 65 78 74 20 6f 66 20  ins the text of 
28a0: 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d  [SQLITE_VERSION]
28b0: 0a 2a 2a 20 6d 61 63 72 6f 2e 20 20 5e 54 68 65  .** macro.  ^The
28c0: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
28d0: 69 6f 6e 28 29 20 66 75 6e 63 74 69 6f 6e 20 72  ion() function r
28e0: 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
28f0: 20 74 6f 20 74 68 65 0a 2a 2a 20 74 6f 20 74 68   to the.** to th
2900: 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f  e sqlite3_versio
2910: 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74  n[] string const
2920: 61 6e 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65  ant.  The sqlite
2930: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 0a 2a  3_libversion().*
2940: 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 72  * function is pr
2950: 6f 76 69 64 65 64 20 66 6f 72 20 75 73 65 20 69  ovided for use i
2960: 6e 20 44 4c 4c 73 20 73 69 6e 63 65 20 44 4c 4c  n DLLs since DLL
2970: 20 75 73 65 72 73 20 75 73 75 61 6c 6c 79 20 64   users usually d
2980: 6f 20 6e 6f 74 20 68 61 76 65 0a 2a 2a 20 64 69  o not have.** di
2990: 72 65 63 74 20 61 63 63 65 73 73 20 74 6f 20 73  rect access to s
29a0: 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 20  tring constants 
29b0: 77 69 74 68 69 6e 20 74 68 65 20 44 4c 4c 2e 20  within the DLL. 
29c0: 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33   ^The.** sqlite3
29d0: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62  _libversion_numb
29e0: 65 72 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65  er() function re
29f0: 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72  turns an integer
2a00: 20 65 71 75 61 6c 20 74 6f 0a 2a 2a 20 5b 53 51   equal to.** [SQ
2a10: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d  LITE_VERSION_NUM
2a20: 42 45 52 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69  BER].  ^The sqli
2a30: 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29 20 66  te3_sourceid() f
2a40: 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
2a50: 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  .** a pointer to
2a60: 20 61 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61   a string consta
2a70: 6e 74 20 77 68 6f 73 65 20 76 61 6c 75 65 20 69  nt whose value i
2a80: 73 20 74 68 65 20 73 61 6d 65 20 61 73 20 74 68  s the same as th
2a90: 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 4f  e .** [SQLITE_SO
2aa0: 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70 72  URCE_ID] C prepr
2ab0: 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 2e 0a 2a  ocessor macro..*
2ac0: 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
2ad0: 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28 29  sqlite_version()
2ae0: 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73 6f  ] and [sqlite_so
2af0: 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a 53  urce_id()]..*/.S
2b00: 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
2b10: 63 68 61 72 20 73 71 6c 69 74 65 33 5f 76 65 72  char sqlite3_ver
2b20: 73 69 6f 6e 5b 5d 20 3d 20 53 51 4c 49 54 45 5f  sion[] = SQLITE_
2b30: 56 45 52 53 49 4f 4e 3b 0a 53 51 4c 49 54 45 5f  VERSION;.SQLITE_
2b40: 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  API const char *
2b50: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
2b60: 6f 6e 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45  on(void);.SQLITE
2b70: 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20  _API const char 
2b80: 2a 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69  *sqlite3_sourcei
2b90: 64 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f  d(void);.SQLITE_
2ba0: 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
2bb0: 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65  libversion_numbe
2bc0: 72 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20  r(void);../*.** 
2bd0: 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69  CAPI3REF: Run-Ti
2be0: 6d 65 20 4c 69 62 72 61 72 79 20 43 6f 6d 70 69  me Library Compi
2bf0: 6c 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 20 44  lation Options D
2c00: 69 61 67 6e 6f 73 74 69 63 73 0a 2a 2a 0a 2a 2a  iagnostics.**.**
2c10: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f   ^The sqlite3_co
2c20: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64  mpileoption_used
2c30: 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  () function retu
2c40: 72 6e 73 20 30 20 6f 72 20 31 20 0a 2a 2a 20 69  rns 0 or 1 .** i
2c50: 6e 64 69 63 61 74 69 6e 67 20 77 68 65 74 68 65  ndicating whethe
2c60: 72 20 74 68 65 20 73 70 65 63 69 66 69 65 64 20  r the specified 
2c70: 6f 70 74 69 6f 6e 20 77 61 73 20 64 65 66 69 6e  option was defin
2c80: 65 64 20 61 74 20 0a 2a 2a 20 63 6f 6d 70 69 6c  ed at .** compil
2c90: 65 20 74 69 6d 65 2e 20 20 5e 54 68 65 20 53 51  e time.  ^The SQ
2ca0: 4c 49 54 45 5f 20 70 72 65 66 69 78 20 6d 61 79  LITE_ prefix may
2cb0: 20 62 65 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d   be omitted from
2cc0: 20 74 68 65 20 0a 2a 2a 20 6f 70 74 69 6f 6e 20   the .** option 
2cd0: 6e 61 6d 65 20 70 61 73 73 65 64 20 74 6f 20 73  name passed to s
2ce0: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
2cf0: 74 69 6f 6e 5f 75 73 65 64 28 29 2e 20 20 0a 2a  tion_used().  .*
2d00: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2d10: 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  3_compileoption_
2d20: 67 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 61  get() function a
2d30: 6c 6c 6f 77 73 20 69 74 65 72 61 74 69 6e 67 0a  llows iterating.
2d40: 2a 2a 20 6f 76 65 72 20 74 68 65 20 6c 69 73 74  ** over the list
2d50: 20 6f 66 20 6f 70 74 69 6f 6e 73 20 74 68 61 74   of options that
2d60: 20 77 65 72 65 20 64 65 66 69 6e 65 64 20 61 74   were defined at
2d70: 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 20 62 79   compile time by
2d80: 0a 2a 2a 20 72 65 74 75 72 6e 69 6e 67 20 74 68  .** returning th
2d90: 65 20 4e 2d 74 68 20 63 6f 6d 70 69 6c 65 20 74  e N-th compile t
2da0: 69 6d 65 20 6f 70 74 69 6f 6e 20 73 74 72 69 6e  ime option strin
2db0: 67 2e 20 20 5e 49 66 20 4e 20 69 73 20 6f 75 74  g.  ^If N is out
2dc0: 20 6f 66 20 72 61 6e 67 65 2c 0a 2a 2a 20 73 71   of range,.** sq
2dd0: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
2de0: 69 6f 6e 5f 67 65 74 28 29 20 72 65 74 75 72 6e  ion_get() return
2df0: 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
2e00: 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 20  .  ^The SQLITE_ 
2e10: 0a 2a 2a 20 70 72 65 66 69 78 20 69 73 20 6f 6d  .** prefix is om
2e20: 69 74 74 65 64 20 66 72 6f 6d 20 61 6e 79 20 73  itted from any s
2e30: 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20  trings returned 
2e40: 62 79 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63  by .** sqlite3_c
2e50: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74  ompileoption_get
2e60: 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 53 75 70 70 6f  ()..**.** ^Suppo
2e70: 72 74 20 66 6f 72 20 74 68 65 20 64 69 61 67 6e  rt for the diagn
2e80: 6f 73 74 69 63 20 66 75 6e 63 74 69 6f 6e 73 20  ostic functions 
2e90: 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f  sqlite3_compileo
2ea0: 70 74 69 6f 6e 5f 75 73 65 64 28 29 0a 2a 2a 20  ption_used().** 
2eb0: 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  and sqlite3_comp
2ec0: 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20  ileoption_get() 
2ed0: 6d 61 79 20 62 65 20 6f 6d 69 74 74 65 64 20 62  may be omitted b
2ee0: 79 20 73 70 65 63 69 66 79 69 6e 67 20 74 68 65  y specifying the
2ef0: 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4d 49   .** [SQLITE_OMI
2f00: 54 5f 43 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f  T_COMPILEOPTION_
2f10: 44 49 41 47 53 5d 20 6f 70 74 69 6f 6e 20 61 74  DIAGS] option at
2f20: 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 0a 2a   compile time..*
2f30: 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 53  *.** See also: S
2f40: 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 5b 73 71  QL functions [sq
2f50: 6c 69 74 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  lite_compileopti
2f60: 6f 6e 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a  on_used()] and.*
2f70: 2a 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70 69 6c  * [sqlite_compil
2f80: 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 5d 20 61  eoption_get()] a
2f90: 6e 64 20 74 68 65 20 5b 63 6f 6d 70 69 6c 65 5f  nd the [compile_
2fa0: 6f 70 74 69 6f 6e 73 20 70 72 61 67 6d 61 5d 2e  options pragma].
2fb0: 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  .*/.#ifndef SQLI
2fc0: 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45 4f  TE_OMIT_COMPILEO
2fd0: 50 54 49 4f 4e 5f 44 49 41 47 53 0a 53 51 4c 49  PTION_DIAGS.SQLI
2fe0: 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
2ff0: 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e  e3_compileoption
3000: 5f 75 73 65 64 28 63 6f 6e 73 74 20 63 68 61 72  _used(const char
3010: 20 2a 7a 4f 70 74 4e 61 6d 65 29 3b 0a 53 51 4c   *zOptName);.SQL
3020: 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68  ITE_API const ch
3030: 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6d 70  ar *sqlite3_comp
3040: 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 69 6e  ileoption_get(in
3050: 74 20 4e 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a  t N);.#endif../*
3060: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65  .** CAPI3REF: Te
3070: 73 74 20 54 6f 20 53 65 65 20 49 66 20 54 68 65  st To See If The
3080: 20 4c 69 62 72 61 72 79 20 49 73 20 54 68 72 65   Library Is Thre
3090: 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e 54 68  adsafe.**.** ^Th
30a0: 65 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64  e sqlite3_thread
30b0: 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e 20  safe() function 
30c0: 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 69 66 20  returns zero if 
30d0: 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 53  and only if.** S
30e0: 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70 69 6c  QLite was compil
30f0: 65 64 20 77 69 74 68 20 6d 75 74 65 78 69 6e 67  ed with mutexing
3100: 20 63 6f 64 65 20 6f 6d 69 74 74 65 64 20 64 75   code omitted du
3110: 65 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  e to the.** [SQL
3120: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20  ITE_THREADSAFE] 
3130: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
3140: 69 6f 6e 20 62 65 69 6e 67 20 73 65 74 20 74 6f  ion being set to
3150: 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65   0..**.** SQLite
3160: 20 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c 65 64   can be compiled
3170: 20 77 69 74 68 20 6f 72 20 77 69 74 68 6f 75 74   with or without
3180: 20 6d 75 74 65 78 65 73 2e 20 20 57 68 65 6e 0a   mutexes.  When.
3190: 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** the [SQLITE_T
31a0: 48 52 45 41 44 53 41 46 45 5d 20 43 20 70 72 65  HREADSAFE] C pre
31b0: 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20  processor macro 
31c0: 69 73 20 31 20 6f 72 20 32 2c 20 6d 75 74 65 78  is 1 or 2, mutex
31d0: 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65  es.** are enable
31e0: 64 20 61 6e 64 20 53 51 4c 69 74 65 20 69 73 20  d and SQLite is 
31f0: 74 68 72 65 61 64 73 61 66 65 2e 20 20 57 68 65  threadsafe.  Whe
3200: 6e 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  n the.** [SQLITE
3210: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d 61 63  _THREADSAFE] mac
3220: 72 6f 20 69 73 20 30 2c 20 0a 2a 2a 20 74 68 65  ro is 0, .** the
3230: 20 6d 75 74 65 78 65 73 20 61 72 65 20 6f 6d 69   mutexes are omi
3240: 74 74 65 64 2e 20 20 57 69 74 68 6f 75 74 20 74  tted.  Without t
3250: 68 65 20 6d 75 74 65 78 65 73 2c 20 69 74 20 69  he mutexes, it i
3260: 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20 74 6f  s not safe.** to
3270: 20 75 73 65 20 53 51 4c 69 74 65 20 63 6f 6e 63   use SQLite conc
3280: 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20 6d 6f  urrently from mo
3290: 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 68 72 65  re than one thre
32a0: 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62 6c 69  ad..**.** Enabli
32b0: 6e 67 20 6d 75 74 65 78 65 73 20 69 6e 63 75 72  ng mutexes incur
32c0: 73 20 61 20 6d 65 61 73 75 72 61 62 6c 65 20 70  s a measurable p
32d0: 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e 61 6c  erformance penal
32e0: 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73 70 65  ty..** So if spe
32f0: 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73 74 20  ed is of utmost 
3300: 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74 20 6d  importance, it m
3310: 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20 64 69  akes sense to di
3320: 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d 75 74  sable.** the mut
3330: 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72 20 6d  exes.  But for m
3340: 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c 20 6d  aximum safety, m
3350: 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20 62 65  utexes should be
3360: 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 5e 54 68   enabled..** ^Th
3370: 65 20 64 65 66 61 75 6c 74 20 62 65 68 61 76 69  e default behavi
3380: 6f 72 20 69 73 20 66 6f 72 20 6d 75 74 65 78 65  or is for mutexe
3390: 73 20 74 6f 20 62 65 20 65 6e 61 62 6c 65 64 2e  s to be enabled.
33a0: 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65  .**.** This inte
33b0: 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65  rface can be use
33c0: 64 20 62 79 20 61 6e 20 61 70 70 6c 69 63 61 74  d by an applicat
33d0: 69 6f 6e 20 74 6f 20 6d 61 6b 65 20 73 75 72 65  ion to make sure
33e0: 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 76 65 72   that the.** ver
33f0: 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65 20 74  sion of SQLite t
3400: 68 61 74 20 69 74 20 69 73 20 6c 69 6e 6b 69 6e  hat it is linkin
3410: 67 20 61 67 61 69 6e 73 74 20 77 61 73 20 63 6f  g against was co
3420: 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74  mpiled with.** t
3430: 68 65 20 64 65 73 69 72 65 64 20 73 65 74 74 69  he desired setti
3440: 6e 67 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54  ng of the [SQLIT
3450: 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d 61  E_THREADSAFE] ma
3460: 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  cro..**.** This 
3470: 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79 20 72  interface only r
3480: 65 70 6f 72 74 73 20 6f 6e 20 74 68 65 20 63 6f  eports on the co
3490: 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74 65 78  mpile-time mutex
34a0: 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66 20 74   setting.** of t
34b0: 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
34c0: 44 53 41 46 45 5d 20 66 6c 61 67 2e 20 20 49 66  DSAFE] flag.  If
34d0: 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
34e0: 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53 51 4c 49  led with.** SQLI
34f0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31 20  TE_THREADSAFE=1 
3500: 6f 72 20 3d 32 20 74 68 65 6e 20 6d 75 74 65 78  or =2 then mutex
3510: 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20 62  es are enabled b
3520: 79 20 64 65 66 61 75 6c 74 20 62 75 74 0a 2a 2a  y default but.**
3530: 20 63 61 6e 20 62 65 20 66 75 6c 6c 79 20 6f 72   can be fully or
3540: 20 70 61 72 74 69 61 6c 6c 79 20 64 69 73 61 62   partially disab
3550: 6c 65 64 20 75 73 69 6e 67 20 61 20 63 61 6c 6c  led using a call
3560: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e   to [sqlite3_con
3570: 66 69 67 28 29 5d 0a 2a 2a 20 77 69 74 68 20 74  fig()].** with t
3580: 68 65 20 76 65 72 62 73 20 5b 53 51 4c 49 54 45  he verbs [SQLITE
3590: 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
35a0: 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 43  READ], [SQLITE_C
35b0: 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
35c0: 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54  D],.** or [SQLIT
35d0: 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 2e  E_CONFIG_MUTEX].
35e0: 20 20 5e 28 54 68 65 20 72 65 74 75 72 6e 20 76    ^(The return v
35f0: 61 6c 75 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73  alue of the.** s
3600: 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66  qlite3_threadsaf
3610: 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f  e() function sho
3620: 77 73 20 6f 6e 6c 79 20 74 68 65 20 63 6f 6d 70  ws only the comp
3630: 69 6c 65 2d 74 69 6d 65 20 73 65 74 74 69 6e 67  ile-time setting
3640: 20 6f 66 0a 2a 2a 20 74 68 72 65 61 64 20 73 61   of.** thread sa
3650: 66 65 74 79 2c 20 6e 6f 74 20 61 6e 79 20 72 75  fety, not any ru
3660: 6e 2d 74 69 6d 65 20 63 68 61 6e 67 65 73 20 74  n-time changes t
3670: 6f 20 74 68 61 74 20 73 65 74 74 69 6e 67 20 6d  o that setting m
3680: 61 64 65 20 62 79 0a 2a 2a 20 73 71 6c 69 74 65  ade by.** sqlite
3690: 33 5f 63 6f 6e 66 69 67 28 29 2e 20 49 6e 20 6f  3_config(). In o
36a0: 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20  ther words, the 
36b0: 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f  return value fro
36c0: 6d 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64  m sqlite3_thread
36d0: 73 61 66 65 28 29 0a 2a 2a 20 69 73 20 75 6e 63  safe().** is unc
36e0: 68 61 6e 67 65 64 20 62 79 20 63 61 6c 6c 73 20  hanged by calls 
36f0: 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  to sqlite3_confi
3700: 67 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65  g().)^.**.** See
3710: 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20   the [threading 
3720: 6d 6f 64 65 5d 20 64 6f 63 75 6d 65 6e 74 61 74  mode] documentat
3730: 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  ion for addition
3740: 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  al information..
3750: 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
3760: 74 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64  t sqlite3_thread
3770: 73 61 66 65 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a  safe(void);../*.
3780: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74  ** CAPI3REF: Dat
3790: 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e  abase Connection
37a0: 20 48 61 6e 64 6c 65 0a 2a 2a 20 4b 45 59 57 4f   Handle.** KEYWO
37b0: 52 44 53 3a 20 7b 64 61 74 61 62 61 73 65 20 63  RDS: {database c
37c0: 6f 6e 6e 65 63 74 69 6f 6e 7d 20 7b 64 61 74 61  onnection} {data
37d0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
37e0: 7d 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f 70 65  }.**.** Each ope
37f0: 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 61 73  n SQLite databas
3800: 65 20 69 73 20 72 65 70 72 65 73 65 6e 74 65 64  e is represented
3810: 20 62 79 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   by a pointer to
3820: 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 0a   an instance of.
3830: 2a 2a 20 74 68 65 20 6f 70 61 71 75 65 20 73 74  ** the opaque st
3840: 72 75 63 74 75 72 65 20 6e 61 6d 65 64 20 22 73  ructure named "s
3850: 71 6c 69 74 65 33 22 2e 20 20 49 74 20 69 73 20  qlite3".  It is 
3860: 75 73 65 66 75 6c 20 74 6f 20 74 68 69 6e 6b 20  useful to think 
3870: 6f 66 20 61 6e 20 73 71 6c 69 74 65 33 0a 2a 2a  of an sqlite3.**
3880: 20 70 6f 69 6e 74 65 72 20 61 73 20 61 6e 20 6f   pointer as an o
3890: 62 6a 65 63 74 2e 20 20 54 68 65 20 5b 73 71 6c  bject.  The [sql
38a0: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
38b0: 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
38c0: 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  , and.** [sqlite
38d0: 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74  3_open_v2()] int
38e0: 65 72 66 61 63 65 73 20 61 72 65 20 69 74 73 20  erfaces are its 
38f0: 63 6f 6e 73 74 72 75 63 74 6f 72 73 2c 20 61 6e  constructors, an
3900: 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  d [sqlite3_close
3910: 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69  ()].** and [sqli
3920: 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 5d 20  te3_close_v2()] 
3930: 61 72 65 20 69 74 73 20 64 65 73 74 72 75 63 74  are its destruct
3940: 6f 72 73 2e 20 20 54 68 65 72 65 20 61 72 65 20  ors.  There are 
3950: 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 69 6e  many other.** in
3960: 74 65 72 66 61 63 65 73 20 28 73 75 63 68 20 61  terfaces (such a
3970: 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  s.** [sqlite3_pr
3980: 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71  epare_v2()], [sq
3990: 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
39a0: 63 74 69 6f 6e 28 29 5d 2c 20 61 6e 64 0a 2a 2a  ction()], and.**
39b0: 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74   [sqlite3_busy_t
39c0: 69 6d 65 6f 75 74 28 29 5d 20 74 6f 20 6e 61 6d  imeout()] to nam
39d0: 65 20 62 75 74 20 74 68 72 65 65 29 20 74 68 61  e but three) tha
39e0: 74 20 61 72 65 20 6d 65 74 68 6f 64 73 20 6f 6e  t are methods on
39f0: 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 20 6f   an.** sqlite3 o
3a00: 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79 70 65 64 65  bject..*/.typede
3a10: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
3a20: 20 73 71 6c 69 74 65 33 3b 0a 0a 2f 2a 0a 2a 2a   sqlite3;../*.**
3a30: 20 43 41 50 49 33 52 45 46 3a 20 36 34 2d 42 69   CAPI3REF: 64-Bi
3a40: 74 20 49 6e 74 65 67 65 72 20 54 79 70 65 73 0a  t Integer Types.
3a50: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c  ** KEYWORDS: sql
3a60: 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  ite_int64 sqlite
3a70: 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a 2a 20 42 65  _uint64.**.** Be
3a80: 63 61 75 73 65 20 74 68 65 72 65 20 69 73 20 6e  cause there is n
3a90: 6f 20 63 72 6f 73 73 2d 70 6c 61 74 66 6f 72 6d  o cross-platform
3aa0: 20 77 61 79 20 74 6f 20 73 70 65 63 69 66 79 20   way to specify 
3ab0: 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20 74  64-bit integer t
3ac0: 79 70 65 73 0a 2a 2a 20 53 51 4c 69 74 65 20 69  ypes.** SQLite i
3ad0: 6e 63 6c 75 64 65 73 20 74 79 70 65 64 65 66 73  ncludes typedefs
3ae0: 20 66 6f 72 20 36 34 2d 62 69 74 20 73 69 67 6e   for 64-bit sign
3af0: 65 64 20 61 6e 64 20 75 6e 73 69 67 6e 65 64 20  ed and unsigned 
3b00: 69 6e 74 65 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  integers..**.** 
3b10: 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  The sqlite3_int6
3b20: 34 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 75 69  4 and sqlite3_ui
3b30: 6e 74 36 34 20 61 72 65 20 74 68 65 20 70 72 65  nt64 are the pre
3b40: 66 65 72 72 65 64 20 74 79 70 65 20 64 65 66 69  ferred type defi
3b50: 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20 54 68 65 20  nitions..** The 
3b60: 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 61 6e 64  sqlite_int64 and
3b70: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 20 74   sqlite_uint64 t
3b80: 79 70 65 73 20 61 72 65 20 73 75 70 70 6f 72 74  ypes are support
3b90: 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73  ed for backwards
3ba0: 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  .** compatibilit
3bb0: 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54  y only..**.** ^T
3bc0: 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  he sqlite3_int64
3bd0: 20 61 6e 64 20 73 71 6c 69 74 65 5f 69 6e 74 36   and sqlite_int6
3be0: 34 20 74 79 70 65 73 20 63 61 6e 20 73 74 6f 72  4 types can stor
3bf0: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73  e integer values
3c00: 0a 2a 2a 20 62 65 74 77 65 65 6e 20 2d 39 32 32  .** between -922
3c10: 33 33 37 32 30 33 36 38 35 34 37 37 35 38 30 38  3372036854775808
3c20: 20 61 6e 64 20 2b 39 32 32 33 33 37 32 30 33 36   and +9223372036
3c30: 38 35 34 37 37 35 38 30 37 20 69 6e 63 6c 75 73  854775807 inclus
3c40: 69 76 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71  ive.  ^The.** sq
3c50: 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 61 6e 64  lite3_uint64 and
3c60: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 20 74   sqlite_uint64 t
3c70: 79 70 65 73 20 63 61 6e 20 73 74 6f 72 65 20 69  ypes can store i
3c80: 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 0a 2a  nteger values .*
3c90: 2a 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20  * between 0 and 
3ca0: 2b 31 38 34 34 36 37 34 34 30 37 33 37 30 39 35  +184467440737095
3cb0: 35 31 36 31 35 20 69 6e 63 6c 75 73 69 76 65 2e  51615 inclusive.
3cc0: 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54  .*/.#ifdef SQLIT
3cd0: 45 5f 49 4e 54 36 34 5f 54 59 50 45 0a 20 20 74  E_INT64_TYPE.  t
3ce0: 79 70 65 64 65 66 20 53 51 4c 49 54 45 5f 49 4e  ypedef SQLITE_IN
3cf0: 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74 65 5f  T64_TYPE sqlite_
3d00: 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66  int64;.  typedef
3d10: 20 75 6e 73 69 67 6e 65 64 20 53 51 4c 49 54 45   unsigned SQLITE
3d20: 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69  _INT64_TYPE sqli
3d30: 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 69 66  te_uint64;.#elif
3d40: 20 64 65 66 69 6e 65 64 28 5f 4d 53 43 5f 56 45   defined(_MSC_VE
3d50: 52 29 20 7c 7c 20 64 65 66 69 6e 65 64 28 5f 5f  R) || defined(__
3d60: 42 4f 52 4c 41 4e 44 43 5f 5f 29 0a 20 20 74 79  BORLANDC__).  ty
3d70: 70 65 64 65 66 20 5f 5f 69 6e 74 36 34 20 73 71  pedef __int64 sq
3d80: 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79  lite_int64;.  ty
3d90: 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 5f  pedef unsigned _
3da0: 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69  _int64 sqlite_ui
3db0: 6e 74 36 34 3b 0a 23 65 6c 73 65 0a 20 20 74 79  nt64;.#else.  ty
3dc0: 70 65 64 65 66 20 6c 6f 6e 67 20 6c 6f 6e 67 20  pedef long long 
3dd0: 69 6e 74 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  int sqlite_int64
3de0: 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73 69  ;.  typedef unsi
3df0: 67 6e 65 64 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69  gned long long i
3e00: 6e 74 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  nt sqlite_uint64
3e10: 3b 0a 23 65 6e 64 69 66 0a 74 79 70 65 64 65 66  ;.#endif.typedef
3e20: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71   sqlite_int64 sq
3e30: 6c 69 74 65 33 5f 69 6e 74 36 34 3b 0a 74 79 70  lite3_int64;.typ
3e40: 65 64 65 66 20 73 71 6c 69 74 65 5f 75 69 6e 74  edef sqlite_uint
3e50: 36 34 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  64 sqlite3_uint6
3e60: 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49 66 20 63 6f 6d  4;../*.** If com
3e70: 70 69 6c 69 6e 67 20 66 6f 72 20 61 20 70 72 6f  piling for a pro
3e80: 63 65 73 73 6f 72 20 74 68 61 74 20 6c 61 63 6b  cessor that lack
3e90: 73 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  s floating point
3ea0: 20 73 75 70 70 6f 72 74 2c 0a 2a 2a 20 73 75 62   support,.** sub
3eb0: 73 74 69 74 75 74 65 20 69 6e 74 65 67 65 72 20  stitute integer 
3ec0: 66 6f 72 20 66 6c 6f 61 74 69 6e 67 2d 70 6f 69  for floating-poi
3ed0: 6e 74 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51  nt..*/.#ifdef SQ
3ee0: 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c 4f 41 54 49  LITE_OMIT_FLOATI
3ef0: 4e 47 5f 50 4f 49 4e 54 0a 23 20 64 65 66 69 6e  NG_POINT.# defin
3f00: 65 20 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33  e double sqlite3
3f10: 5f 69 6e 74 36 34 0a 23 65 6e 64 69 66 0a 0a 2f  _int64.#endif../
3f20: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
3f30: 6c 6f 73 69 6e 67 20 41 20 44 61 74 61 62 61 73  losing A Databas
3f40: 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a  e Connection.**.
3f50: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
3f60: 63 6c 6f 73 65 28 29 20 61 6e 64 20 73 71 6c 69  close() and sqli
3f70: 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 72  te3_close_v2() r
3f80: 6f 75 74 69 6e 65 73 20 61 72 65 20 64 65 73 74  outines are dest
3f90: 72 75 63 74 6f 72 73 0a 2a 2a 20 66 6f 72 20 74  ructors.** for t
3fa0: 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a  he [sqlite3] obj
3fb0: 65 63 74 2e 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74  ect..** ^Calls t
3fc0: 6f 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28  o sqlite3_close(
3fd0: 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c  ) and sqlite3_cl
3fe0: 6f 73 65 5f 76 32 28 29 20 72 65 74 75 72 6e 20  ose_v2() return 
3ff0: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 0a 2a  [SQLITE_OK] if.*
4000: 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20  * the [sqlite3] 
4010: 6f 62 6a 65 63 74 20 69 73 20 73 75 63 63 65 73  object is succes
4020: 73 66 75 6c 6c 79 20 64 65 73 74 72 6f 79 65 64  sfully destroyed
4030: 20 61 6e 64 20 61 6c 6c 20 61 73 73 6f 63 69 61   and all associa
4040: 74 65 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 73  ted.** resources
4050: 20 61 72 65 20 64 65 61 6c 6c 6f 63 61 74 65 64   are deallocated
4060: 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
4070: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
4080: 69 6f 6e 20 69 73 20 61 73 73 6f 63 69 61 74 65  ion is associate
4090: 64 20 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a  d with unfinaliz
40a0: 65 64 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73  ed prepared.** s
40b0: 74 61 74 65 6d 65 6e 74 73 20 6f 72 20 75 6e 66  tatements or unf
40c0: 69 6e 69 73 68 65 64 20 73 71 6c 69 74 65 33 5f  inished sqlite3_
40d0: 62 61 63 6b 75 70 20 6f 62 6a 65 63 74 73 20 74  backup objects t
40e0: 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  hen sqlite3_clos
40f0: 65 28 29 0a 2a 2a 20 77 69 6c 6c 20 6c 65 61 76  e().** will leav
4100: 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  e the database c
4110: 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 20 61  onnection open a
4120: 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  nd return [SQLIT
4130: 45 5f 42 55 53 59 5d 2e 0a 2a 2a 20 5e 49 66 20  E_BUSY]..** ^If 
4140: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32  sqlite3_close_v2
4150: 28 29 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74  () is called wit
4160: 68 20 75 6e 66 69 6e 61 6c 69 7a 65 64 20 70 72  h unfinalized pr
4170: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
4180: 73 0a 2a 2a 20 61 6e 64 2f 6f 72 20 75 6e 66 69  s.** and/or unfi
4190: 6e 69 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62  nished sqlite3_b
41a0: 61 63 6b 75 70 73 2c 20 74 68 65 6e 20 74 68 65  ackups, then the
41b0: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
41c0: 74 69 6f 6e 20 62 65 63 6f 6d 65 73 0a 2a 2a 20  tion becomes.** 
41d0: 61 6e 20 75 6e 75 73 61 62 6c 65 20 22 7a 6f 6d  an unusable "zom
41e0: 62 69 65 22 20 77 68 69 63 68 20 77 69 6c 6c 20  bie" which will 
41f0: 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 65  automatically be
4200: 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 77 68 65   deallocated whe
4210: 6e 20 74 68 65 0a 2a 2a 20 6c 61 73 74 20 70 72  n the.** last pr
4220: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
4230: 20 69 73 20 66 69 6e 61 6c 69 7a 65 64 20 6f 72   is finalized or
4240: 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65   the last sqlite
4250: 33 5f 62 61 63 6b 75 70 20 69 73 0a 2a 2a 20 66  3_backup is.** f
4260: 69 6e 69 73 68 65 64 2e 20 20 54 68 65 20 73 71  inished.  The sq
4270: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29  lite3_close_v2()
4280: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 69 6e   interface is in
4290: 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 77  tended for use w
42a0: 69 74 68 0a 2a 2a 20 68 6f 73 74 20 6c 61 6e 67  ith.** host lang
42b0: 75 61 67 65 73 20 74 68 61 74 20 61 72 65 20 67  uages that are g
42c0: 61 72 62 61 67 65 20 63 6f 6c 6c 65 63 74 65 64  arbage collected
42d0: 2c 20 61 6e 64 20 77 68 65 72 65 20 74 68 65 20  , and where the 
42e0: 6f 72 64 65 72 20 69 6e 20 77 68 69 63 68 0a 2a  order in which.*
42f0: 2a 20 64 65 73 74 72 75 63 74 6f 72 73 20 61 72  * destructors ar
4300: 65 20 63 61 6c 6c 65 64 20 69 73 20 61 72 62 69  e called is arbi
4310: 74 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 41 70 70  trary..**.** App
4320: 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64  lications should
4330: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
4340: 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 5d 20 61  ze | finalize] a
4350: 6c 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ll [prepared sta
4360: 74 65 6d 65 6e 74 73 5d 2c 0a 2a 2a 20 5b 73 71  tements],.** [sq
4370: 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65  lite3_blob_close
4380: 20 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42   | close] all [B
4390: 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61 6e  LOB handles], an
43a0: 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  d .** [sqlite3_b
43b0: 61 63 6b 75 70 5f 66 69 6e 69 73 68 20 7c 20 66  ackup_finish | f
43c0: 69 6e 69 73 68 5d 20 61 6c 6c 20 5b 73 71 6c 69  inish] all [sqli
43d0: 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65  te3_backup] obje
43e0: 63 74 73 20 61 73 73 6f 63 69 61 74 65 64 0a 2a  cts associated.*
43f0: 2a 20 77 69 74 68 20 74 68 65 20 5b 73 71 6c 69  * with the [sqli
4400: 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 72 69 6f  te3] object prio
4410: 72 20 74 6f 20 61 74 74 65 6d 70 74 69 6e 67 20  r to attempting 
4420: 74 6f 20 63 6c 6f 73 65 20 74 68 65 20 6f 62 6a  to close the obj
4430: 65 63 74 2e 20 20 5e 49 66 0a 2a 2a 20 73 71 6c  ect.  ^If.** sql
4440: 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20  ite3_close_v2() 
4450: 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b  is called on a [
4460: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
4470: 69 6f 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c 20  ion] that still 
4480: 68 61 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64 69  has.** outstandi
4490: 6e 67 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ng [prepared sta
44a0: 74 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20  tements], [BLOB 
44b0: 68 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 2f 6f 72  handles], and/or
44c0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63  .** [sqlite3_bac
44d0: 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20 74 68 65  kup] objects the
44e0: 6e 20 69 74 20 72 65 74 75 72 6e 73 20 5b 53 51  n it returns [SQ
44f0: 4c 49 54 45 5f 4f 4b 5d 20 61 6e 64 20 74 68 65  LITE_OK] and the
4500: 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a   deallocation.**
4510: 20 6f 66 20 72 65 73 6f 75 72 63 65 73 20 69 73   of resources is
4520: 20 64 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20   deferred until 
4530: 61 6c 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74  all [prepared st
4540: 61 74 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42  atements], [BLOB
4550: 20 68 61 6e 64 6c 65 73 5d 2c 0a 2a 2a 20 61 6e   handles],.** an
4560: 64 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75  d [sqlite3_backu
4570: 70 5d 20 6f 62 6a 65 63 74 73 20 61 72 65 20 61  p] objects are a
4580: 6c 73 6f 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a  lso destroyed..*
4590: 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 5b 73 71 6c  *.** ^If an [sql
45a0: 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20  ite3] object is 
45b0: 64 65 73 74 72 6f 79 65 64 20 77 68 69 6c 65 20  destroyed while 
45c0: 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73  a transaction is
45d0: 20 6f 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72   open,.** the tr
45e0: 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74  ansaction is aut
45f0: 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65  omatically rolle
4600: 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68  d back..**.** Th
4610: 65 20 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f  e C parameter to
4620: 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28   [sqlite3_close(
4630: 43 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  C)] and [sqlite3
4640: 5f 63 6c 6f 73 65 5f 76 32 28 43 29 5d 0a 2a 2a  _close_v2(C)].**
4650: 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20   must be either 
4660: 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65  a NULL.** pointe
4670: 72 20 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33  r or an [sqlite3
4680: 5d 20 6f 62 6a 65 63 74 20 70 6f 69 6e 74 65 72  ] object pointer
4690: 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f   obtained.** fro
46a0: 6d 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  m [sqlite3_open(
46b0: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
46c0: 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73  n16()], or.** [s
46d0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
46e0: 5d 2c 20 61 6e 64 20 6e 6f 74 20 70 72 65 76 69  ], and not previ
46f0: 6f 75 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a  ously closed..**
4700: 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65   ^Calling sqlite
4710: 33 5f 63 6c 6f 73 65 28 29 20 6f 72 20 73 71 6c  3_close() or sql
4720: 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20  ite3_close_v2() 
4730: 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  with a NULL poin
4740: 74 65 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  ter.** argument 
4750: 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f  is a harmless no
4760: 2d 6f 70 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  -op..*/.SQLITE_A
4770: 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  PI int sqlite3_c
4780: 6c 6f 73 65 28 73 71 6c 69 74 65 33 2a 29 3b 0a  lose(sqlite3*);.
4790: 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
47a0: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28  qlite3_close_v2(
47b0: 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
47c0: 2a 20 54 68 65 20 74 79 70 65 20 66 6f 72 20 61  * The type for a
47d0: 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
47e0: 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 6c  on..** This is l
47f0: 65 67 61 63 79 20 61 6e 64 20 64 65 70 72 65 63  egacy and deprec
4800: 61 74 65 64 2e 20 20 49 74 20 69 73 20 69 6e 63  ated.  It is inc
4810: 6c 75 64 65 64 20 66 6f 72 20 68 69 73 74 6f 72  luded for histor
4820: 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61 74 69 62  ical.** compatib
4830: 69 6c 69 74 79 20 61 6e 64 20 69 73 20 6e 6f 74  ility and is not
4840: 20 64 6f 63 75 6d 65 6e 74 65 64 2e 0a 2a 2f 0a   documented..*/.
4850: 74 79 70 65 64 65 66 20 69 6e 74 20 28 2a 73 71  typedef int (*sq
4860: 6c 69 74 65 33 5f 63 61 6c 6c 62 61 63 6b 29 28  lite3_callback)(
4870: 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a  void*,int,char**
4880: 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f 2a 0a 2a  , char**);../*.*
4890: 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 6e 65 2d  * CAPI3REF: One-
48a0: 53 74 65 70 20 51 75 65 72 79 20 45 78 65 63 75  Step Query Execu
48b0: 74 69 6f 6e 20 49 6e 74 65 72 66 61 63 65 0a 2a  tion Interface.*
48c0: 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
48d0: 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66 61 63  _exec() interfac
48e0: 65 20 69 73 20 61 20 63 6f 6e 76 65 6e 69 65 6e  e is a convenien
48f0: 63 65 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e  ce wrapper aroun
4900: 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  d.** [sqlite3_pr
4910: 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71  epare_v2()], [sq
4920: 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 61  lite3_step()], a
4930: 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  nd [sqlite3_fina
4940: 6c 69 7a 65 28 29 5d 2c 0a 2a 2a 20 74 68 61 74  lize()],.** that
4950: 20 61 6c 6c 6f 77 73 20 61 6e 20 61 70 70 6c 69   allows an appli
4960: 63 61 74 69 6f 6e 20 74 6f 20 72 75 6e 20 6d 75  cation to run mu
4970: 6c 74 69 70 6c 65 20 73 74 61 74 65 6d 65 6e 74  ltiple statement
4980: 73 20 6f 66 20 53 51 4c 0a 2a 2a 20 77 69 74 68  s of SQL.** with
4990: 6f 75 74 20 68 61 76 69 6e 67 20 74 6f 20 75 73  out having to us
49a0: 65 20 61 20 6c 6f 74 20 6f 66 20 43 20 63 6f 64  e a lot of C cod
49b0: 65 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  e. .**.** ^The s
49c0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 6e  qlite3_exec() in
49d0: 74 65 72 66 61 63 65 20 72 75 6e 73 20 7a 65 72  terface runs zer
49e0: 6f 20 6f 72 20 6d 6f 72 65 20 55 54 46 2d 38 20  o or more UTF-8 
49f0: 65 6e 63 6f 64 65 64 2c 0a 2a 2a 20 73 65 6d 69  encoded,.** semi
4a00: 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 20 53  colon-separate S
4a10: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 70 61  QL statements pa
4a20: 73 73 65 64 20 69 6e 74 6f 20 69 74 73 20 32 6e  ssed into its 2n
4a30: 64 20 61 72 67 75 6d 65 6e 74 2c 0a 2a 2a 20 69  d argument,.** i
4a40: 6e 20 74 68 65 20 63 6f 6e 74 65 78 74 20 6f 66  n the context of
4a50: 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
4a60: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 61 73 73 65  onnection] passe
4a70: 64 20 69 6e 20 61 73 20 69 74 73 20 31 73 74 0a  d in as its 1st.
4a80: 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 49  ** argument.  ^I
4a90: 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 66  f the callback f
4aa0: 75 6e 63 74 69 6f 6e 20 6f 66 20 74 68 65 20 33  unction of the 3
4ab0: 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a  rd argument to.*
4ac0: 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  * sqlite3_exec()
4ad0: 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68   is not NULL, th
4ae0: 65 6e 20 69 74 20 69 73 20 69 6e 76 6f 6b 65 64  en it is invoked
4af0: 20 66 6f 72 20 65 61 63 68 20 72 65 73 75 6c 74   for each result
4b00: 20 72 6f 77 0a 2a 2a 20 63 6f 6d 69 6e 67 20 6f   row.** coming o
4b10: 75 74 20 6f 66 20 74 68 65 20 65 76 61 6c 75 61  ut of the evalua
4b20: 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ted SQL statemen
4b30: 74 73 2e 20 20 5e 54 68 65 20 34 74 68 20 61 72  ts.  ^The 4th ar
4b40: 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c  gument to.** sql
4b50: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 72  ite3_exec() is r
4b60: 65 6c 61 79 65 64 20 74 68 72 6f 75 67 68 20 74  elayed through t
4b70: 6f 20 74 68 65 20 31 73 74 20 61 72 67 75 6d 65  o the 1st argume
4b80: 6e 74 20 6f 66 20 65 61 63 68 0a 2a 2a 20 63 61  nt of each.** ca
4b90: 6c 6c 62 61 63 6b 20 69 6e 76 6f 63 61 74 69 6f  llback invocatio
4ba0: 6e 2e 20 20 5e 49 66 20 74 68 65 20 63 61 6c 6c  n.  ^If the call
4bb0: 62 61 63 6b 20 70 6f 69 6e 74 65 72 20 74 6f 20  back pointer to 
4bc0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a  sqlite3_exec().*
4bd0: 2a 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20  * is NULL, then 
4be0: 6e 6f 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 65  no callback is e
4bf0: 76 65 72 20 69 6e 76 6f 6b 65 64 20 61 6e 64 20  ver invoked and 
4c00: 72 65 73 75 6c 74 20 72 6f 77 73 20 61 72 65 0a  result rows are.
4c10: 2a 2a 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a  ** ignored..**.*
4c20: 2a 20 5e 49 66 20 61 6e 20 65 72 72 6f 72 20 6f  * ^If an error o
4c30: 63 63 75 72 73 20 77 68 69 6c 65 20 65 76 61 6c  ccurs while eval
4c40: 75 61 74 69 6e 67 20 74 68 65 20 53 51 4c 20 73  uating the SQL s
4c50: 74 61 74 65 6d 65 6e 74 73 20 70 61 73 73 65 64  tatements passed
4c60: 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33   into.** sqlite3
4c70: 5f 65 78 65 63 28 29 2c 20 74 68 65 6e 20 65 78  _exec(), then ex
4c80: 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 20 63  ecution of the c
4c90: 75 72 72 65 6e 74 20 73 74 61 74 65 6d 65 6e 74  urrent statement
4ca0: 20 73 74 6f 70 73 20 61 6e 64 0a 2a 2a 20 73 75   stops and.** su
4cb0: 62 73 65 71 75 65 6e 74 20 73 74 61 74 65 6d 65  bsequent stateme
4cc0: 6e 74 73 20 61 72 65 20 73 6b 69 70 70 65 64 2e  nts are skipped.
4cd0: 20 20 5e 49 66 20 74 68 65 20 35 74 68 20 70 61    ^If the 5th pa
4ce0: 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
4cf0: 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73 20  e3_exec().** is 
4d00: 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 61 6e  not NULL then an
4d10: 79 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  y error message 
4d20: 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  is written into 
4d30: 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 0a  memory obtained.
4d40: 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ** from [sqlite3
4d50: 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 70  _malloc()] and p
4d60: 61 73 73 65 64 20 62 61 63 6b 20 74 68 72 6f 75  assed back throu
4d70: 67 68 20 74 68 65 20 35 74 68 20 70 61 72 61 6d  gh the 5th param
4d80: 65 74 65 72 2e 0a 2a 2a 20 54 6f 20 61 76 6f 69  eter..** To avoi
4d90: 64 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 73 2c 20  d memory leaks, 
4da0: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
4db0: 73 68 6f 75 6c 64 20 69 6e 76 6f 6b 65 20 5b 73  should invoke [s
4dc0: 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 0a 2a  qlite3_free()].*
4dd0: 2a 20 6f 6e 20 65 72 72 6f 72 20 6d 65 73 73 61  * on error messa
4de0: 67 65 20 73 74 72 69 6e 67 73 20 72 65 74 75 72  ge strings retur
4df0: 6e 65 64 20 74 68 72 6f 75 67 68 20 74 68 65 20  ned through the 
4e00: 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f 66  5th parameter of
4e10: 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 65  .** of sqlite3_e
4e20: 78 65 63 28 29 20 61 66 74 65 72 20 74 68 65 20  xec() after the 
4e30: 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74  error message st
4e40: 72 69 6e 67 20 69 73 20 6e 6f 20 6c 6f 6e 67 65  ring is no longe
4e50: 72 20 6e 65 65 64 65 64 2e 0a 2a 2a 20 5e 49 66  r needed..** ^If
4e60: 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74   the 5th paramet
4e70: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
4e80: 65 63 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  ec() is not NULL
4e90: 20 61 6e 64 20 6e 6f 20 65 72 72 6f 72 73 0a 2a   and no errors.*
4ea0: 2a 20 6f 63 63 75 72 2c 20 74 68 65 6e 20 73 71  * occur, then sq
4eb0: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 73 65 74  lite3_exec() set
4ec0: 73 20 74 68 65 20 70 6f 69 6e 74 65 72 20 69 6e  s the pointer in
4ed0: 20 69 74 73 20 35 74 68 20 70 61 72 61 6d 65 74   its 5th paramet
4ee0: 65 72 20 74 6f 0a 2a 2a 20 4e 55 4c 4c 20 62 65  er to.** NULL be
4ef0: 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a  fore returning..
4f00: 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 73 71 6c  **.** ^If an sql
4f10: 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c  ite3_exec() call
4f20: 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e  back returns non
4f30: 2d 7a 65 72 6f 2c 20 74 68 65 20 73 71 6c 69 74  -zero, the sqlit
4f40: 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 72 6f 75  e3_exec().** rou
4f50: 74 69 6e 65 20 72 65 74 75 72 6e 73 20 53 51 4c  tine returns SQL
4f60: 49 54 45 5f 41 42 4f 52 54 20 77 69 74 68 6f 75  ITE_ABORT withou
4f70: 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 63  t invoking the c
4f80: 61 6c 6c 62 61 63 6b 20 61 67 61 69 6e 20 61 6e  allback again an
4f90: 64 0a 2a 2a 20 77 69 74 68 6f 75 74 20 72 75 6e  d.** without run
4fa0: 6e 69 6e 67 20 61 6e 79 20 73 75 62 73 65 71 75  ning any subsequ
4fb0: 65 6e 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ent SQL statemen
4fc0: 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 32  ts..**.** ^The 2
4fd0: 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  nd argument to t
4fe0: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  he sqlite3_exec(
4ff0: 29 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  ) callback funct
5000: 69 6f 6e 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75  ion is the.** nu
5010: 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
5020: 69 6e 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20  in the result.  
5030: 5e 54 68 65 20 33 72 64 20 61 72 67 75 6d 65 6e  ^The 3rd argumen
5040: 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  t to the sqlite3
5050: 5f 65 78 65 63 28 29 0a 2a 2a 20 63 61 6c 6c 62  _exec().** callb
5060: 61 63 6b 20 69 73 20 61 6e 20 61 72 72 61 79 20  ack is an array 
5070: 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73  of pointers to s
5080: 74 72 69 6e 67 73 20 6f 62 74 61 69 6e 65 64 20  trings obtained 
5090: 61 73 20 69 66 20 66 72 6f 6d 0a 2a 2a 20 5b 73  as if from.** [s
50a0: 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
50b0: 78 74 28 29 5d 2c 20 6f 6e 65 20 66 6f 72 20 65  xt()], one for e
50c0: 61 63 68 20 63 6f 6c 75 6d 6e 2e 20 20 5e 49 66  ach column.  ^If
50d0: 20 61 6e 20 65 6c 65 6d 65 6e 74 20 6f 66 20 61   an element of a
50e0: 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 69  .** result row i
50f0: 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20  s NULL then the 
5100: 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 73 74  corresponding st
5110: 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 66 6f 72  ring pointer for
5120: 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   the.** sqlite3_
5130: 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20  exec() callback 
5140: 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
5150: 72 2e 20 20 5e 54 68 65 20 34 74 68 20 61 72 67  r.  ^The 4th arg
5160: 75 6d 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20  ument to the.** 
5170: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63  sqlite3_exec() c
5180: 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 61 72  allback is an ar
5190: 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20  ray of pointers 
51a0: 74 6f 20 73 74 72 69 6e 67 73 20 77 68 65 72 65  to strings where
51b0: 20 65 61 63 68 0a 2a 2a 20 65 6e 74 72 79 20 72   each.** entry r
51c0: 65 70 72 65 73 65 6e 74 73 20 74 68 65 20 6e 61  epresents the na
51d0: 6d 65 20 6f 66 20 63 6f 72 72 65 73 70 6f 6e 64  me of correspond
51e0: 69 6e 67 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  ing result colum
51f0: 6e 20 61 73 20 6f 62 74 61 69 6e 65 64 0a 2a 2a  n as obtained.**
5200: 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63   from [sqlite3_c
5210: 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 5d 2e 0a 2a  olumn_name()]..*
5220: 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 32 6e 64  *.** ^If the 2nd
5230: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
5240: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20  lite3_exec() is 
5250: 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  a NULL pointer, 
5260: 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20  a pointer.** to 
5270: 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c  an empty string,
5280: 20 6f 72 20 61 20 70 6f 69 6e 74 65 72 20 74 68   or a pointer th
5290: 61 74 20 63 6f 6e 74 61 69 6e 73 20 6f 6e 6c 79  at contains only
52a0: 20 77 68 69 74 65 73 70 61 63 65 20 61 6e 64 2f   whitespace and/
52b0: 6f 72 20 0a 2a 2a 20 53 51 4c 20 63 6f 6d 6d 65  or .** SQL comme
52c0: 6e 74 73 2c 20 74 68 65 6e 20 6e 6f 20 53 51 4c  nts, then no SQL
52d0: 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20   statements are 
52e0: 65 76 61 6c 75 61 74 65 64 20 61 6e 64 20 74 68  evaluated and th
52f0: 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 73  e database.** is
5300: 20 6e 6f 74 20 63 68 61 6e 67 65 64 2e 0a 2a 2a   not changed..**
5310: 0a 2a 2a 20 52 65 73 74 72 69 63 74 69 6f 6e 73  .** Restrictions
5320: 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
5330: 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61  <li> The applica
5340: 74 69 6f 6e 20 6d 75 73 74 20 69 6e 73 75 72 65  tion must insure
5350: 20 74 68 61 74 20 74 68 65 20 31 73 74 20 70 61   that the 1st pa
5360: 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
5370: 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 20 20 20  e3_exec().**    
5380: 20 20 69 73 20 61 20 76 61 6c 69 64 20 61 6e 64    is a valid and
5390: 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20   open [database 
53a0: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20  connection]..** 
53b0: 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61  <li> The applica
53c0: 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 63 6c  tion must not cl
53d0: 6f 73 65 20 74 68 65 20 5b 64 61 74 61 62 61 73  ose the [databas
53e0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70  e connection] sp
53f0: 65 63 69 66 69 65 64 20 62 79 0a 2a 2a 20 20 20  ecified by.**   
5400: 20 20 20 74 68 65 20 31 73 74 20 70 61 72 61 6d     the 1st param
5410: 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
5420: 65 78 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c  exec() while sql
5430: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 72  ite3_exec() is r
5440: 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 6c 69 3e 20  unning..** <li> 
5450: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
5460: 6d 75 73 74 20 6e 6f 74 20 6d 6f 64 69 66 79 20  must not modify 
5470: 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
5480: 74 20 74 65 78 74 20 70 61 73 73 65 64 20 69 6e  t text passed in
5490: 74 6f 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 32  to.**      the 2
54a0: 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  nd parameter of 
54b0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77  sqlite3_exec() w
54c0: 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65  hile sqlite3_exe
54d0: 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  c() is running..
54e0: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 53 51 4c 49  ** </ul>.*/.SQLI
54f0: 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
5500: 65 33 5f 65 78 65 63 28 0a 20 20 73 71 6c 69 74  e3_exec(.  sqlit
5510: 65 33 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20  e3*,            
5520: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
5530: 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e        /* An open
5540: 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63   database */.  c
5550: 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 2c 20  onst char *sql, 
5560: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
5570: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c            /* SQL
5580: 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64   to be evaluated
5590: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c   */.  int (*call
55a0: 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c  back)(void*,int,
55b0: 63 68 61 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20  char**,char**), 
55c0: 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e   /* Callback fun
55d0: 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20  ction */.  void 
55e0: 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  *,              
55f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
5600: 20 20 20 20 20 20 2f 2a 20 31 73 74 20 61 72 67        /* 1st arg
5610: 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63  ument to callbac
5620: 6b 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72  k */.  char **er
5630: 72 6d 73 67 20 20 20 20 20 20 20 20 20 20 20 20  rmsg            
5640: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
5650: 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77    /* Error msg w
5660: 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29  ritten here */.)
5670: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
5680: 46 3a 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a  F: Result Codes.
5690: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 72 65  ** KEYWORDS: {re
56a0: 73 75 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69  sult code defini
56b0: 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e  tions}.**.** Man
56c0: 79 20 53 51 4c 69 74 65 20 66 75 6e 63 74 69 6f  y SQLite functio
56d0: 6e 73 20 72 65 74 75 72 6e 20 61 6e 20 69 6e 74  ns return an int
56e0: 65 67 65 72 20 72 65 73 75 6c 74 20 63 6f 64 65  eger result code
56f0: 20 66 72 6f 6d 20 74 68 65 20 73 65 74 20 73 68   from the set sh
5700: 6f 77 6e 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f  own.** here in o
5710: 72 64 65 72 20 74 6f 20 69 6e 64 69 63 61 74 65  rder to indicate
5720: 20 73 75 63 63 65 73 73 20 6f 72 20 66 61 69 6c   success or fail
5730: 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65  ure..**.** New e
5740: 72 72 6f 72 20 63 6f 64 65 73 20 6d 61 79 20 62  rror codes may b
5750: 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
5760: 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
5770: 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  Lite..**.** See 
5780: 61 6c 73 6f 3a 20 5b 65 78 74 65 6e 64 65 64 20  also: [extended 
5790: 72 65 73 75 6c 74 20 63 6f 64 65 20 64 65 66 69  result code defi
57a0: 6e 69 74 69 6f 6e 73 5d 0a 2a 2f 0a 23 64 65 66  nitions].*/.#def
57b0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20  ine SQLITE_OK   
57c0: 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20 53          0   /* S
57d0: 75 63 63 65 73 73 66 75 6c 20 72 65 73 75 6c 74  uccessful result
57e0: 20 2a 2f 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67   */./* beginning
57f0: 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20  -of-error-codes 
5800: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5810: 45 5f 45 52 52 4f 52 20 20 20 20 20 20 20 20 31  E_ERROR        1
5820: 20 20 20 2f 2a 20 53 51 4c 20 65 72 72 6f 72 20     /* SQL error 
5830: 6f 72 20 6d 69 73 73 69 6e 67 20 64 61 74 61 62  or missing datab
5840: 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ase */.#define S
5850: 51 4c 49 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20  QLITE_INTERNAL  
5860: 20 20 20 32 20 20 20 2f 2a 20 49 6e 74 65 72 6e     2   /* Intern
5870: 61 6c 20 6c 6f 67 69 63 20 65 72 72 6f 72 20 69  al logic error i
5880: 6e 20 53 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66  n SQLite */.#def
5890: 69 6e 65 20 53 51 4c 49 54 45 5f 50 45 52 4d 20  ine SQLITE_PERM 
58a0: 20 20 20 20 20 20 20 20 33 20 20 20 2f 2a 20 41          3   /* A
58b0: 63 63 65 73 73 20 70 65 72 6d 69 73 73 69 6f 6e  ccess permission
58c0: 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69   denied */.#defi
58d0: 6e 65 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20  ne SQLITE_ABORT 
58e0: 20 20 20 20 20 20 20 34 20 20 20 2f 2a 20 43 61         4   /* Ca
58f0: 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 72  llback routine r
5900: 65 71 75 65 73 74 65 64 20 61 6e 20 61 62 6f 72  equested an abor
5910: 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
5920: 49 54 45 5f 42 55 53 59 20 20 20 20 20 20 20 20  ITE_BUSY        
5930: 20 35 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61   5   /* The data
5940: 62 61 73 65 20 66 69 6c 65 20 69 73 20 6c 6f 63  base file is loc
5950: 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ked */.#define S
5960: 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20  QLITE_LOCKED    
5970: 20 20 20 36 20 20 20 2f 2a 20 41 20 74 61 62 6c     6   /* A tabl
5980: 65 20 69 6e 20 74 68 65 20 64 61 74 61 62 61 73  e in the databas
5990: 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23  e is locked */.#
59a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
59b0: 4d 45 4d 20 20 20 20 20 20 20 20 37 20 20 20 2f  MEM        7   /
59c0: 2a 20 41 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69  * A malloc() fai
59d0: 6c 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  led */.#define S
59e0: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20  QLITE_READONLY  
59f0: 20 20 20 38 20 20 20 2f 2a 20 41 74 74 65 6d 70     8   /* Attemp
5a00: 74 20 74 6f 20 77 72 69 74 65 20 61 20 72 65 61  t to write a rea
5a10: 64 6f 6e 6c 79 20 64 61 74 61 62 61 73 65 20 2a  donly database *
5a20: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5a30: 5f 49 4e 54 45 52 52 55 50 54 20 20 20 20 39 20  _INTERRUPT    9 
5a40: 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74    /* Operation t
5a50: 65 72 6d 69 6e 61 74 65 64 20 62 79 20 73 71 6c  erminated by sql
5a60: 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
5a70: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5a80: 45 5f 49 4f 45 52 52 20 20 20 20 20 20 20 31 30  E_IOERR       10
5a90: 20 20 20 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20     /* Some kind 
5aa0: 6f 66 20 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f  of disk I/O erro
5ab0: 72 20 6f 63 63 75 72 72 65 64 20 2a 2f 0a 23 64  r occurred */.#d
5ac0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52  efine SQLITE_COR
5ad0: 52 55 50 54 20 20 20 20 20 31 31 20 20 20 2f 2a  RUPT     11   /*
5ae0: 20 54 68 65 20 64 61 74 61 62 61 73 65 20 64 69   The database di
5af0: 73 6b 20 69 6d 61 67 65 20 69 73 20 6d 61 6c 66  sk image is malf
5b00: 6f 72 6d 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  ormed */.#define
5b10: 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44   SQLITE_NOTFOUND
5b20: 20 20 20 20 31 32 20 20 20 2f 2a 20 55 6e 6b 6e      12   /* Unkn
5b30: 6f 77 6e 20 6f 70 63 6f 64 65 20 69 6e 20 73 71  own opcode in sq
5b40: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
5b50: 6f 6c 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ol() */.#define 
5b60: 53 51 4c 49 54 45 5f 46 55 4c 4c 20 20 20 20 20  SQLITE_FULL     
5b70: 20 20 20 31 33 20 20 20 2f 2a 20 49 6e 73 65 72     13   /* Inser
5b80: 74 69 6f 6e 20 66 61 69 6c 65 64 20 62 65 63 61  tion failed beca
5b90: 75 73 65 20 64 61 74 61 62 61 73 65 20 69 73 20  use database is 
5ba0: 66 75 6c 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20  full */.#define 
5bb0: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20  SQLITE_CANTOPEN 
5bc0: 20 20 20 31 34 20 20 20 2f 2a 20 55 6e 61 62 6c     14   /* Unabl
5bd0: 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61  e to open the da
5be0: 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23  tabase file */.#
5bf0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52  define SQLITE_PR
5c00: 4f 54 4f 43 4f 4c 20 20 20 20 31 35 20 20 20 2f  OTOCOL    15   /
5c10: 2a 20 44 61 74 61 62 61 73 65 20 6c 6f 63 6b 20  * Database lock 
5c20: 70 72 6f 74 6f 63 6f 6c 20 65 72 72 6f 72 20 2a  protocol error *
5c30: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5c40: 5f 45 4d 50 54 59 20 20 20 20 20 20 20 31 36 20  _EMPTY       16 
5c50: 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 69 73    /* Database is
5c60: 20 65 6d 70 74 79 20 2a 2f 0a 23 64 65 66 69 6e   empty */.#defin
5c70: 65 20 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 20  e SQLITE_SCHEMA 
5c80: 20 20 20 20 20 31 37 20 20 20 2f 2a 20 54 68 65       17   /* The
5c90: 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61   database schema
5ca0: 20 63 68 61 6e 67 65 64 20 2a 2f 0a 23 64 65 66   changed */.#def
5cb0: 69 6e 65 20 53 51 4c 49 54 45 5f 54 4f 4f 42 49  ine SQLITE_TOOBI
5cc0: 47 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20 53  G      18   /* S
5cd0: 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 65 78  tring or BLOB ex
5ce0: 63 65 65 64 73 20 73 69 7a 65 20 6c 69 6d 69 74  ceeds size limit
5cf0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5d00: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 20 31  TE_CONSTRAINT  1
5d10: 39 20 20 20 2f 2a 20 41 62 6f 72 74 20 64 75 65  9   /* Abort due
5d20: 20 74 6f 20 63 6f 6e 73 74 72 61 69 6e 74 20 76   to constraint v
5d30: 69 6f 6c 61 74 69 6f 6e 20 2a 2f 0a 23 64 65 66  iolation */.#def
5d40: 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 4d 41  ine SQLITE_MISMA
5d50: 54 43 48 20 20 20 20 32 30 20 20 20 2f 2a 20 44  TCH    20   /* D
5d60: 61 74 61 20 74 79 70 65 20 6d 69 73 6d 61 74 63  ata type mismatc
5d70: 68 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  h */.#define SQL
5d80: 49 54 45 5f 4d 49 53 55 53 45 20 20 20 20 20 20  ITE_MISUSE      
5d90: 32 31 20 20 20 2f 2a 20 4c 69 62 72 61 72 79 20  21   /* Library 
5da0: 75 73 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79  used incorrectly
5db0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5dc0: 54 45 5f 4e 4f 4c 46 53 20 20 20 20 20 20 20 32  TE_NOLFS       2
5dd0: 32 20 20 20 2f 2a 20 55 73 65 73 20 4f 53 20 66  2   /* Uses OS f
5de0: 65 61 74 75 72 65 73 20 6e 6f 74 20 73 75 70 70  eatures not supp
5df0: 6f 72 74 65 64 20 6f 6e 20 68 6f 73 74 20 2a 2f  orted on host */
5e00: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5e10: 41 55 54 48 20 20 20 20 20 20 20 20 32 33 20 20  AUTH        23  
5e20: 20 2f 2a 20 41 75 74 68 6f 72 69 7a 61 74 69 6f   /* Authorizatio
5e30: 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66  n denied */.#def
5e40: 69 6e 65 20 53 51 4c 49 54 45 5f 46 4f 52 4d 41  ine SQLITE_FORMA
5e50: 54 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20 41  T      24   /* A
5e60: 75 78 69 6c 69 61 72 79 20 64 61 74 61 62 61 73  uxiliary databas
5e70: 65 20 66 6f 72 6d 61 74 20 65 72 72 6f 72 20 2a  e format error *
5e80: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5e90: 5f 52 41 4e 47 45 20 20 20 20 20 20 20 32 35 20  _RANGE       25 
5ea0: 20 20 2f 2a 20 32 6e 64 20 70 61 72 61 6d 65 74    /* 2nd paramet
5eb0: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  er to sqlite3_bi
5ec0: 6e 64 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20  nd out of range 
5ed0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5ee0: 45 5f 4e 4f 54 41 44 42 20 20 20 20 20 20 32 36  E_NOTADB      26
5ef0: 20 20 20 2f 2a 20 46 69 6c 65 20 6f 70 65 6e 65     /* File opene
5f00: 64 20 74 68 61 74 20 69 73 20 6e 6f 74 20 61 20  d that is not a 
5f10: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f  database file */
5f20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5f30: 4e 4f 54 49 43 45 20 20 20 20 20 20 32 37 20 20  NOTICE      27  
5f40: 20 2f 2a 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e   /* Notification
5f50: 73 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c  s from sqlite3_l
5f60: 6f 67 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  og() */.#define 
5f70: 53 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47 20 20  SQLITE_WARNING  
5f80: 20 20 20 32 38 20 20 20 2f 2a 20 57 61 72 6e 69     28   /* Warni
5f90: 6e 67 73 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ngs from sqlite3
5fa0: 5f 6c 6f 67 28 29 20 2a 2f 0a 23 64 65 66 69 6e  _log() */.#defin
5fb0: 65 20 53 51 4c 49 54 45 5f 52 4f 57 20 20 20 20  e SQLITE_ROW    
5fc0: 20 20 20 20 20 31 30 30 20 20 2f 2a 20 73 71 6c       100  /* sql
5fd0: 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73 20  ite3_step() has 
5fe0: 61 6e 6f 74 68 65 72 20 72 6f 77 20 72 65 61 64  another row read
5ff0: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
6000: 49 54 45 5f 44 4f 4e 45 20 20 20 20 20 20 20 20  ITE_DONE        
6010: 31 30 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f  101  /* sqlite3_
6020: 73 74 65 70 28 29 20 68 61 73 20 66 69 6e 69 73  step() has finis
6030: 68 65 64 20 65 78 65 63 75 74 69 6e 67 20 2a 2f  hed executing */
6040: 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72 72 6f 72  ./* end-of-error
6050: 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  -codes */../*.**
6060: 20 43 41 50 49 33 52 45 46 3a 20 45 78 74 65 6e   CAPI3REF: Exten
6070: 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73  ded Result Codes
6080: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65  .** KEYWORDS: {e
6090: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
60a0: 6f 64 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 7d  ode definitions}
60b0: 0a 2a 2a 0a 2a 2a 20 49 6e 20 69 74 73 20 64 65  .**.** In its de
60c0: 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74  fault configurat
60d0: 69 6f 6e 2c 20 53 51 4c 69 74 65 20 41 50 49 20  ion, SQLite API 
60e0: 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
60f0: 6f 6e 65 20 6f 66 20 33 30 20 69 6e 74 65 67 65  one of 30 intege
6100: 72 0a 2a 2a 20 5b 72 65 73 75 6c 74 20 63 6f 64  r.** [result cod
6110: 65 73 5d 2e 20 20 48 6f 77 65 76 65 72 2c 20 65  es].  However, e
6120: 78 70 65 72 69 65 6e 63 65 20 68 61 73 20 73 68  xperience has sh
6130: 6f 77 6e 20 74 68 61 74 20 6d 61 6e 79 20 6f 66  own that many of
6140: 0a 2a 2a 20 74 68 65 73 65 20 72 65 73 75 6c 74  .** these result
6150: 20 63 6f 64 65 73 20 61 72 65 20 74 6f 6f 20 63   codes are too c
6160: 6f 61 72 73 65 2d 67 72 61 69 6e 65 64 2e 20 20  oarse-grained.  
6170: 54 68 65 79 20 64 6f 20 6e 6f 74 20 70 72 6f 76  They do not prov
6180: 69 64 65 20 61 73 0a 2a 2a 20 6d 75 63 68 20 69  ide as.** much i
6190: 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74  nformation about
61a0: 20 70 72 6f 62 6c 65 6d 73 20 61 73 20 70 72 6f   problems as pro
61b0: 67 72 61 6d 6d 65 72 73 20 6d 69 67 68 74 20 6c  grammers might l
61c0: 69 6b 65 2e 20 20 49 6e 20 61 6e 20 65 66 66 6f  ike.  In an effo
61d0: 72 74 20 74 6f 0a 2a 2a 20 61 64 64 72 65 73 73  rt to.** address
61e0: 20 74 68 69 73 2c 20 6e 65 77 65 72 20 76 65 72   this, newer ver
61f0: 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20  sions of SQLite 
6200: 28 76 65 72 73 69 6f 6e 20 33 2e 33 2e 38 20 61  (version 3.3.8 a
6210: 6e 64 20 6c 61 74 65 72 29 20 69 6e 63 6c 75 64  nd later) includ
6220: 65 0a 2a 2a 20 73 75 70 70 6f 72 74 20 66 6f 72  e.** support for
6230: 20 61 64 64 69 74 69 6f 6e 61 6c 20 72 65 73 75   additional resu
6240: 6c 74 20 63 6f 64 65 73 20 74 68 61 74 20 70 72  lt codes that pr
6250: 6f 76 69 64 65 20 6d 6f 72 65 20 64 65 74 61 69  ovide more detai
6260: 6c 65 64 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a  led information.
6270: 2a 2a 20 61 62 6f 75 74 20 65 72 72 6f 72 73 2e  ** about errors.
6280: 20 54 68 65 73 65 20 5b 65 78 74 65 6e 64 65 64   These [extended
6290: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 61   result codes] a
62a0: 72 65 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69  re enabled or di
62b0: 73 61 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70  sabled.** on a p
62c0: 65 72 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  er database conn
62d0: 65 63 74 69 6f 6e 20 62 61 73 69 73 20 75 73 69  ection basis usi
62e0: 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ng the.** [sqlit
62f0: 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75  e3_extended_resu
6300: 6c 74 5f 63 6f 64 65 73 28 29 5d 20 41 50 49 2e  lt_codes()] API.
6310: 20 20 4f 72 2c 20 74 68 65 20 65 78 74 65 6e 64    Or, the extend
6320: 65 64 20 63 6f 64 65 20 66 6f 72 0a 2a 2a 20 74  ed code for.** t
6330: 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65  he most recent e
6340: 72 72 6f 72 20 63 61 6e 20 62 65 20 6f 62 74 61  rror can be obta
6350: 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  ined using.** [s
6360: 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
6370: 65 72 72 63 6f 64 65 28 29 5d 2e 0a 2a 2f 0a 23  errcode()]..*/.#
6380: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
6390: 45 52 52 5f 52 45 41 44 20 20 20 20 20 20 20 20  ERR_READ        
63a0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
63b0: 45 52 52 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64  ERR | (1<<8)).#d
63c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
63d0: 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 20 20  RR_SHORT_READ   
63e0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
63f0: 52 52 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65  RR | (2<<8)).#de
6400: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
6410: 52 5f 57 52 49 54 45 20 20 20 20 20 20 20 20 20  R_WRITE         
6420: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
6430: 52 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66  R | (3<<8)).#def
6440: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
6450: 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20 20 20  _FSYNC          
6460: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
6470: 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69   | (4<<8)).#defi
6480: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
6490: 44 49 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20  DIR_FSYNC       
64a0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
64b0: 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (5<<8)).#defin
64c0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 54  e SQLITE_IOERR_T
64d0: 52 55 4e 43 41 54 45 20 20 20 20 20 20 20 20 20  RUNCATE         
64e0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
64f0: 20 28 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (6<<8)).#define
6500: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53   SQLITE_IOERR_FS
6510: 54 41 54 20 20 20 20 20 20 20 20 20 20 20 20 20  TAT             
6520: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
6530: 28 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (7<<8)).#define 
6540: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 55 4e 4c  SQLITE_IOERR_UNL
6550: 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 20 28  OCK            (
6560: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
6570: 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  8<<8)).#define S
6580: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 44 4c 4f  QLITE_IOERR_RDLO
6590: 43 4b 20 20 20 20 20 20 20 20 20 20 20 20 28 53  CK            (S
65a0: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 39  QLITE_IOERR | (9
65b0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
65c0: 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54  LITE_IOERR_DELET
65d0: 45 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51  E            (SQ
65e0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 30  LITE_IOERR | (10
65f0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
6600: 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b  LITE_IOERR_BLOCK
6610: 45 44 20 20 20 20 20 20 20 20 20 20 20 28 53 51  ED           (SQ
6620: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 31  LITE_IOERR | (11
6630: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
6640: 4c 49 54 45 5f 49 4f 45 52 52 5f 4e 4f 4d 45 4d  LITE_IOERR_NOMEM
6650: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
6660: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 32  LITE_IOERR | (12
6670: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
6680: 4c 49 54 45 5f 49 4f 45 52 52 5f 41 43 43 45 53  LITE_IOERR_ACCES
6690: 53 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51  S            (SQ
66a0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 33  LITE_IOERR | (13
66b0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
66c0: 4c 49 54 45 5f 49 4f 45 52 52 5f 43 48 45 43 4b  LITE_IOERR_CHECK
66d0: 52 45 53 45 52 56 45 44 4c 4f 43 4b 20 28 53 51  RESERVEDLOCK (SQ
66e0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 34  LITE_IOERR | (14
66f0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
6700: 4c 49 54 45 5f 49 4f 45 52 52 5f 4c 4f 43 4b 20  LITE_IOERR_LOCK 
6710: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
6720: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 35  LITE_IOERR | (15
6730: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
6740: 4c 49 54 45 5f 49 4f 45 52 52 5f 43 4c 4f 53 45  LITE_IOERR_CLOSE
6750: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
6760: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 36  LITE_IOERR | (16
6770: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
6780: 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f 43  LITE_IOERR_DIR_C
6790: 4c 4f 53 45 20 20 20 20 20 20 20 20 20 28 53 51  LOSE         (SQ
67a0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 37  LITE_IOERR | (17
67b0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
67c0: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4f 50  LITE_IOERR_SHMOP
67d0: 45 4e 20 20 20 20 20 20 20 20 20 20 20 28 53 51  EN           (SQ
67e0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 38  LITE_IOERR | (18
67f0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
6800: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 53 49  LITE_IOERR_SHMSI
6810: 5a 45 20 20 20 20 20 20 20 20 20 20 20 28 53 51  ZE           (SQ
6820: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 39  LITE_IOERR | (19
6830: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
6840: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4c 4f  LITE_IOERR_SHMLO
6850: 43 4b 20 20 20 20 20 20 20 20 20 20 20 28 53 51  CK           (SQ
6860: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 30  LITE_IOERR | (20
6870: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
6880: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4d 41  LITE_IOERR_SHMMA
6890: 50 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51  P            (SQ
68a0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 31  LITE_IOERR | (21
68b0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
68c0: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 45 45 4b 20  LITE_IOERR_SEEK 
68d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
68e0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 32  LITE_IOERR | (22
68f0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
6900: 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54  LITE_IOERR_DELET
6910: 45 5f 4e 4f 45 4e 54 20 20 20 20 20 20 28 53 51  E_NOENT      (SQ
6920: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 33  LITE_IOERR | (23
6930: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
6940: 4c 49 54 45 5f 49 4f 45 52 52 5f 4d 4d 41 50 20  LITE_IOERR_MMAP 
6950: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
6960: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 34  LITE_IOERR | (24
6970: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
6980: 4c 49 54 45 5f 49 4f 45 52 52 5f 47 45 54 54 45  LITE_IOERR_GETTE
6990: 4d 50 50 41 54 48 20 20 20 20 20 20 20 28 53 51  MPPATH       (SQ
69a0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 35  LITE_IOERR | (25
69b0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
69c0: 4c 49 54 45 5f 49 4f 45 52 52 5f 43 4f 4e 56 50  LITE_IOERR_CONVP
69d0: 41 54 48 20 20 20 20 20 20 20 20 20 20 28 53 51  ATH          (SQ
69e0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 36  LITE_IOERR | (26
69f0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
6a00: 4c 49 54 45 5f 4c 4f 43 4b 45 44 5f 53 48 41 52  LITE_LOCKED_SHAR
6a10: 45 44 43 41 43 48 45 20 20 20 20 20 20 28 53 51  EDCACHE      (SQ
6a20: 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 7c 20 20 28  LITE_LOCKED |  (
6a30: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
6a40: 51 4c 49 54 45 5f 42 55 53 59 5f 52 45 43 4f 56  QLITE_BUSY_RECOV
6a50: 45 52 59 20 20 20 20 20 20 20 20 20 20 20 28 53  ERY           (S
6a60: 51 4c 49 54 45 5f 42 55 53 59 20 20 20 7c 20 20  QLITE_BUSY   |  
6a70: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (1<<8)).#define 
6a80: 53 51 4c 49 54 45 5f 42 55 53 59 5f 53 4e 41 50  SQLITE_BUSY_SNAP
6a90: 53 48 4f 54 20 20 20 20 20 20 20 20 20 20 20 28  SHOT           (
6aa0: 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20 7c 20  SQLITE_BUSY   | 
6ab0: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (2<<8)).#define
6ac0: 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e   SQLITE_CANTOPEN
6ad0: 5f 4e 4f 54 45 4d 50 44 49 52 20 20 20 20 20 20  _NOTEMPDIR      
6ae0: 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e  (SQLITE_CANTOPEN
6af0: 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69   | (1<<8)).#defi
6b00: 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  ne SQLITE_CANTOP
6b10: 45 4e 5f 49 53 44 49 52 20 20 20 20 20 20 20 20  EN_ISDIR        
6b20: 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50    (SQLITE_CANTOP
6b30: 45 4e 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65  EN | (2<<8)).#de
6b40: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54  fine SQLITE_CANT
6b50: 4f 50 45 4e 5f 46 55 4c 4c 50 41 54 48 20 20 20  OPEN_FULLPATH   
6b60: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54      (SQLITE_CANT
6b70: 4f 50 45 4e 20 7c 20 28 33 3c 3c 38 29 29 0a 23  OPEN | (3<<8)).#
6b80: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41  define SQLITE_CA
6b90: 4e 54 4f 50 45 4e 5f 43 4f 4e 56 50 41 54 48 20  NTOPEN_CONVPATH 
6ba0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41        (SQLITE_CA
6bb0: 4e 54 4f 50 45 4e 20 7c 20 28 34 3c 3c 38 29 29  NTOPEN | (4<<8))
6bc0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6bd0: 43 4f 52 52 55 50 54 5f 56 54 41 42 20 20 20 20  CORRUPT_VTAB    
6be0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
6bf0: 43 4f 52 52 55 50 54 20 7c 20 28 31 3c 3c 38 29  CORRUPT | (1<<8)
6c00: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
6c10: 5f 52 45 41 44 4f 4e 4c 59 5f 52 45 43 4f 56 45  _READONLY_RECOVE
6c20: 52 59 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  RY       (SQLITE
6c30: 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 31 3c 3c  _READONLY | (1<<
6c40: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
6c50: 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 43 41 4e 54  TE_READONLY_CANT
6c60: 4c 4f 43 4b 20 20 20 20 20 20 20 28 53 51 4c 49  LOCK       (SQLI
6c70: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 32  TE_READONLY | (2
6c80: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
6c90: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 52 4f  LITE_READONLY_RO
6ca0: 4c 4c 42 41 43 4b 20 20 20 20 20 20 20 28 53 51  LLBACK       (SQ
6cb0: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20  LITE_READONLY | 
6cc0: 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (3<<8)).#define 
6cd0: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f  SQLITE_READONLY_
6ce0: 44 42 4d 4f 56 45 44 20 20 20 20 20 20 20 20 28  DBMOVED        (
6cf0: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20  SQLITE_READONLY 
6d00: 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (4<<8)).#defin
6d10: 65 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 5f 52  e SQLITE_ABORT_R
6d20: 4f 4c 4c 42 41 43 4b 20 20 20 20 20 20 20 20 20  OLLBACK         
6d30: 20 28 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 7c   (SQLITE_ABORT |
6d40: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (2<<8)).#define
6d50: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
6d60: 4e 54 5f 43 48 45 43 4b 20 20 20 20 20 20 20 20  NT_CHECK        
6d70: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
6d80: 4e 54 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65  NT | (1<<8)).#de
6d90: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
6da0: 54 52 41 49 4e 54 5f 43 4f 4d 4d 49 54 48 4f 4f  TRAINT_COMMITHOO
6db0: 4b 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53  K   (SQLITE_CONS
6dc0: 54 52 41 49 4e 54 20 7c 20 28 32 3c 3c 38 29 29  TRAINT | (2<<8))
6dd0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6de0: 43 4f 4e 53 54 52 41 49 4e 54 5f 46 4f 52 45 49  CONSTRAINT_FOREI
6df0: 47 4e 4b 45 59 20 20 20 28 53 51 4c 49 54 45 5f  GNKEY   (SQLITE_
6e00: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 33 3c  CONSTRAINT | (3<
6e10: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
6e20: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 46  ITE_CONSTRAINT_F
6e30: 55 4e 43 54 49 4f 4e 20 20 20 20 20 28 53 51 4c  UNCTION     (SQL
6e40: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
6e50: 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (4<<8)).#define
6e60: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
6e70: 4e 54 5f 4e 4f 54 4e 55 4c 4c 20 20 20 20 20 20  NT_NOTNULL      
6e80: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
6e90: 4e 54 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65  NT | (5<<8)).#de
6ea0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
6eb0: 54 52 41 49 4e 54 5f 50 52 49 4d 41 52 59 4b 45  TRAINT_PRIMARYKE
6ec0: 59 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53  Y   (SQLITE_CONS
6ed0: 54 52 41 49 4e 54 20 7c 20 28 36 3c 3c 38 29 29  TRAINT | (6<<8))
6ee0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6ef0: 43 4f 4e 53 54 52 41 49 4e 54 5f 54 52 49 47 47  CONSTRAINT_TRIGG
6f00: 45 52 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  ER      (SQLITE_
6f10: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 37 3c  CONSTRAINT | (7<
6f20: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
6f30: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 55  ITE_CONSTRAINT_U
6f40: 4e 49 51 55 45 20 20 20 20 20 20 20 28 53 51 4c  NIQUE       (SQL
6f50: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
6f60: 20 28 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (8<<8)).#define
6f70: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
6f80: 4e 54 5f 56 54 41 42 20 20 20 20 20 20 20 20 20  NT_VTAB         
6f90: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
6fa0: 4e 54 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65  NT | (9<<8)).#de
6fb0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
6fc0: 54 52 41 49 4e 54 5f 52 4f 57 49 44 20 20 20 20  TRAINT_ROWID    
6fd0: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53      (SQLITE_CONS
6fe0: 54 52 41 49 4e 54 20 7c 28 31 30 3c 3c 38 29 29  TRAINT |(10<<8))
6ff0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
7000: 4e 4f 54 49 43 45 5f 52 45 43 4f 56 45 52 5f 57  NOTICE_RECOVER_W
7010: 41 4c 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  AL      (SQLITE_
7020: 4e 4f 54 49 43 45 20 7c 20 28 31 3c 3c 38 29 29  NOTICE | (1<<8))
7030: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
7040: 4e 4f 54 49 43 45 5f 52 45 43 4f 56 45 52 5f 52  NOTICE_RECOVER_R
7050: 4f 4c 4c 42 41 43 4b 20 28 53 51 4c 49 54 45 5f  OLLBACK (SQLITE_
7060: 4e 4f 54 49 43 45 20 7c 20 28 32 3c 3c 38 29 29  NOTICE | (2<<8))
7070: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
7080: 57 41 52 4e 49 4e 47 5f 41 55 54 4f 49 4e 44 45  WARNING_AUTOINDE
7090: 58 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  X       (SQLITE_
70a0: 57 41 52 4e 49 4e 47 20 7c 20 28 31 3c 3c 38 29  WARNING | (1<<8)
70b0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
70c0: 5f 41 55 54 48 5f 55 53 45 52 20 20 20 20 20 20  _AUTH_USER      
70d0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
70e0: 5f 41 55 54 48 20 7c 20 28 31 3c 3c 38 29 29 0a  _AUTH | (1<<8)).
70f0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
7100: 20 46 6c 61 67 73 20 46 6f 72 20 46 69 6c 65 20   Flags For File 
7110: 4f 70 65 6e 20 4f 70 65 72 61 74 69 6f 6e 73 0a  Open Operations.
7120: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 62 69 74 20  **.** These bit 
7130: 76 61 6c 75 65 73 20 61 72 65 20 69 6e 74 65 6e  values are inten
7140: 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20 74  ded for use in t
7150: 68 65 0a 2a 2a 20 33 72 64 20 70 61 72 61 6d 65  he.** 3rd parame
7160: 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ter to the [sqli
7170: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69  te3_open_v2()] i
7180: 6e 74 65 72 66 61 63 65 20 61 6e 64 0a 2a 2a 20  nterface and.** 
7190: 69 6e 20 74 68 65 20 34 74 68 20 70 61 72 61 6d  in the 4th param
71a0: 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c  eter to the [sql
71b0: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20  ite3_vfs.xOpen] 
71c0: 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 23 64 65 66 69  method..*/.#defi
71d0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  ne SQLITE_OPEN_R
71e0: 45 41 44 4f 4e 4c 59 20 20 20 20 20 20 20 20 20  EADONLY         
71f0: 30 78 30 30 30 30 30 30 30 31 20 20 2f 2a 20 4f  0x00000001  /* O
7200: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
7210: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
7220: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  ne SQLITE_OPEN_R
7230: 45 41 44 57 52 49 54 45 20 20 20 20 20 20 20 20  EADWRITE        
7240: 30 78 30 30 30 30 30 30 30 32 20 20 2f 2a 20 4f  0x00000002  /* O
7250: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
7260: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
7270: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  ne SQLITE_OPEN_C
7280: 52 45 41 54 45 20 20 20 20 20 20 20 20 20 20 20  REATE           
7290: 30 78 30 30 30 30 30 30 30 34 20 20 2f 2a 20 4f  0x00000004  /* O
72a0: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
72b0: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
72c0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44  ne SQLITE_OPEN_D
72d0: 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 20 20 20 20  ELETEONCLOSE    
72e0: 30 78 30 30 30 30 30 30 30 38 20 20 2f 2a 20 56  0x00000008  /* V
72f0: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
7300: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45  ne SQLITE_OPEN_E
7310: 58 43 4c 55 53 49 56 45 20 20 20 20 20 20 20 20  XCLUSIVE        
7320: 30 78 30 30 30 30 30 30 31 30 20 20 2f 2a 20 56  0x00000010  /* V
7330: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
7340: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 41  ne SQLITE_OPEN_A
7350: 55 54 4f 50 52 4f 58 59 20 20 20 20 20 20 20 20  UTOPROXY        
7360: 30 78 30 30 30 30 30 30 32 30 20 20 2f 2a 20 56  0x00000020  /* V
7370: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
7380: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55  ne SQLITE_OPEN_U
7390: 52 49 20 20 20 20 20 20 20 20 20 20 20 20 20 20  RI              
73a0: 30 78 30 30 30 30 30 30 34 30 20 20 2f 2a 20 4f  0x00000040  /* O
73b0: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
73c0: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
73d0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d  ne SQLITE_OPEN_M
73e0: 45 4d 4f 52 59 20 20 20 20 20 20 20 20 20 20 20  EMORY           
73f0: 30 78 30 30 30 30 30 30 38 30 20 20 2f 2a 20 4f  0x00000080  /* O
7400: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
7410: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
7420: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d  ne SQLITE_OPEN_M
7430: 41 49 4e 5f 44 42 20 20 20 20 20 20 20 20 20 20  AIN_DB          
7440: 30 78 30 30 30 30 30 31 30 30 20 20 2f 2a 20 56  0x00000100  /* V
7450: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
7460: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54  ne SQLITE_OPEN_T
7470: 45 4d 50 5f 44 42 20 20 20 20 20 20 20 20 20 20  EMP_DB          
7480: 30 78 30 30 30 30 30 32 30 30 20 20 2f 2a 20 56  0x00000200  /* V
7490: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
74a0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54  ne SQLITE_OPEN_T
74b0: 52 41 4e 53 49 45 4e 54 5f 44 42 20 20 20 20 20  RANSIENT_DB     
74c0: 30 78 30 30 30 30 30 34 30 30 20 20 2f 2a 20 56  0x00000400  /* V
74d0: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
74e0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d  ne SQLITE_OPEN_M
74f0: 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20  AIN_JOURNAL     
7500: 30 78 30 30 30 30 30 38 30 30 20 20 2f 2a 20 56  0x00000800  /* V
7510: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
7520: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54  ne SQLITE_OPEN_T
7530: 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20  EMP_JOURNAL     
7540: 30 78 30 30 30 30 31 30 30 30 20 20 2f 2a 20 56  0x00001000  /* V
7550: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
7560: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53  ne SQLITE_OPEN_S
7570: 55 42 4a 4f 55 52 4e 41 4c 20 20 20 20 20 20 20  UBJOURNAL       
7580: 30 78 30 30 30 30 32 30 30 30 20 20 2f 2a 20 56  0x00002000  /* V
7590: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
75a0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d  ne SQLITE_OPEN_M
75b0: 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 20 20 20  ASTER_JOURNAL   
75c0: 30 78 30 30 30 30 34 30 30 30 20 20 2f 2a 20 56  0x00004000  /* V
75d0: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
75e0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e  ne SQLITE_OPEN_N
75f0: 4f 4d 55 54 45 58 20 20 20 20 20 20 20 20 20 20  OMUTEX          
7600: 30 78 30 30 30 30 38 30 30 30 20 20 2f 2a 20 4f  0x00008000  /* O
7610: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
7620: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
7630: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46  ne SQLITE_OPEN_F
7640: 55 4c 4c 4d 55 54 45 58 20 20 20 20 20 20 20 20  ULLMUTEX        
7650: 30 78 30 30 30 31 30 30 30 30 20 20 2f 2a 20 4f  0x00010000  /* O
7660: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
7670: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
7680: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53  ne SQLITE_OPEN_S
7690: 48 41 52 45 44 43 41 43 48 45 20 20 20 20 20 20  HAREDCACHE      
76a0: 30 78 30 30 30 32 30 30 30 30 20 20 2f 2a 20 4f  0x00020000  /* O
76b0: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
76c0: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
76d0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50  ne SQLITE_OPEN_P
76e0: 52 49 56 41 54 45 43 41 43 48 45 20 20 20 20 20  RIVATECACHE     
76f0: 30 78 30 30 30 34 30 30 30 30 20 20 2f 2a 20 4f  0x00040000  /* O
7700: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
7710: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
7720: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 57  ne SQLITE_OPEN_W
7730: 41 4c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  AL              
7740: 30 78 30 30 30 38 30 30 30 30 20 20 2f 2a 20 56  0x00080000  /* V
7750: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 20 52  FS only */../* R
7760: 65 73 65 72 76 65 64 3a 20 20 20 20 20 20 20 20  eserved:        
7770: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
7780: 20 30 78 30 30 46 30 30 30 30 30 20 2a 2f 0a 0a   0x00F00000 */..
7790: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
77a0: 44 65 76 69 63 65 20 43 68 61 72 61 63 74 65 72  Device Character
77b0: 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 54 68 65  istics.**.** The
77c0: 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65   xDeviceCharacte
77d0: 72 69 73 74 69 63 73 20 6d 65 74 68 6f 64 20 6f  ristics method o
77e0: 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69  f the [sqlite3_i
77f0: 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62  o_methods].** ob
7800: 6a 65 63 74 20 72 65 74 75 72 6e 73 20 61 6e 20  ject returns an 
7810: 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73  integer which is
7820: 20 61 20 76 65 63 74 6f 72 20 6f 66 20 74 68 65   a vector of the
7830: 73 65 0a 2a 2a 20 62 69 74 20 76 61 6c 75 65 73  se.** bit values
7840: 20 65 78 70 72 65 73 73 69 6e 67 20 49 2f 4f 20   expressing I/O 
7850: 63 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20  characteristics 
7860: 6f 66 20 74 68 65 20 6d 61 73 73 20 73 74 6f 72  of the mass stor
7870: 61 67 65 0a 2a 2a 20 64 65 76 69 63 65 20 74 68  age.** device th
7880: 61 74 20 68 6f 6c 64 73 20 74 68 65 20 66 69 6c  at holds the fil
7890: 65 20 74 68 61 74 20 74 68 65 20 5b 73 71 6c 69  e that the [sqli
78a0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a  te3_io_methods].
78b0: 2a 2a 20 72 65 66 65 72 73 20 74 6f 2e 0a 2a 2a  ** refers to..**
78c0: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 49  .** The SQLITE_I
78d0: 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70  OCAP_ATOMIC prop
78e0: 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20  erty means that 
78f0: 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a  all writes of.**
7900: 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20 61 74   any size are at
7910: 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54  omic.  The SQLIT
7920: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e  E_IOCAP_ATOMICnn
7930: 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e  n values.** mean
7940: 20 74 68 61 74 20 77 72 69 74 65 73 20 6f 66 20   that writes of 
7950: 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 65 20  blocks that are 
7960: 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 69 7a  nnn bytes in siz
7970: 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69  e and.** are ali
7980: 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 72 65  gned to an addre
7990: 73 73 20 77 68 69 63 68 20 69 73 20 61 6e 20 69  ss which is an i
79a0: 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c 65 20  nteger multiple 
79b0: 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74  of.** nnn are at
79c0: 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54  omic.  The SQLIT
79d0: 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50  E_IOCAP_SAFE_APP
79e0: 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a  END value means.
79f0: 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64 61 74  ** that when dat
7a00: 61 20 69 73 20 61 70 70 65 6e 64 65 64 20 74 6f  a is appended to
7a10: 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74   a file, the dat
7a20: 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a  a is appended.**
7a30: 20 66 69 72 73 74 20 74 68 65 6e 20 74 68 65 20   first then the 
7a40: 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69 6c 65  size of the file
7a50: 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20 6e 65   is extended, ne
7a60: 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a  ver the other.**
7a70: 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 54 68   way around.  Th
7a80: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53  e SQLITE_IOCAP_S
7a90: 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 65 72  EQUENTIAL proper
7aa0: 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a  ty means that.**
7ab0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20   information is 
7ac0: 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 20  written to disk 
7ad0: 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 64 65  in the same orde
7ae0: 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f  r as calls.** to
7af0: 20 78 57 72 69 74 65 28 29 2e 20 20 54 68 65 20   xWrite().  The 
7b00: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57  SQLITE_IOCAP_POW
7b10: 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45  ERSAFE_OVERWRITE
7b20: 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20   property means 
7b30: 74 68 61 74 0a 2a 2a 20 61 66 74 65 72 20 72 65  that.** after re
7b40: 62 6f 6f 74 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  boot following a
7b50: 20 63 72 61 73 68 20 6f 72 20 70 6f 77 65 72 20   crash or power 
7b60: 6c 6f 73 73 2c 20 74 68 65 20 6f 6e 6c 79 20 62  loss, the only b
7b70: 79 74 65 73 20 69 6e 20 61 0a 2a 2a 20 66 69 6c  ytes in a.** fil
7b80: 65 20 74 68 61 74 20 77 65 72 65 20 77 72 69 74  e that were writ
7b90: 74 65 6e 20 61 74 20 74 68 65 20 61 70 70 6c 69  ten at the appli
7ba0: 63 61 74 69 6f 6e 20 6c 65 76 65 6c 20 6d 69 67  cation level mig
7bb0: 68 74 20 68 61 76 65 20 63 68 61 6e 67 65 64 0a  ht have changed.
7bc0: 2a 2a 20 61 6e 64 20 74 68 61 74 20 61 64 6a 61  ** and that adja
7bd0: 63 65 6e 74 20 62 79 74 65 73 2c 20 65 76 65 6e  cent bytes, even
7be0: 20 62 79 74 65 73 20 77 69 74 68 69 6e 20 74 68   bytes within th
7bf0: 65 20 73 61 6d 65 20 73 65 63 74 6f 72 20 61 72  e same sector ar
7c00: 65 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 64 20  e.** guaranteed 
7c10: 74 6f 20 62 65 20 75 6e 63 68 61 6e 67 65 64 2e  to be unchanged.
7c20: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
7c30: 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57  AP_UNDELETABLE_W
7c40: 48 45 4e 5f 4f 50 45 4e 0a 2a 2a 20 66 6c 61 67  HEN_OPEN.** flag
7c50: 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 20 61   indicate that a
7c60: 20 66 69 6c 65 20 63 61 6e 6e 6f 74 20 62 65 20   file cannot be 
7c70: 64 65 6c 65 74 65 64 20 77 68 65 6e 20 6f 70 65  deleted when ope
7c80: 6e 2e 20 20 54 68 65 0a 2a 2a 20 53 51 4c 49 54  n.  The.** SQLIT
7c90: 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c  E_IOCAP_IMMUTABL
7ca0: 45 20 66 6c 61 67 20 69 6e 64 69 63 61 74 65 73  E flag indicates
7cb0: 20 74 68 61 74 20 74 68 65 20 66 69 6c 65 20 69   that the file i
7cc0: 73 20 6f 6e 0a 2a 2a 20 72 65 61 64 2d 6f 6e 6c  s on.** read-onl
7cd0: 79 20 6d 65 64 69 61 20 61 6e 64 20 63 61 6e 6e  y media and cann
7ce0: 6f 74 20 62 65 20 63 68 61 6e 67 65 64 20 65 76  ot be changed ev
7cf0: 65 6e 20 62 79 20 70 72 6f 63 65 73 73 65 73 20  en by processes 
7d00: 77 69 74 68 0a 2a 2a 20 65 6c 65 76 61 74 65 64  with.** elevated
7d10: 20 70 72 69 76 69 6c 65 67 65 73 2e 0a 2a 2f 0a   privileges..*/.
7d20: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
7d30: 4f 43 41 50 5f 41 54 4f 4d 49 43 20 20 20 20 20  OCAP_ATOMIC     
7d40: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
7d50: 30 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53  000001.#define S
7d60: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7d70: 49 43 35 31 32 20 20 20 20 20 20 20 20 20 20 20  IC512           
7d80: 20 20 20 30 78 30 30 30 30 30 30 30 32 0a 23 64     0x00000002.#d
7d90: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
7da0: 41 50 5f 41 54 4f 4d 49 43 31 4b 20 20 20 20 20  AP_ATOMIC1K     
7db0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
7dc0: 30 30 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c  0004.#define SQL
7dd0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
7de0: 32 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  2K              
7df0: 20 30 78 30 30 30 30 30 30 30 38 0a 23 64 65 66   0x00000008.#def
7e00: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
7e10: 5f 41 54 4f 4d 49 43 34 4b 20 20 20 20 20 20 20  _ATOMIC4K       
7e20: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
7e30: 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  10.#define SQLIT
7e40: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b  E_IOCAP_ATOMIC8K
7e50: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
7e60: 78 30 30 30 30 30 30 32 30 0a 23 64 65 66 69 6e  x00000020.#defin
7e70: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
7e80: 54 4f 4d 49 43 31 36 4b 20 20 20 20 20 20 20 20  TOMIC16K        
7e90: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 34 30        0x00000040
7ea0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
7eb0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20  IOCAP_ATOMIC32K 
7ec0: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
7ed0: 30 30 30 30 30 38 30 0a 23 64 65 66 69 6e 65 20  0000080.#define 
7ee0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
7ef0: 4d 49 43 36 34 4b 20 20 20 20 20 20 20 20 20 20  MIC64K          
7f00: 20 20 20 20 30 78 30 30 30 30 30 31 30 30 0a 23      0x00000100.#
7f10: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
7f20: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20  CAP_SAFE_APPEND 
7f30: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
7f40: 30 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00200.#define SQ
7f50: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45  LITE_IOCAP_SEQUE
7f60: 4e 54 49 41 4c 20 20 20 20 20 20 20 20 20 20 20  NTIAL           
7f70: 20 20 30 78 30 30 30 30 30 34 30 30 0a 23 64 65    0x00000400.#de
7f80: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
7f90: 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48  P_UNDELETABLE_WH
7fa0: 45 4e 5f 4f 50 45 4e 20 20 30 78 30 30 30 30 30  EN_OPEN  0x00000
7fb0: 38 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  800.#define SQLI
7fc0: 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41  TE_IOCAP_POWERSA
7fd0: 46 45 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20  FE_OVERWRITE    
7fe0: 30 78 30 30 30 30 31 30 30 30 0a 23 64 65 66 69  0x00001000.#defi
7ff0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
8000: 49 4d 4d 55 54 41 42 4c 45 20 20 20 20 20 20 20  IMMUTABLE       
8010: 20 20 20 20 20 20 20 30 78 30 30 30 30 32 30 30         0x0000200
8020: 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  0../*.** CAPI3RE
8030: 46 3a 20 46 69 6c 65 20 4c 6f 63 6b 69 6e 67 20  F: File Locking 
8040: 4c 65 76 65 6c 73 0a 2a 2a 0a 2a 2a 20 53 51 4c  Levels.**.** SQL
8050: 69 74 65 20 75 73 65 73 20 6f 6e 65 20 6f 66 20  ite uses one of 
8060: 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61  these integer va
8070: 6c 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f  lues as the seco
8080: 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74  nd.** argument t
8090: 6f 20 63 61 6c 6c 73 20 69 74 20 6d 61 6b 65 73  o calls it makes
80a0: 20 74 6f 20 74 68 65 20 78 4c 6f 63 6b 28 29 20   to the xLock() 
80b0: 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 6d 65  and xUnlock() me
80c0: 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b  thods.** of an [
80d0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
80e0: 64 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23  ds] object..*/.#
80f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
8100: 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 20 20 20 20  CK_NONE         
8110: 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   0.#define SQLIT
8120: 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 20 20 20  E_LOCK_SHARED   
8130: 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
8140: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52  QLITE_LOCK_RESER
8150: 56 45 44 20 20 20 20 20 20 32 0a 23 64 65 66 69  VED      2.#defi
8160: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50  ne SQLITE_LOCK_P
8170: 45 4e 44 49 4e 47 20 20 20 20 20 20 20 33 0a 23  ENDING       3.#
8180: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
8190: 43 4b 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20  CK_EXCLUSIVE    
81a0: 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52   4../*.** CAPI3R
81b0: 45 46 3a 20 53 79 6e 63 68 72 6f 6e 69 7a 61 74  EF: Synchronizat
81c0: 69 6f 6e 20 54 79 70 65 20 46 6c 61 67 73 0a 2a  ion Type Flags.*
81d0: 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 4c 69 74 65  *.** When SQLite
81e0: 20 69 6e 76 6f 6b 65 73 20 74 68 65 20 78 53 79   invokes the xSy
81f0: 6e 63 28 29 20 6d 65 74 68 6f 64 20 6f 66 20 61  nc() method of a
8200: 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f  n.** [sqlite3_io
8210: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
8220: 20 69 74 20 75 73 65 73 20 61 20 63 6f 6d 62 69   it uses a combi
8230: 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65  nation of.** the
8240: 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65  se integer value
8250: 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  s as the second 
8260: 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
8270: 57 68 65 6e 20 74 68 65 20 53 51 4c 49 54 45 5f  When the SQLITE_
8280: 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 66 6c  SYNC_DATAONLY fl
8290: 61 67 20 69 73 20 75 73 65 64 2c 20 69 74 20 6d  ag is used, it m
82a0: 65 61 6e 73 20 74 68 61 74 20 74 68 65 0a 2a 2a  eans that the.**
82b0: 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 20   sync operation 
82c0: 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 66 6c  only needs to fl
82d0: 75 73 68 20 64 61 74 61 20 74 6f 20 6d 61 73 73  ush data to mass
82e0: 20 73 74 6f 72 61 67 65 2e 20 20 49 6e 6f 64 65   storage.  Inode
82f0: 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  .** information 
8300: 6e 65 65 64 20 6e 6f 74 20 62 65 20 66 6c 75 73  need not be flus
8310: 68 65 64 2e 20 49 66 20 74 68 65 20 6c 6f 77 65  hed. If the lowe
8320: 72 20 66 6f 75 72 20 62 69 74 73 20 6f 66 20 74  r four bits of t
8330: 68 65 20 66 6c 61 67 0a 2a 2a 20 65 71 75 61 6c  he flag.** equal
8340: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52   SQLITE_SYNC_NOR
8350: 4d 41 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73 20  MAL, that means 
8360: 74 6f 20 75 73 65 20 6e 6f 72 6d 61 6c 20 66 73  to use normal fs
8370: 79 6e 63 28 29 20 73 65 6d 61 6e 74 69 63 73 2e  ync() semantics.
8380: 0a 2a 2a 20 49 66 20 74 68 65 20 6c 6f 77 65 72  .** If the lower
8390: 20 66 6f 75 72 20 62 69 74 73 20 65 71 75 61 6c   four bits equal
83a0: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c   SQLITE_SYNC_FUL
83b0: 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a  L, that means.**
83c0: 20 74 6f 20 75 73 65 20 4d 61 63 20 4f 53 20 58   to use Mac OS X
83d0: 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 20   style fullsync 
83e0: 69 6e 73 74 65 61 64 20 6f 66 20 66 73 79 6e 63  instead of fsync
83f0: 28 29 2e 0a 2a 2a 0a 2a 2a 20 44 6f 20 6e 6f 74  ()..**.** Do not
8400: 20 63 6f 6e 66 75 73 65 20 74 68 65 20 53 51 4c   confuse the SQL
8410: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20  ITE_SYNC_NORMAL 
8420: 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  and SQLITE_SYNC_
8430: 46 55 4c 4c 20 66 6c 61 67 73 0a 2a 2a 20 77 69  FULL flags.** wi
8440: 74 68 20 74 68 65 20 5b 50 52 41 47 4d 41 20 73  th the [PRAGMA s
8450: 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 4e 4f 52 4d  ynchronous]=NORM
8460: 41 4c 20 61 6e 64 20 5b 50 52 41 47 4d 41 20 73  AL and [PRAGMA s
8470: 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 46 55 4c 4c  ynchronous]=FULL
8480: 0a 2a 2a 20 73 65 74 74 69 6e 67 73 2e 20 20 54  .** settings.  T
8490: 68 65 20 5b 73 79 6e 63 68 72 6f 6e 6f 75 73 20  he [synchronous 
84a0: 70 72 61 67 6d 61 5d 20 64 65 74 65 72 6d 69 6e  pragma] determin
84b0: 65 73 20 77 68 65 6e 20 63 61 6c 6c 73 20 74 6f  es when calls to
84c0: 20 74 68 65 0a 2a 2a 20 78 53 79 6e 63 20 56 46   the.** xSync VF
84d0: 53 20 6d 65 74 68 6f 64 20 6f 63 63 75 72 20 61  S method occur a
84e0: 6e 64 20 61 70 70 6c 69 65 73 20 75 6e 69 66 6f  nd applies unifo
84f0: 72 6d 6c 79 20 61 63 72 6f 73 73 20 61 6c 6c 20  rmly across all 
8500: 70 6c 61 74 66 6f 72 6d 73 2e 0a 2a 2a 20 54 68  platforms..** Th
8510: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f  e SQLITE_SYNC_NO
8520: 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f  RMAL and SQLITE_
8530: 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73 20  SYNC_FULL flags 
8540: 64 65 74 65 72 6d 69 6e 65 20 68 6f 77 0a 2a 2a  determine how.**
8550: 20 65 6e 65 72 67 65 74 69 63 20 6f 72 20 72 69   energetic or ri
8560: 67 6f 72 6f 75 73 20 6f 72 20 66 6f 72 63 65 66  gorous or forcef
8570: 75 6c 20 74 68 65 20 73 79 6e 63 20 6f 70 65 72  ul the sync oper
8580: 61 74 69 6f 6e 73 20 61 72 65 20 61 6e 64 0a 2a  ations are and.*
8590: 2a 20 6f 6e 6c 79 20 6d 61 6b 65 20 61 20 64 69  * only make a di
85a0: 66 66 65 72 65 6e 63 65 20 6f 6e 20 4d 61 63 20  fference on Mac 
85b0: 4f 53 58 20 66 6f 72 20 74 68 65 20 64 65 66 61  OSX for the defa
85c0: 75 6c 74 20 53 51 4c 69 74 65 20 63 6f 64 65 2e  ult SQLite code.
85d0: 0a 2a 2a 20 28 54 68 69 72 64 2d 70 61 72 74 79  .** (Third-party
85e0: 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
85f0: 69 6f 6e 73 20 6d 69 67 68 74 20 61 6c 73 6f 20  ions might also 
8600: 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69 6e 63  make the distinc
8610: 74 69 6f 6e 0a 2a 2a 20 62 65 74 77 65 65 6e 20  tion.** between 
8620: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d  SQLITE_SYNC_NORM
8630: 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59  AL and SQLITE_SY
8640: 4e 43 5f 46 55 4c 4c 2c 20 62 75 74 20 61 6d 6f  NC_FULL, but amo
8650: 6e 67 20 74 68 65 0a 2a 2a 20 6f 70 65 72 61 74  ng the.** operat
8660: 69 6e 67 20 73 79 73 74 65 6d 73 20 6e 61 74 69  ing systems nati
8670: 76 65 6c 79 20 73 75 70 70 6f 72 74 65 64 20 62  vely supported b
8680: 79 20 53 51 4c 69 74 65 2c 20 6f 6e 6c 79 20 4d  y SQLite, only M
8690: 61 63 20 4f 53 58 0a 2a 2a 20 63 61 72 65 73 20  ac OSX.** cares 
86a0: 61 62 6f 75 74 20 74 68 65 20 64 69 66 66 65 72  about the differ
86b0: 65 6e 63 65 2e 29 0a 2a 2f 0a 23 64 65 66 69 6e  ence.).*/.#defin
86c0: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f  e SQLITE_SYNC_NO
86d0: 52 4d 41 4c 20 20 20 20 20 20 20 20 30 78 30 30  RMAL        0x00
86e0: 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  002.#define SQLI
86f0: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 20 20 20  TE_SYNC_FULL    
8700: 20 20 20 20 20 20 30 78 30 30 30 30 33 0a 23 64        0x00003.#d
8710: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e  efine SQLITE_SYN
8720: 43 5f 44 41 54 41 4f 4e 4c 59 20 20 20 20 20 20  C_DATAONLY      
8730: 30 78 30 30 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43  0x00010../*.** C
8740: 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65  API3REF: OS Inte
8750: 72 66 61 63 65 20 4f 70 65 6e 20 46 69 6c 65 20  rface Open File 
8760: 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 41 6e 20  Handle.**.** An 
8770: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f  [sqlite3_file] o
8780: 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 73  bject represents
8790: 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 69 6e   an open file in
87a0: 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65   the .** [sqlite
87b0: 33 5f 76 66 73 20 7c 20 4f 53 20 69 6e 74 65 72  3_vfs | OS inter
87c0: 66 61 63 65 20 6c 61 79 65 72 5d 2e 20 20 49 6e  face layer].  In
87d0: 64 69 76 69 64 75 61 6c 20 4f 53 20 69 6e 74 65  dividual OS inte
87e0: 72 66 61 63 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65  rface.** impleme
87f0: 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a  ntations will.**
8800: 20 77 61 6e 74 20 74 6f 20 73 75 62 63 6c 61 73   want to subclas
8810: 73 20 74 68 69 73 20 6f 62 6a 65 63 74 20 62 79  s this object by
8820: 20 61 70 70 65 6e 64 69 6e 67 20 61 64 64 69 74   appending addit
8830: 69 6f 6e 61 6c 20 66 69 65 6c 64 73 0a 2a 2a 20  ional fields.** 
8840: 66 6f 72 20 74 68 65 69 72 20 6f 77 6e 20 75 73  for their own us
8850: 65 2e 20 20 54 68 65 20 70 4d 65 74 68 6f 64 73  e.  The pMethods
8860: 20 65 6e 74 72 79 20 69 73 20 61 20 70 6f 69 6e   entry is a poin
8870: 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71  ter to an.** [sq
8880: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
8890: 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65  ] object that de
88a0: 66 69 6e 65 73 20 6d 65 74 68 6f 64 73 20 66 6f  fines methods fo
88b0: 72 20 70 65 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20  r performing.** 
88c0: 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20 6f  I/O operations o
88d0: 6e 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 2e  n the open file.
88e0: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
88f0: 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20  ct sqlite3_file 
8900: 73 71 6c 69 74 65 33 5f 66 69 6c 65 3b 0a 73 74  sqlite3_file;.st
8910: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c  ruct sqlite3_fil
8920: 65 20 7b 0a 20 20 63 6f 6e 73 74 20 73 74 72 75  e {.  const stru
8930: 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  ct sqlite3_io_me
8940: 74 68 6f 64 73 20 2a 70 4d 65 74 68 6f 64 73 3b  thods *pMethods;
8950: 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72    /* Methods for
8960: 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 2a 2f   an open file */
8970: 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .};../*.** CAPI3
8980: 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63  REF: OS Interfac
8990: 65 20 46 69 6c 65 20 56 69 72 74 75 61 6c 20 4d  e File Virtual M
89a0: 65 74 68 6f 64 73 20 4f 62 6a 65 63 74 0a 2a 2a  ethods Object.**
89b0: 0a 2a 2a 20 45 76 65 72 79 20 66 69 6c 65 20 6f  .** Every file o
89c0: 70 65 6e 65 64 20 62 79 20 74 68 65 20 5b 73 71  pened by the [sq
89d0: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d  lite3_vfs.xOpen]
89e0: 20 6d 65 74 68 6f 64 20 70 6f 70 75 6c 61 74 65   method populate
89f0: 73 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  s an.** [sqlite3
8a00: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 28 6f  _file] object (o
8a10: 72 2c 20 6d 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79  r, more commonly
8a20: 2c 20 61 20 73 75 62 63 6c 61 73 73 20 6f 66 20  , a subclass of 
8a30: 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
8a40: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 29 20 77 69  file] object) wi
8a50: 74 68 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  th a pointer to 
8a60: 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
8a70: 68 69 73 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54  his object..** T
8a80: 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e  his object defin
8a90: 65 73 20 74 68 65 20 6d 65 74 68 6f 64 73 20 75  es the methods u
8aa0: 73 65 64 20 74 6f 20 70 65 72 66 6f 72 6d 20 76  sed to perform v
8ab0: 61 72 69 6f 75 73 20 6f 70 65 72 61 74 69 6f 6e  arious operation
8ac0: 73 0a 2a 2a 20 61 67 61 69 6e 73 74 20 74 68 65  s.** against the
8ad0: 20 6f 70 65 6e 20 66 69 6c 65 20 72 65 70 72 65   open file repre
8ae0: 73 65 6e 74 65 64 20 62 79 20 74 68 65 20 5b 73  sented by the [s
8af0: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
8b00: 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  ect..**.** If th
8b10: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78  e [sqlite3_vfs.x
8b20: 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 73 65 74  Open] method set
8b30: 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69  s the sqlite3_fi
8b40: 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d  le.pMethods elem
8b50: 65 6e 74 20 0a 2a 2a 20 74 6f 20 61 20 6e 6f 6e  ent .** to a non
8b60: 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74  -NULL pointer, t
8b70: 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f  hen the sqlite3_
8b80: 69 6f 5f 6d 65 74 68 6f 64 73 2e 78 43 6c 6f 73  io_methods.xClos
8b90: 65 20 6d 65 74 68 6f 64 0a 2a 2a 20 6d 61 79 20  e method.** may 
8ba0: 62 65 20 69 6e 76 6f 6b 65 64 20 65 76 65 6e 20  be invoked even 
8bb0: 69 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  if the [sqlite3_
8bc0: 76 66 73 2e 78 4f 70 65 6e 5d 20 72 65 70 6f 72  vfs.xOpen] repor
8bd0: 74 65 64 20 74 68 61 74 20 69 74 20 66 61 69 6c  ted that it fail
8be0: 65 64 2e 20 20 54 68 65 0a 2a 2a 20 6f 6e 6c 79  ed.  The.** only
8bf0: 20 77 61 79 20 74 6f 20 70 72 65 76 65 6e 74 20   way to prevent 
8c00: 61 20 63 61 6c 6c 20 74 6f 20 78 43 6c 6f 73 65  a call to xClose
8c10: 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69   following a fai
8c20: 6c 65 64 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  led [sqlite3_vfs
8c30: 2e 78 4f 70 65 6e 5d 0a 2a 2a 20 69 73 20 66 6f  .xOpen].** is fo
8c40: 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  r the [sqlite3_v
8c50: 66 73 2e 78 4f 70 65 6e 5d 20 74 6f 20 73 65 74  fs.xOpen] to set
8c60: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c   the sqlite3_fil
8c70: 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65  e.pMethods eleme
8c80: 6e 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 0a 2a  nt.** to NULL..*
8c90: 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61  *.** The flags a
8ca0: 72 67 75 6d 65 6e 74 20 74 6f 20 78 53 79 6e 63  rgument to xSync
8cb0: 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66 20 5b   may be one of [
8cc0: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d  SQLITE_SYNC_NORM
8cd0: 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54  AL] or.** [SQLIT
8ce0: 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d 2e 20 20 54  E_SYNC_FULL].  T
8cf0: 68 65 20 66 69 72 73 74 20 63 68 6f 69 63 65 20  he first choice 
8d00: 69 73 20 74 68 65 20 6e 6f 72 6d 61 6c 20 66 73  is the normal fs
8d10: 79 6e 63 28 29 2e 0a 2a 2a 20 54 68 65 20 73 65  ync()..** The se
8d20: 63 6f 6e 64 20 63 68 6f 69 63 65 20 69 73 20 61  cond choice is a
8d30: 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20   Mac OS X style 
8d40: 66 75 6c 6c 73 79 6e 63 2e 20 20 54 68 65 20 5b  fullsync.  The [
8d50: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41  SQLITE_SYNC_DATA
8d60: 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c 61 67 20 6d 61  ONLY].** flag ma
8d70: 79 20 62 65 20 4f 52 65 64 20 69 6e 20 74 6f 20  y be ORed in to 
8d80: 69 6e 64 69 63 61 74 65 20 74 68 61 74 20 6f 6e  indicate that on
8d90: 6c 79 20 74 68 65 20 64 61 74 61 20 6f 66 20 74  ly the data of t
8da0: 68 65 20 66 69 6c 65 0a 2a 2a 20 61 6e 64 20 6e  he file.** and n
8db0: 6f 74 20 69 74 73 20 69 6e 6f 64 65 20 6e 65 65  ot its inode nee
8dc0: 64 73 20 74 6f 20 62 65 20 73 79 6e 63 65 64 2e  ds to be synced.
8dd0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65 67  .**.** The integ
8de0: 65 72 20 76 61 6c 75 65 73 20 74 6f 20 78 4c 6f  er values to xLo
8df0: 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b  ck() and xUnlock
8e00: 28 29 20 61 72 65 20 6f 6e 65 20 6f 66 0a 2a 2a  () are one of.**
8e10: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53   <ul>.** <li> [S
8e20: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d  QLITE_LOCK_NONE]
8e30: 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ,.** <li> [SQLIT
8e40: 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a  E_LOCK_SHARED],.
8e50: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
8e60: 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 0a  LOCK_RESERVED],.
8e70: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
8e80: 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f  LOCK_PENDING], o
8e90: 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  r.** <li> [SQLIT
8ea0: 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45  E_LOCK_EXCLUSIVE
8eb0: 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 78  ]..** </ul>.** x
8ec0: 4c 6f 63 6b 28 29 20 69 6e 63 72 65 61 73 65 73  Lock() increases
8ed0: 20 74 68 65 20 6c 6f 63 6b 2e 20 78 55 6e 6c 6f   the lock. xUnlo
8ee0: 63 6b 28 29 20 64 65 63 72 65 61 73 65 73 20 74  ck() decreases t
8ef0: 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 54 68 65 20  he lock..** The 
8f00: 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f  xCheckReservedLo
8f10: 63 6b 28 29 20 6d 65 74 68 6f 64 20 63 68 65 63  ck() method chec
8f20: 6b 73 20 77 68 65 74 68 65 72 20 61 6e 79 20 64  ks whether any d
8f30: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
8f40: 6f 6e 2c 0a 2a 2a 20 65 69 74 68 65 72 20 69 6e  on,.** either in
8f50: 20 74 68 69 73 20 70 72 6f 63 65 73 73 20 6f 72   this process or
8f60: 20 69 6e 20 73 6f 6d 65 20 6f 74 68 65 72 20 70   in some other p
8f70: 72 6f 63 65 73 73 2c 20 69 73 20 68 6f 6c 64 69  rocess, is holdi
8f80: 6e 67 20 61 20 52 45 53 45 52 56 45 44 2c 0a 2a  ng a RESERVED,.*
8f90: 2a 20 50 45 4e 44 49 4e 47 2c 20 6f 72 20 45 58  * PENDING, or EX
8fa0: 43 4c 55 53 49 56 45 20 6c 6f 63 6b 20 6f 6e 20  CLUSIVE lock on 
8fb0: 74 68 65 20 66 69 6c 65 2e 20 20 49 74 20 72 65  the file.  It re
8fc0: 74 75 72 6e 73 20 74 72 75 65 0a 2a 2a 20 69 66  turns true.** if
8fd0: 20 73 75 63 68 20 61 20 6c 6f 63 6b 20 65 78 69   such a lock exi
8fe0: 73 74 73 20 61 6e 64 20 66 61 6c 73 65 20 6f 74  sts and false ot
8ff0: 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 54  herwise..**.** T
9000: 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28  he xFileControl(
9010: 29 20 6d 65 74 68 6f 64 20 69 73 20 61 20 67 65  ) method is a ge
9020: 6e 65 72 69 63 20 69 6e 74 65 72 66 61 63 65 20  neric interface 
9030: 74 68 61 74 20 61 6c 6c 6f 77 73 20 63 75 73 74  that allows cust
9040: 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d 70 6c 65 6d  om.** VFS implem
9050: 65 6e 74 61 74 69 6f 6e 73 20 74 6f 20 64 69 72  entations to dir
9060: 65 63 74 6c 79 20 63 6f 6e 74 72 6f 6c 20 61 6e  ectly control an
9070: 20 6f 70 65 6e 20 66 69 6c 65 20 75 73 69 6e 67   open file using
9080: 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
9090: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _file_control()]
90a0: 20 69 6e 74 65 72 66 61 63 65 2e 20 20 54 68 65   interface.  The
90b0: 20 73 65 63 6f 6e 64 20 22 6f 70 22 20 61 72 67   second "op" arg
90c0: 75 6d 65 6e 74 20 69 73 20 61 6e 0a 2a 2a 20 69  ument is an.** i
90d0: 6e 74 65 67 65 72 20 6f 70 63 6f 64 65 2e 20 20  nteger opcode.  
90e0: 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  The third argume
90f0: 6e 74 20 69 73 20 61 20 67 65 6e 65 72 69 63 20  nt is a generic 
9100: 70 6f 69 6e 74 65 72 20 69 6e 74 65 6e 64 65 64  pointer intended
9110: 20 74 6f 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20   to.** point to 
9120: 61 20 73 74 72 75 63 74 75 72 65 20 74 68 61 74  a structure that
9130: 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 61 72 67   may contain arg
9140: 75 6d 65 6e 74 73 20 6f 72 20 73 70 61 63 65 20  uments or space 
9150: 69 6e 20 77 68 69 63 68 20 74 6f 0a 2a 2a 20 77  in which to.** w
9160: 72 69 74 65 20 72 65 74 75 72 6e 20 76 61 6c 75  rite return valu
9170: 65 73 2e 20 20 50 6f 74 65 6e 74 69 61 6c 20 75  es.  Potential u
9180: 73 65 73 20 66 6f 72 20 78 46 69 6c 65 43 6f 6e  ses for xFileCon
9190: 74 72 6f 6c 28 29 20 6d 69 67 68 74 20 62 65 0a  trol() might be.
91a0: 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 20  ** functions to 
91b0: 65 6e 61 62 6c 65 20 62 6c 6f 63 6b 69 6e 67 20  enable blocking 
91c0: 6c 6f 63 6b 73 20 77 69 74 68 20 74 69 6d 65 6f  locks with timeo
91d0: 75 74 73 2c 20 74 6f 20 63 68 61 6e 67 65 20 74  uts, to change t
91e0: 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e 67 20 73 74  he.** locking st
91f0: 72 61 74 65 67 79 20 28 66 6f 72 20 65 78 61 6d  rategy (for exam
9200: 70 6c 65 20 74 6f 20 75 73 65 20 64 6f 74 2d 66  ple to use dot-f
9210: 69 6c 65 20 6c 6f 63 6b 73 29 2c 20 74 6f 20 69  ile locks), to i
9220: 6e 71 75 69 72 65 0a 2a 2a 20 61 62 6f 75 74 20  nquire.** about 
9230: 74 68 65 20 73 74 61 74 75 73 20 6f 66 20 61 20  the status of a 
9240: 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20 62 72 65 61  lock, or to brea
9250: 6b 20 73 74 61 6c 65 20 6c 6f 63 6b 73 2e 20 20  k stale locks.  
9260: 54 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20 63 6f  The SQLite.** co
9270: 72 65 20 72 65 73 65 72 76 65 73 20 61 6c 6c 20  re reserves all 
9280: 6f 70 63 6f 64 65 73 20 6c 65 73 73 20 74 68 61  opcodes less tha
9290: 6e 20 31 30 30 20 66 6f 72 20 69 74 73 20 6f 77  n 100 for its ow
92a0: 6e 20 75 73 65 2e 0a 2a 2a 20 41 20 5b 66 69 6c  n use..** A [fil
92b0: 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65  e control opcode
92c0: 73 20 7c 20 6c 69 73 74 20 6f 66 20 6f 70 63 6f  s | list of opco
92d0: 64 65 73 5d 20 6c 65 73 73 20 74 68 61 6e 20 31  des] less than 1
92e0: 30 30 20 69 73 20 61 76 61 69 6c 61 62 6c 65 2e  00 is available.
92f0: 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  .** Applications
9300: 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 20 63   that define a c
9310: 75 73 74 6f 6d 20 78 46 69 6c 65 43 6f 6e 74 72  ustom xFileContr
9320: 6f 6c 20 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64  ol method should
9330: 20 75 73 65 20 6f 70 63 6f 64 65 73 0a 2a 2a 20   use opcodes.** 
9340: 67 72 65 61 74 65 72 20 74 68 61 6e 20 31 30 30  greater than 100
9350: 20 74 6f 20 61 76 6f 69 64 20 63 6f 6e 66 6c 69   to avoid confli
9360: 63 74 73 2e 20 20 56 46 53 20 69 6d 70 6c 65 6d  cts.  VFS implem
9370: 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64  entations should
9380: 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  .** return [SQLI
9390: 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 20 66 6f 72  TE_NOTFOUND] for
93a0: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70   file control op
93b0: 63 6f 64 65 73 20 74 68 61 74 20 74 68 65 79 20  codes that they 
93c0: 64 6f 20 6e 6f 74 0a 2a 2a 20 72 65 63 6f 67 6e  do not.** recogn
93d0: 69 7a 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ize..**.** The x
93e0: 53 65 63 74 6f 72 53 69 7a 65 28 29 20 6d 65 74  SectorSize() met
93f0: 68 6f 64 20 72 65 74 75 72 6e 73 20 74 68 65 20  hod returns the 
9400: 73 65 63 74 6f 72 20 73 69 7a 65 20 6f 66 20 74  sector size of t
9410: 68 65 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 61  he.** device tha
9420: 74 20 75 6e 64 65 72 6c 69 65 73 20 74 68 65 20  t underlies the 
9430: 66 69 6c 65 2e 20 20 54 68 65 20 73 65 63 74 6f  file.  The secto
9440: 72 20 73 69 7a 65 20 69 73 20 74 68 65 0a 2a 2a  r size is the.**
9450: 20 6d 69 6e 69 6d 75 6d 20 77 72 69 74 65 20 74   minimum write t
9460: 68 61 74 20 63 61 6e 20 62 65 20 70 65 72 66 6f  hat can be perfo
9470: 72 6d 65 64 20 77 69 74 68 6f 75 74 20 64 69 73  rmed without dis
9480: 74 75 72 62 69 6e 67 0a 2a 2a 20 6f 74 68 65 72  turbing.** other
9490: 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 66 69   bytes in the fi
94a0: 6c 65 2e 20 20 54 68 65 20 78 44 65 76 69 63 65  le.  The xDevice
94b0: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 28  Characteristics(
94c0: 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75  ).** method retu
94d0: 72 6e 73 20 61 20 62 69 74 20 76 65 63 74 6f 72  rns a bit vector
94e0: 20 64 65 73 63 72 69 62 69 6e 67 20 62 65 68 61   describing beha
94f0: 76 69 6f 72 73 20 6f 66 20 74 68 65 0a 2a 2a 20  viors of the.** 
9500: 75 6e 64 65 72 6c 79 69 6e 67 20 64 65 76 69 63  underlying devic
9510: 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  e:.**.** <ul>.**
9520: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
9530: 43 41 50 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c  CAP_ATOMIC].** <
9540: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
9550: 50 5f 41 54 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20  P_ATOMIC512].** 
9560: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
9570: 41 50 5f 41 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20  AP_ATOMIC1K].** 
9580: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
9590: 41 50 5f 41 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20  AP_ATOMIC2K].** 
95a0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
95b0: 41 50 5f 41 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20  AP_ATOMIC4K].** 
95c0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
95d0: 41 50 5f 41 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20  AP_ATOMIC8K].** 
95e0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
95f0: 41 50 5f 41 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a  AP_ATOMIC16K].**
9600: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
9610: 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a  CAP_ATOMIC32K].*
9620: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
9630: 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a  OCAP_ATOMIC64K].
9640: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
9650: 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e  IOCAP_SAFE_APPEN
9660: 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  D].** <li> [SQLI
9670: 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54  TE_IOCAP_SEQUENT
9680: 49 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  IAL].** </ul>.**
9690: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 49  .** The SQLITE_I
96a0: 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70  OCAP_ATOMIC prop
96b0: 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20  erty means that 
96c0: 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a  all writes of.**
96d0: 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20 61 74   any size are at
96e0: 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54  omic.  The SQLIT
96f0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e  E_IOCAP_ATOMICnn
9700: 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e  n values.** mean
9710: 20 74 68 61 74 20 77 72 69 74 65 73 20 6f 66 20   that writes of 
9720: 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 65 20  blocks that are 
9730: 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 69 7a  nnn bytes in siz
9740: 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69  e and.** are ali
9750: 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 72 65  gned to an addre
9760: 73 73 20 77 68 69 63 68 20 69 73 20 61 6e 20 69  ss which is an i
9770: 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c 65 20  nteger multiple 
9780: 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74  of.** nnn are at
9790: 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54  omic.  The SQLIT
97a0: 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50  E_IOCAP_SAFE_APP
97b0: 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a  END value means.
97c0: 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64 61 74  ** that when dat
97d0: 61 20 69 73 20 61 70 70 65 6e 64 65 64 20 74 6f  a is appended to
97e0: 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74   a file, the dat
97f0: 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a  a is appended.**
9800: 20 66 69 72 73 74 20 74 68 65 6e 20 74 68 65 20   first then the 
9810: 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69 6c 65  size of the file
9820: 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20 6e 65   is extended, ne
9830: 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a  ver the other.**
9840: 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 54 68   way around.  Th
9850: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53  e SQLITE_IOCAP_S
9860: 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 65 72  EQUENTIAL proper
9870: 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a  ty means that.**
9880: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20   information is 
9890: 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 20  written to disk 
98a0: 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 64 65  in the same orde
98b0: 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f  r as calls.** to
98c0: 20 78 57 72 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a   xWrite()..**.**
98d0: 20 49 66 20 78 52 65 61 64 28 29 20 72 65 74 75   If xRead() retu
98e0: 72 6e 73 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  rns SQLITE_IOERR
98f0: 5f 53 48 4f 52 54 5f 52 45 41 44 20 69 74 20 6d  _SHORT_READ it m
9900: 75 73 74 20 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a  ust also fill.**
9910: 20 69 6e 20 74 68 65 20 75 6e 72 65 61 64 20 70   in the unread p
9920: 6f 72 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 62  ortions of the b
9930: 75 66 66 65 72 20 77 69 74 68 20 7a 65 72 6f 73  uffer with zeros
9940: 2e 20 20 41 20 56 46 53 20 74 68 61 74 0a 2a 2a  .  A VFS that.**
9950: 20 66 61 69 6c 73 20 74 6f 20 7a 65 72 6f 2d 66   fails to zero-f
9960: 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20  ill short reads 
9970: 6d 69 67 68 74 20 73 65 65 6d 20 74 6f 20 77 6f  might seem to wo
9980: 72 6b 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a  rk.  However,.**
9990: 20 66 61 69 6c 75 72 65 20 74 6f 20 7a 65 72 6f   failure to zero
99a0: 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 64  -fill short read
99b0: 73 20 77 69 6c 6c 20 65 76 65 6e 74 75 61 6c 6c  s will eventuall
99c0: 79 20 6c 65 61 64 20 74 6f 0a 2a 2a 20 64 61 74  y lead to.** dat
99d0: 61 62 61 73 65 20 63 6f 72 72 75 70 74 69 6f 6e  abase corruption
99e0: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
99f0: 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  uct sqlite3_io_m
9a00: 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 69  ethods sqlite3_i
9a10: 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63  o_methods;.struc
9a20: 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74  t sqlite3_io_met
9a30: 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20 69 56 65  hods {.  int iVe
9a40: 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78  rsion;.  int (*x
9a50: 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 66  Close)(sqlite3_f
9a60: 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  ile*);.  int (*x
9a70: 52 65 61 64 29 28 73 71 6c 69 74 65 33 5f 66 69  Read)(sqlite3_fi
9a80: 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20 69 6e 74 20  le*, void*, int 
9a90: 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e  iAmt, sqlite3_in
9aa0: 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e  t64 iOfst);.  in
9ab0: 74 20 28 2a 78 57 72 69 74 65 29 28 73 71 6c 69  t (*xWrite)(sqli
9ac0: 74 65 33 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73 74  te3_file*, const
9ad0: 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74   void*, int iAmt
9ae0: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
9af0: 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a  iOfst);.  int (*
9b00: 78 54 72 75 6e 63 61 74 65 29 28 73 71 6c 69 74  xTruncate)(sqlit
9b10: 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65  e3_file*, sqlite
9b20: 33 5f 69 6e 74 36 34 20 73 69 7a 65 29 3b 0a 20  3_int64 size);. 
9b30: 20 69 6e 74 20 28 2a 78 53 79 6e 63 29 28 73 71   int (*xSync)(sq
9b40: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
9b50: 20 66 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28   flags);.  int (
9b60: 2a 78 46 69 6c 65 53 69 7a 65 29 28 73 71 6c 69  *xFileSize)(sqli
9b70: 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74  te3_file*, sqlit
9b80: 65 33 5f 69 6e 74 36 34 20 2a 70 53 69 7a 65 29  e3_int64 *pSize)
9b90: 3b 0a 20 20 69 6e 74 20 28 2a 78 4c 6f 63 6b 29  ;.  int (*xLock)
9ba0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
9bb0: 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55  int);.  int (*xU
9bc0: 6e 6c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66  nlock)(sqlite3_f
9bd0: 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e  ile*, int);.  in
9be0: 74 20 28 2a 78 43 68 65 63 6b 52 65 73 65 72 76  t (*xCheckReserv
9bf0: 65 64 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f  edLock)(sqlite3_
9c00: 66 69 6c 65 2a 2c 20 69 6e 74 20 2a 70 52 65 73  file*, int *pRes
9c10: 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46  Out);.  int (*xF
9c20: 69 6c 65 43 6f 6e 74 72 6f 6c 29 28 73 71 6c 69  ileControl)(sqli
9c30: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f  te3_file*, int o
9c40: 70 2c 20 76 6f 69 64 20 2a 70 41 72 67 29 3b 0a  p, void *pArg);.
9c50: 20 20 69 6e 74 20 28 2a 78 53 65 63 74 6f 72 53    int (*xSectorS
9c60: 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ize)(sqlite3_fil
9c70: 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65  e*);.  int (*xDe
9c80: 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74  viceCharacterist
9c90: 69 63 73 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ics)(sqlite3_fil
9ca0: 65 2a 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64  e*);.  /* Method
9cb0: 73 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69  s above are vali
9cc0: 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 31 20  d for version 1 
9cd0: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 4d  */.  int (*xShmM
9ce0: 61 70 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ap)(sqlite3_file
9cf0: 2a 2c 20 69 6e 74 20 69 50 67 2c 20 69 6e 74 20  *, int iPg, int 
9d00: 70 67 73 7a 2c 20 69 6e 74 2c 20 76 6f 69 64 20  pgsz, int, void 
9d10: 76 6f 6c 61 74 69 6c 65 2a 2a 29 3b 0a 20 20 69  volatile**);.  i
9d20: 6e 74 20 28 2a 78 53 68 6d 4c 6f 63 6b 29 28 73  nt (*xShmLock)(s
9d30: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
9d40: 74 20 6f 66 66 73 65 74 2c 20 69 6e 74 20 6e 2c  t offset, int n,
9d50: 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 76   int flags);.  v
9d60: 6f 69 64 20 28 2a 78 53 68 6d 42 61 72 72 69 65  oid (*xShmBarrie
9d70: 72 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  r)(sqlite3_file*
9d80: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 55  );.  int (*xShmU
9d90: 6e 6d 61 70 29 28 73 71 6c 69 74 65 33 5f 66 69  nmap)(sqlite3_fi
9da0: 6c 65 2a 2c 20 69 6e 74 20 64 65 6c 65 74 65 46  le*, int deleteF
9db0: 6c 61 67 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f  lag);.  /* Metho
9dc0: 64 73 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c  ds above are val
9dd0: 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 32  id for version 2
9de0: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 46 65 74   */.  int (*xFet
9df0: 63 68 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ch)(sqlite3_file
9e00: 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
9e10: 20 69 4f 66 73 74 2c 20 69 6e 74 20 69 41 6d 74   iOfst, int iAmt
9e20: 2c 20 76 6f 69 64 20 2a 2a 70 70 29 3b 0a 20 20  , void **pp);.  
9e30: 69 6e 74 20 28 2a 78 55 6e 66 65 74 63 68 29 28  int (*xUnfetch)(
9e40: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73  sqlite3_file*, s
9e50: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66  qlite3_int64 iOf
9e60: 73 74 2c 20 76 6f 69 64 20 2a 70 29 3b 0a 20 20  st, void *p);.  
9e70: 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65  /* Methods above
9e80: 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76   are valid for v
9e90: 65 72 73 69 6f 6e 20 33 20 2a 2f 0a 20 20 2f 2a  ersion 3 */.  /*
9ea0: 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 74 68   Additional meth
9eb0: 6f 64 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  ods may be added
9ec0: 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
9ed0: 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  ses */.};../*.**
9ee0: 20 43 41 50 49 33 52 45 46 3a 20 53 74 61 6e 64   CAPI3REF: Stand
9ef0: 61 72 64 20 46 69 6c 65 20 43 6f 6e 74 72 6f 6c  ard File Control
9f00: 20 4f 70 63 6f 64 65 73 0a 2a 2a 20 4b 45 59 57   Opcodes.** KEYW
9f10: 4f 52 44 53 3a 20 7b 66 69 6c 65 20 63 6f 6e 74  ORDS: {file cont
9f20: 72 6f 6c 20 6f 70 63 6f 64 65 73 7d 20 7b 66 69  rol opcodes} {fi
9f30: 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64  le control opcod
9f40: 65 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69  e}.**.** These i
9f50: 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73  nteger constants
9f60: 20 61 72 65 20 6f 70 63 6f 64 65 73 20 66 6f 72   are opcodes for
9f70: 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f   the xFileContro
9f80: 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74  l method.** of t
9f90: 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  he [sqlite3_io_m
9fa0: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 61  ethods] object a
9fb0: 6e 64 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69  nd for the [sqli
9fc0: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
9fd0: 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  ()].** interface
9fe0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ..**.** The [SQL
9ff0: 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54  ITE_FCNTL_LOCKST
a000: 41 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75  ATE] opcode is u
a010: 73 65 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e  sed for debuggin
a020: 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f  g.  This.** opco
a030: 64 65 20 63 61 75 73 65 73 20 74 68 65 20 78 46  de causes the xF
a040: 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f  ileControl metho
a050: 64 20 74 6f 20 77 72 69 74 65 20 74 68 65 20 63  d to write the c
a060: 75 72 72 65 6e 74 20 73 74 61 74 65 20 6f 66 0a  urrent state of.
a070: 2a 2a 20 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65  ** the lock (one
a080: 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b   of [SQLITE_LOCK
a090: 5f 4e 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f  _NONE], [SQLITE_
a0a0: 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a  LOCK_SHARED],.**
a0b0: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45   [SQLITE_LOCK_RE
a0c0: 53 45 52 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45  SERVED], [SQLITE
a0d0: 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20  _LOCK_PENDING], 
a0e0: 6f 72 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  or [SQLITE_LOCK_
a0f0: 45 58 43 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69  EXCLUSIVE]).** i
a100: 6e 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 74  nto an integer t
a110: 68 61 74 20 74 68 65 20 70 41 72 67 20 61 72 67  hat the pArg arg
a120: 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e  ument points to.
a130: 20 54 68 69 73 20 63 61 70 61 62 69 6c 69 74 79   This capability
a140: 0a 2a 2a 20 69 73 20 75 73 65 64 20 64 75 72 69  .** is used duri
a150: 6e 67 20 74 65 73 74 69 6e 67 20 61 6e 64 20 6f  ng testing and o
a160: 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 62 65 20  nly needs to be 
a170: 73 75 70 70 6f 72 74 65 64 20 77 68 65 6e 20 53  supported when S
a180: 51 4c 49 54 45 5f 54 45 53 54 0a 2a 2a 20 69 73  QLITE_TEST.** is
a190: 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 3c 75 6c   defined..** <ul
a1a0: 3e 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  >.** <li>[[SQLIT
a1b0: 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e  E_FCNTL_SIZE_HIN
a1c0: 54 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  T]].** The [SQLI
a1d0: 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49  TE_FCNTL_SIZE_HI
a1e0: 4e 54 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  NT] opcode is us
a1f0: 65 64 20 62 79 20 53 51 4c 69 74 65 20 74 6f 20  ed by SQLite to 
a200: 67 69 76 65 20 74 68 65 20 56 46 53 0a 2a 2a 20  give the VFS.** 
a210: 6c 61 79 65 72 20 61 20 68 69 6e 74 20 6f 66 20  layer a hint of 
a220: 68 6f 77 20 6c 61 72 67 65 20 74 68 65 20 64 61  how large the da
a230: 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c  tabase file will
a240: 20 67 72 6f 77 20 74 6f 20 62 65 20 64 75 72 69   grow to be duri
a250: 6e 67 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e  ng the.** curren
a260: 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 20  t transaction.  
a270: 54 68 69 73 20 68 69 6e 74 20 69 73 20 6e 6f 74  This hint is not
a280: 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62   guaranteed to b
a290: 65 20 61 63 63 75 72 61 74 65 20 62 75 74 20 69  e accurate but i
a2a0: 74 0a 2a 2a 20 69 73 20 6f 66 74 65 6e 20 63 6c  t.** is often cl
a2b0: 6f 73 65 2e 20 20 54 68 65 20 75 6e 64 65 72 6c  ose.  The underl
a2c0: 79 69 6e 67 20 56 46 53 20 6d 69 67 68 74 20 63  ying VFS might c
a2d0: 68 6f 6f 73 65 20 74 6f 20 70 72 65 61 6c 6c 6f  hoose to preallo
a2e0: 63 61 74 65 20 64 61 74 61 62 61 73 65 0a 2a 2a  cate database.**
a2f0: 20 66 69 6c 65 20 73 70 61 63 65 20 62 61 73 65   file space base
a300: 64 20 6f 6e 20 74 68 69 73 20 68 69 6e 74 20 69  d on this hint i
a310: 6e 20 6f 72 64 65 72 20 74 6f 20 68 65 6c 70 20  n order to help 
a320: 77 72 69 74 65 73 20 74 6f 20 74 68 65 20 64 61  writes to the da
a330: 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 72  tabase.** file r
a340: 75 6e 20 66 61 73 74 65 72 2e 0a 2a 2a 0a 2a 2a  un faster..**.**
a350: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
a360: 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 5d  NTL_CHUNK_SIZE]]
a370: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
a380: 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45  FCNTL_CHUNK_SIZE
a390: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
a3a0: 20 74 6f 20 72 65 71 75 65 73 74 20 74 68 61 74   to request that
a3b0: 20 74 68 65 20 56 46 53 0a 2a 2a 20 65 78 74 65   the VFS.** exte
a3c0: 6e 64 73 20 61 6e 64 20 74 72 75 6e 63 61 74 65  nds and truncate
a3d0: 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  s the database f
a3e0: 69 6c 65 20 69 6e 20 63 68 75 6e 6b 73 20 6f 66  ile in chunks of
a3f0: 20 61 20 73 69 7a 65 20 73 70 65 63 69 66 69 65   a size specifie
a400: 64 0a 2a 2a 20 62 79 20 74 68 65 20 75 73 65 72  d.** by the user
a410: 2e 20 54 68 65 20 66 6f 75 72 74 68 20 61 72 67  . The fourth arg
a420: 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65  ument to [sqlite
a430: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
a440: 5d 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 70 6f 69  ] should .** poi
a450: 6e 74 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  nt to an integer
a460: 20 28 74 79 70 65 20 69 6e 74 29 20 63 6f 6e 74   (type int) cont
a470: 61 69 6e 69 6e 67 20 74 68 65 20 6e 65 77 20 63  aining the new c
a480: 68 75 6e 6b 2d 73 69 7a 65 20 74 6f 20 75 73 65  hunk-size to use
a490: 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6e 6f 6d 69  .** for the nomi
a4a0: 6e 61 74 65 64 20 64 61 74 61 62 61 73 65 2e 20  nated database. 
a4b0: 41 6c 6c 6f 63 61 74 69 6e 67 20 64 61 74 61 62  Allocating datab
a4c0: 61 73 65 20 66 69 6c 65 20 73 70 61 63 65 20 69  ase file space i
a4d0: 6e 20 6c 61 72 67 65 0a 2a 2a 20 63 68 75 6e 6b  n large.** chunk
a4e0: 73 20 28 73 61 79 20 31 4d 42 20 61 74 20 61 20  s (say 1MB at a 
a4f0: 74 69 6d 65 29 2c 20 6d 61 79 20 72 65 64 75 63  time), may reduc
a500: 65 20 66 69 6c 65 2d 73 79 73 74 65 6d 20 66 72  e file-system fr
a510: 61 67 6d 65 6e 74 61 74 69 6f 6e 20 61 6e 64 0a  agmentation and.
a520: 2a 2a 20 69 6d 70 72 6f 76 65 20 70 65 72 66 6f  ** improve perfo
a530: 72 6d 61 6e 63 65 20 6f 6e 20 73 6f 6d 65 20 73  rmance on some s
a540: 79 73 74 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  ystems..**.** <l
a550: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
a560: 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 5d 0a  _FILE_POINTER]].
a570: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
a580: 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45  CNTL_FILE_POINTE
a590: 52 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  R] opcode is use
a5a0: 64 20 74 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f  d to obtain a po
a5b0: 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  inter.** to the 
a5c0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f  [sqlite3_file] o
a5d0: 62 6a 65 63 74 20 61 73 73 6f 63 69 61 74 65 64  bject associated
a5e0: 20 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c   with a particul
a5f0: 61 72 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  ar database.** c
a600: 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 53 65 65 20  onnection.  See 
a610: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  the [sqlite3_fil
a620: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 64 6f 63  e_control()] doc
a630: 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a  umentation for.*
a640: 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66  * additional inf
a650: 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  ormation..**.** 
a660: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
a670: 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 5d  TL_SYNC_OMITTED]
a680: 5d 0a 2a 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 69  ].** No longer i
a690: 6e 20 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  n use..**.** <li
a6a0: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
a6b0: 53 59 4e 43 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  SYNC]].** The [S
a6c0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43  QLITE_FCNTL_SYNC
a6d0: 5d 20 6f 70 63 6f 64 65 20 69 73 20 67 65 6e 65  ] opcode is gene
a6e0: 72 61 74 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79  rated internally
a6f0: 20 62 79 20 53 51 4c 69 74 65 20 61 6e 64 0a 2a   by SQLite and.*
a700: 2a 20 73 65 6e 74 20 74 6f 20 74 68 65 20 56 46  * sent to the VF
a710: 53 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 62 65  S immediately be
a720: 66 6f 72 65 20 74 68 65 20 78 53 79 6e 63 20 6d  fore the xSync m
a730: 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64  ethod is invoked
a740: 20 6f 6e 20 61 0a 2a 2a 20 64 61 74 61 62 61 73   on a.** databas
a750: 65 20 66 69 6c 65 20 64 65 73 63 72 69 70 74 6f  e file descripto
a760: 72 2e 20 4f 72 2c 20 69 66 20 74 68 65 20 78 53  r. Or, if the xS
a770: 79 6e 63 20 6d 65 74 68 6f 64 20 69 73 20 6e 6f  ync method is no
a780: 74 20 69 6e 76 6f 6b 65 64 20 0a 2a 2a 20 62 65  t invoked .** be
a790: 63 61 75 73 65 20 74 68 65 20 75 73 65 72 20 68  cause the user h
a7a0: 61 73 20 63 6f 6e 66 69 67 75 72 65 64 20 53 51  as configured SQ
a7b0: 4c 69 74 65 20 77 69 74 68 20 0a 2a 2a 20 5b 50  Lite with .** [P
a7c0: 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75  RAGMA synchronou
a7d0: 73 20 7c 20 50 52 41 47 4d 41 20 73 79 6e 63 68  s | PRAGMA synch
a7e0: 72 6f 6e 6f 75 73 3d 4f 46 46 5d 20 69 74 20 69  ronous=OFF] it i
a7f0: 73 20 69 6e 76 6f 6b 65 64 20 69 6e 20 70 6c 61  s invoked in pla
a800: 63 65 20 0a 2a 2a 20 6f 66 20 74 68 65 20 78 53  ce .** of the xS
a810: 79 6e 63 20 6d 65 74 68 6f 64 2e 20 49 6e 20 6d  ync method. In m
a820: 6f 73 74 20 63 61 73 65 73 2c 20 74 68 65 20 70  ost cases, the p
a830: 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 20  ointer argument 
a840: 70 61 73 73 65 64 20 77 69 74 68 0a 2a 2a 20 74  passed with.** t
a850: 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c  his file-control
a860: 20 69 73 20 4e 55 4c 4c 2e 20 48 6f 77 65 76 65   is NULL. Howeve
a870: 72 2c 20 69 66 20 74 68 65 20 64 61 74 61 62 61  r, if the databa
a880: 73 65 20 66 69 6c 65 20 69 73 20 62 65 69 6e 67  se file is being
a890: 20 73 79 6e 63 65 64 0a 2a 2a 20 61 73 20 70 61   synced.** as pa
a8a0: 72 74 20 6f 66 20 61 20 6d 75 6c 74 69 2d 64 61  rt of a multi-da
a8b0: 74 61 62 61 73 65 20 63 6f 6d 6d 69 74 2c 20 74  tabase commit, t
a8c0: 68 65 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e  he argument poin
a8d0: 74 73 20 74 6f 20 61 20 6e 75 6c 2d 74 65 72 6d  ts to a nul-term
a8e0: 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67  inated.** string
a8f0: 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20   containing the 
a900: 74 72 61 6e 73 61 63 74 69 6f 6e 73 20 6d 61 73  transactions mas
a910: 74 65 72 2d 6a 6f 75 72 6e 61 6c 20 66 69 6c 65  ter-journal file
a920: 20 6e 61 6d 65 2e 20 56 46 53 65 73 20 74 68 61   name. VFSes tha
a930: 74 20 0a 2a 2a 20 64 6f 20 6e 6f 74 20 6e 65 65  t .** do not nee
a940: 64 20 74 68 69 73 20 73 69 67 6e 61 6c 20 73 68  d this signal sh
a950: 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69 67  ould silently ig
a960: 6e 6f 72 65 20 74 68 69 73 20 6f 70 63 6f 64 65  nore this opcode
a970: 2e 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 0a  . Applications .
a980: 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61  ** should not ca
a990: 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ll [sqlite3_file
a9a0: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68  _control()] with
a9b0: 20 74 68 69 73 20 6f 70 63 6f 64 65 20 61 73 20   this opcode as 
a9c0: 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20 0a 2a 2a  doing so may .**
a9d0: 20 64 69 73 72 75 70 74 20 74 68 65 20 6f 70 65   disrupt the ope
a9e0: 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 70  ration of the sp
a9f0: 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65 73 20  ecialized VFSes 
aa00: 74 68 61 74 20 64 6f 20 72 65 71 75 69 72 65 20  that do require 
aa10: 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  it.  .**.** <li>
aa20: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43  [[SQLITE_FCNTL_C
aa30: 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f 5d 5d  OMMIT_PHASETWO]]
aa40: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
aa50: 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41  FCNTL_COMMIT_PHA
aa60: 53 45 54 57 4f 5d 20 6f 70 63 6f 64 65 20 69 73  SETWO] opcode is
aa70: 20 67 65 6e 65 72 61 74 65 64 20 69 6e 74 65 72   generated inter
aa80: 6e 61 6c 6c 79 20 62 79 20 53 51 4c 69 74 65 0a  nally by SQLite.
aa90: 2a 2a 20 61 6e 64 20 73 65 6e 74 20 74 6f 20 74  ** and sent to t
aaa0: 68 65 20 56 46 53 20 61 66 74 65 72 20 61 20 74  he VFS after a t
aab0: 72 61 6e 73 61 63 74 69 6f 6e 20 68 61 73 20 62  ransaction has b
aac0: 65 65 6e 20 63 6f 6d 6d 69 74 74 65 64 20 69 6d  een committed im
aad0: 6d 65 64 69 61 74 65 6c 79 0a 2a 2a 20 62 75 74  mediately.** but
aae0: 20 62 65 66 6f 72 65 20 74 68 65 20 64 61 74 61   before the data
aaf0: 62 61 73 65 20 69 73 20 75 6e 6c 6f 63 6b 65 64  base is unlocked
ab00: 2e 20 56 46 53 65 73 20 74 68 61 74 20 64 6f 20  . VFSes that do 
ab10: 6e 6f 74 20 6e 65 65 64 20 74 68 69 73 20 73 69  not need this si
ab20: 67 6e 61 6c 0a 2a 2a 20 73 68 6f 75 6c 64 20 73  gnal.** should s
ab30: 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74  ilently ignore t
ab40: 68 69 73 20 6f 70 63 6f 64 65 2e 20 41 70 70 6c  his opcode. Appl
ab50: 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20  ications should 
ab60: 6e 6f 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c  not call.** [sql
ab70: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
ab80: 6c 28 29 5d 20 77 69 74 68 20 74 68 69 73 20 6f  l()] with this o
ab90: 70 63 6f 64 65 20 61 73 20 64 6f 69 6e 67 20 73  pcode as doing s
aba0: 6f 20 6d 61 79 20 64 69 73 72 75 70 74 20 74 68  o may disrupt th
abb0: 65 20 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20  e .** operation 
abc0: 6f 66 20 74 68 65 20 73 70 65 63 69 61 6c 69 7a  of the specializ
abd0: 65 64 20 56 46 53 65 73 20 74 68 61 74 20 64 6f  ed VFSes that do
abe0: 20 72 65 71 75 69 72 65 20 69 74 2e 20 20 0a 2a   require it.  .*
abf0: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
ac00: 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56  E_FCNTL_WIN32_AV
ac10: 5f 52 45 54 52 59 5d 5d 0a 2a 2a 20 5e 54 68 65  _RETRY]].** ^The
ac20: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57   [SQLITE_FCNTL_W
ac30: 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d 20 6f  IN32_AV_RETRY] o
ac40: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f  pcode is used to
ac50: 20 63 6f 6e 66 69 67 75 72 65 20 61 75 74 6f 6d   configure autom
ac60: 61 74 69 63 0a 2a 2a 20 72 65 74 72 79 20 63 6f  atic.** retry co
ac70: 75 6e 74 73 20 61 6e 64 20 69 6e 74 65 72 76 61  unts and interva
ac80: 6c 73 20 66 6f 72 20 63 65 72 74 61 69 6e 20 64  ls for certain d
ac90: 69 73 6b 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f  isk I/O operatio
aca0: 6e 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 77 69  ns for the.** wi
acb0: 6e 64 6f 77 73 20 5b 56 46 53 5d 20 69 6e 20 6f  ndows [VFS] in o
acc0: 72 64 65 72 20 74 6f 20 70 72 6f 76 69 64 65 20  rder to provide 
acd0: 72 6f 62 75 73 74 6e 65 73 73 20 69 6e 20 74 68  robustness in th
ace0: 65 20 70 72 65 73 65 6e 63 65 20 6f 66 0a 2a 2a  e presence of.**
acf0: 20 61 6e 74 69 2d 76 69 72 75 73 20 70 72 6f 67   anti-virus prog
ad00: 72 61 6d 73 2e 20 20 42 79 20 64 65 66 61 75 6c  rams.  By defaul
ad10: 74 2c 20 74 68 65 20 77 69 6e 64 6f 77 73 20 56  t, the windows V
ad20: 46 53 20 77 69 6c 6c 20 72 65 74 72 79 20 66 69  FS will retry fi
ad30: 6c 65 20 72 65 61 64 2c 0a 2a 2a 20 66 69 6c 65  le read,.** file
ad40: 20 77 72 69 74 65 2c 20 61 6e 64 20 66 69 6c 65   write, and file
ad50: 20 64 65 6c 65 74 65 20 6f 70 65 72 61 74 69 6f   delete operatio
ad60: 6e 73 20 75 70 20 74 6f 20 31 30 20 74 69 6d 65  ns up to 10 time
ad70: 73 2c 20 77 69 74 68 20 61 20 64 65 6c 61 79 0a  s, with a delay.
ad80: 2a 2a 20 6f 66 20 32 35 20 6d 69 6c 6c 69 73 65  ** of 25 millise
ad90: 63 6f 6e 64 73 20 62 65 66 6f 72 65 20 74 68 65  conds before the
ada0: 20 66 69 72 73 74 20 72 65 74 72 79 20 61 6e 64   first retry and
adb0: 20 77 69 74 68 20 74 68 65 20 64 65 6c 61 79 20   with the delay 
adc0: 69 6e 63 72 65 61 73 69 6e 67 0a 2a 2a 20 62 79  increasing.** by
add0: 20 61 6e 20 61 64 64 69 74 69 6f 6e 61 6c 20 32   an additional 2
ade0: 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 77  5 milliseconds w
adf0: 69 74 68 20 65 61 63 68 20 73 75 62 73 65 71 75  ith each subsequ
ae00: 65 6e 74 20 72 65 74 72 79 2e 20 20 54 68 69 73  ent retry.  This
ae10: 0a 2a 2a 20 6f 70 63 6f 64 65 20 61 6c 6c 6f 77  .** opcode allow
ae20: 73 20 74 68 65 73 65 20 74 77 6f 20 76 61 6c 75  s these two valu
ae30: 65 73 20 28 31 30 20 72 65 74 72 69 65 73 20 61  es (10 retries a
ae40: 6e 64 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e  nd 25 millisecon
ae50: 64 73 20 6f 66 20 64 65 6c 61 79 29 0a 2a 2a 20  ds of delay).** 
ae60: 74 6f 20 62 65 20 61 64 6a 75 73 74 65 64 2e 20  to be adjusted. 
ae70: 20 54 68 65 20 76 61 6c 75 65 73 20 61 72 65 20   The values are 
ae80: 63 68 61 6e 67 65 64 20 66 6f 72 20 61 6c 6c 20  changed for all 
ae90: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
aea0: 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 69 6e 20 74  ions.** within t
aeb0: 68 65 20 73 61 6d 65 20 70 72 6f 63 65 73 73 2e  he same process.
aec0: 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69    The argument i
aed0: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
aee0: 6e 20 61 72 72 61 79 20 6f 66 20 74 77 6f 0a 2a  n array of two.*
aef0: 2a 20 69 6e 74 65 67 65 72 73 20 77 68 65 72 65  * integers where
af00: 20 74 68 65 20 66 69 72 73 74 20 69 6e 74 65 67   the first integ
af10: 65 72 20 69 20 74 68 65 20 6e 65 77 20 72 65 74  er i the new ret
af20: 72 79 20 63 6f 75 6e 74 20 61 6e 64 20 74 68 65  ry count and the
af30: 20 73 65 63 6f 6e 64 0a 2a 2a 20 69 6e 74 65 67   second.** integ
af40: 65 72 20 69 73 20 74 68 65 20 64 65 6c 61 79 2e  er is the delay.
af50: 20 20 49 66 20 65 69 74 68 65 72 20 69 6e 74 65    If either inte
af60: 67 65 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c  ger is negative,
af70: 20 74 68 65 6e 20 74 68 65 20 73 65 74 74 69 6e   then the settin
af80: 67 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e  g.** is not chan
af90: 67 65 64 20 62 75 74 20 69 6e 73 74 65 61 64 20  ged but instead 
afa0: 74 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20  the prior value 
afb0: 6f 66 20 74 68 61 74 20 73 65 74 74 69 6e 67 20  of that setting 
afc0: 69 73 20 77 72 69 74 74 65 6e 0a 2a 2a 20 69 6e  is written.** in
afd0: 74 6f 20 74 68 65 20 61 72 72 61 79 20 65 6e 74  to the array ent
afe0: 72 79 2c 20 61 6c 6c 6f 77 69 6e 67 20 74 68 65  ry, allowing the
aff0: 20 63 75 72 72 65 6e 74 20 72 65 74 72 79 20 73   current retry s
b000: 65 74 74 69 6e 67 73 20 74 6f 20 62 65 0a 2a 2a  ettings to be.**
b010: 20 69 6e 74 65 72 72 6f 67 61 74 65 64 2e 20 20   interrogated.  
b020: 54 68 65 20 7a 44 62 4e 61 6d 65 20 70 61 72 61  The zDbName para
b030: 6d 65 74 65 72 20 69 73 20 69 67 6e 6f 72 65 64  meter is ignored
b040: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
b050: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49  LITE_FCNTL_PERSI
b060: 53 54 5f 57 41 4c 5d 5d 0a 2a 2a 20 5e 54 68 65  ST_WAL]].** ^The
b070: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50   [SQLITE_FCNTL_P
b080: 45 52 53 49 53 54 5f 57 41 4c 5d 20 6f 70 63 6f  ERSIST_WAL] opco
b090: 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 73 65  de is used to se
b0a0: 74 20 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a  t or query the.*
b0b0: 2a 20 70 65 72 73 69 73 74 65 6e 74 20 5b 57 41  * persistent [WA
b0c0: 4c 20 7c 20 57 72 69 74 65 20 41 68 65 61 64 20  L | Write Ahead 
b0d0: 4c 6f 67 5d 20 73 65 74 74 69 6e 67 2e 20 20 42  Log] setting.  B
b0e0: 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20 61  y default, the a
b0f0: 75 78 69 6c 69 61 72 79 0a 2a 2a 20 77 72 69 74  uxiliary.** writ
b100: 65 20 61 68 65 61 64 20 6c 6f 67 20 61 6e 64 20  e ahead log and 
b110: 73 68 61 72 65 64 20 6d 65 6d 6f 72 79 20 66 69  shared memory fi
b120: 6c 65 73 20 75 73 65 64 20 66 6f 72 20 74 72 61  les used for tra
b130: 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c  nsaction control
b140: 0a 2a 2a 20 61 72 65 20 61 75 74 6f 6d 61 74 69  .** are automati
b150: 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 77 68  cally deleted wh
b160: 65 6e 20 74 68 65 20 6c 61 74 65 73 74 20 63 6f  en the latest co
b170: 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 74 68 65 20  nnection to the 
b180: 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6c 6f 73  database.** clos
b190: 65 73 2e 20 20 53 65 74 74 69 6e 67 20 70 65 72  es.  Setting per
b1a0: 73 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65  sistent WAL mode
b1b0: 20 63 61 75 73 65 73 20 74 68 6f 73 65 20 66 69   causes those fi
b1c0: 6c 65 73 20 74 6f 20 70 65 72 73 69 73 74 20 61  les to persist a
b1d0: 66 74 65 72 0a 2a 2a 20 63 6c 6f 73 65 2e 20 20  fter.** close.  
b1e0: 50 65 72 73 69 73 74 69 6e 67 20 74 68 65 20 66  Persisting the f
b1f0: 69 6c 65 73 20 69 73 20 75 73 65 66 75 6c 20 77  iles is useful w
b200: 68 65 6e 20 6f 74 68 65 72 20 70 72 6f 63 65 73  hen other proces
b210: 73 65 73 20 74 68 61 74 20 64 6f 20 6e 6f 74 0a  ses that do not.
b220: 2a 2a 20 68 61 76 65 20 77 72 69 74 65 20 70 65  ** have write pe
b230: 72 6d 69 73 73 69 6f 6e 20 6f 6e 20 74 68 65 20  rmission on the 
b240: 64 69 72 65 63 74 6f 72 79 20 63 6f 6e 74 61 69  directory contai
b250: 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 73  ning the databas
b260: 65 20 66 69 6c 65 20 77 61 6e 74 0a 2a 2a 20 74  e file want.** t
b270: 6f 20 72 65 61 64 20 74 68 65 20 64 61 74 61 62  o read the datab
b280: 61 73 65 20 66 69 6c 65 2c 20 61 73 20 74 68 65  ase file, as the
b290: 20 57 41 4c 20 61 6e 64 20 73 68 61 72 65 64 20   WAL and shared 
b2a0: 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20 6d 75 73  memory files mus
b2b0: 74 20 65 78 69 73 74 0a 2a 2a 20 69 6e 20 6f 72  t exist.** in or
b2c0: 64 65 72 20 66 6f 72 20 74 68 65 20 64 61 74 61  der for the data
b2d0: 62 61 73 65 20 74 6f 20 62 65 20 72 65 61 64 61  base to be reada
b2e0: 62 6c 65 2e 20 20 54 68 65 20 66 6f 75 72 74 68  ble.  The fourth
b2f0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
b300: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
b310: 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68  ontrol()] for th
b320: 69 73 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64  is opcode should
b330: 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   be a pointer to
b340: 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20   an integer..** 
b350: 54 68 61 74 20 69 6e 74 65 67 65 72 20 69 73 20  That integer is 
b360: 30 20 74 6f 20 64 69 73 61 62 6c 65 20 70 65 72  0 to disable per
b370: 73 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65  sistent WAL mode
b380: 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20   or 1 to enable 
b390: 70 65 72 73 69 73 74 65 6e 74 0a 2a 2a 20 57 41  persistent.** WA
b3a0: 4c 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20  L mode.  If the 
b3b0: 69 6e 74 65 67 65 72 20 69 73 20 2d 31 2c 20 74  integer is -1, t
b3c0: 68 65 6e 20 69 74 20 69 73 20 6f 76 65 72 77 72  hen it is overwr
b3d0: 69 74 74 65 6e 20 77 69 74 68 20 74 68 65 20 63  itten with the c
b3e0: 75 72 72 65 6e 74 0a 2a 2a 20 57 41 4c 20 70 65  urrent.** WAL pe
b3f0: 72 73 69 73 74 65 6e 63 65 20 73 65 74 74 69 6e  rsistence settin
b400: 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  g..**.** <li>[[S
b410: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45  QLITE_FCNTL_POWE
b420: 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d  RSAFE_OVERWRITE]
b430: 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ].** ^The [SQLIT
b440: 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46  E_FCNTL_POWERSAF
b450: 45 5f 4f 56 45 52 57 52 49 54 45 5d 20 6f 70 63  E_OVERWRITE] opc
b460: 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 73  ode is used to s
b470: 65 74 20 6f 72 20 71 75 65 72 79 20 74 68 65 0a  et or query the.
b480: 2a 2a 20 70 65 72 73 69 73 74 65 6e 74 20 22 70  ** persistent "p
b490: 6f 77 65 72 73 61 66 65 2d 6f 76 65 72 77 72 69  owersafe-overwri
b4a0: 74 65 22 20 6f 72 20 22 50 53 4f 57 22 20 73 65  te" or "PSOW" se
b4b0: 74 74 69 6e 67 2e 20 20 54 68 65 20 50 53 4f 57  tting.  The PSOW
b4c0: 20 73 65 74 74 69 6e 67 0a 2a 2a 20 64 65 74 65   setting.** dete
b4d0: 72 6d 69 6e 65 73 20 74 68 65 20 5b 53 51 4c 49  rmines the [SQLI
b4e0: 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41  TE_IOCAP_POWERSA
b4f0: 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 20 62 69  FE_OVERWRITE] bi
b500: 74 20 6f 66 20 74 68 65 0a 2a 2a 20 78 44 65 76  t of the.** xDev
b510: 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69  iceCharacteristi
b520: 63 73 20 6d 65 74 68 6f 64 73 2e 20 54 68 65 20  cs methods. The 
b530: 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
b540: 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
b550: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20  file_control()] 
b560: 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65 20  for this opcode 
b570: 73 68 6f 75 6c 64 20 62 65 20 61 20 70 6f 69 6e  should be a poin
b580: 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ter to an intege
b590: 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65 67  r..** That integ
b5a0: 65 72 20 69 73 20 30 20 74 6f 20 64 69 73 61 62  er is 0 to disab
b5b0: 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d  le zero-damage m
b5c0: 6f 64 65 20 6f 72 20 31 20 74 6f 20 65 6e 61 62  ode or 1 to enab
b5d0: 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65 0a 2a  le zero-damage.*
b5e0: 2a 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20  * mode.  If the 
b5f0: 69 6e 74 65 67 65 72 20 69 73 20 2d 31 2c 20 74  integer is -1, t
b600: 68 65 6e 20 69 74 20 69 73 20 6f 76 65 72 77 72  hen it is overwr
b610: 69 74 74 65 6e 20 77 69 74 68 20 74 68 65 20 63  itten with the c
b620: 75 72 72 65 6e 74 0a 2a 2a 20 7a 65 72 6f 2d 64  urrent.** zero-d
b630: 61 6d 61 67 65 20 6d 6f 64 65 20 73 65 74 74 69  amage mode setti
b640: 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ng..**.** <li>[[
b650: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45  SQLITE_FCNTL_OVE
b660: 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65  RWRITE]].** ^The
b670: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f   [SQLITE_FCNTL_O
b680: 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 65  VERWRITE] opcode
b690: 20 69 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 53   is invoked by S
b6a0: 51 4c 69 74 65 20 61 66 74 65 72 20 6f 70 65 6e  QLite after open
b6b0: 69 6e 67 0a 2a 2a 20 61 20 77 72 69 74 65 20 74  ing.** a write t
b6c0: 72 61 6e 73 61 63 74 69 6f 6e 20 74 6f 20 69 6e  ransaction to in
b6d0: 64 69 63 61 74 65 20 74 68 61 74 2c 20 75 6e 6c  dicate that, unl
b6e0: 65 73 73 20 69 74 20 69 73 20 72 6f 6c 6c 65 64  ess it is rolled
b6f0: 20 62 61 63 6b 20 66 6f 72 20 73 6f 6d 65 0a 2a   back for some.*
b700: 2a 20 72 65 61 73 6f 6e 2c 20 74 68 65 20 65 6e  * reason, the en
b710: 74 69 72 65 20 64 61 74 61 62 61 73 65 20 66 69  tire database fi
b720: 6c 65 20 77 69 6c 6c 20 62 65 20 6f 76 65 72 77  le will be overw
b730: 72 69 74 74 65 6e 20 62 79 20 74 68 65 20 63 75  ritten by the cu
b740: 72 72 65 6e 74 20 0a 2a 2a 20 74 72 61 6e 73 61  rrent .** transa
b750: 63 74 69 6f 6e 2e 20 54 68 69 73 20 69 73 20 75  ction. This is u
b760: 73 65 64 20 62 79 20 56 41 43 55 55 4d 20 6f 70  sed by VACUUM op
b770: 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20  erations..**.** 
b780: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
b790: 54 4c 5f 56 46 53 4e 41 4d 45 5d 5d 0a 2a 2a 20  TL_VFSNAME]].** 
b7a0: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e  ^The [SQLITE_FCN
b7b0: 54 4c 5f 56 46 53 4e 41 4d 45 5d 20 6f 70 63 6f  TL_VFSNAME] opco
b7c0: 64 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  de can be used t
b7d0: 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6e 61 6d  o obtain the nam
b7e0: 65 73 20 6f 66 0a 2a 2a 20 61 6c 6c 20 5b 56 46  es of.** all [VF
b7f0: 53 65 73 5d 20 69 6e 20 74 68 65 20 56 46 53 20  Ses] in the VFS 
b800: 73 74 61 63 6b 2e 20 20 54 68 65 20 6e 61 6d 65  stack.  The name
b810: 73 20 61 72 65 20 6f 66 20 61 6c 6c 20 56 46 53  s are of all VFS
b820: 20 73 68 69 6d 73 20 61 6e 64 20 74 68 65 0a 2a   shims and the.*
b830: 2a 20 66 69 6e 61 6c 20 62 6f 74 74 6f 6d 2d 6c  * final bottom-l
b840: 65 76 65 6c 20 56 46 53 20 61 72 65 20 77 72 69  evel VFS are wri
b850: 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79  tten into memory
b860: 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a   obtained from .
b870: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ** [sqlite3_mall
b880: 6f 63 28 29 5d 20 61 6e 64 20 74 68 65 20 72 65  oc()] and the re
b890: 73 75 6c 74 20 69 73 20 73 74 6f 72 65 64 20 69  sult is stored i
b8a0: 6e 20 74 68 65 20 63 68 61 72 2a 20 76 61 72 69  n the char* vari
b8b0: 61 62 6c 65 0a 2a 2a 20 74 68 61 74 20 74 68 65  able.** that the
b8c0: 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
b8d0: 72 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 66 69  r of [sqlite3_fi
b8e0: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 70 6f  le_control()] po
b8f0: 69 6e 74 73 20 74 6f 2e 0a 2a 2a 20 54 68 65 20  ints to..** The 
b900: 63 61 6c 6c 65 72 20 69 73 20 72 65 73 70 6f 6e  caller is respon
b910: 73 69 62 6c 65 20 66 6f 72 20 66 72 65 65 69 6e  sible for freein
b920: 67 20 74 68 65 20 6d 65 6d 6f 72 79 20 77 68 65  g the memory whe
b930: 6e 20 64 6f 6e 65 2e 20 20 41 73 20 77 69 74 68  n done.  As with
b940: 0a 2a 2a 20 61 6c 6c 20 66 69 6c 65 2d 63 6f 6e  .** all file-con
b950: 74 72 6f 6c 20 61 63 74 69 6f 6e 73 2c 20 74 68  trol actions, th
b960: 65 72 65 20 69 73 20 6e 6f 20 67 75 61 72 61 6e  ere is no guaran
b970: 74 65 65 20 74 68 61 74 20 74 68 69 73 20 77 69  tee that this wi
b980: 6c 6c 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 64  ll actually.** d
b990: 6f 20 61 6e 79 74 68 69 6e 67 2e 20 20 43 61 6c  o anything.  Cal
b9a0: 6c 65 72 73 20 73 68 6f 75 6c 64 20 69 6e 69 74  lers should init
b9b0: 69 61 6c 69 7a 65 20 74 68 65 20 63 68 61 72 2a  ialize the char*
b9c0: 20 76 61 72 69 61 62 6c 65 20 74 6f 20 61 20 4e   variable to a N
b9d0: 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69  ULL.** pointer i
b9e0: 6e 20 63 61 73 65 20 74 68 69 73 20 66 69 6c 65  n case this file
b9f0: 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 6e 6f 74 20  -control is not 
ba00: 69 6d 70 6c 65 6d 65 6e 74 65 64 2e 20 20 54 68  implemented.  Th
ba10: 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a  is file-control.
ba20: 2a 2a 20 69 73 20 69 6e 74 65 6e 64 65 64 20 66  ** is intended f
ba30: 6f 72 20 64 69 61 67 6e 6f 73 74 69 63 20 75 73  or diagnostic us
ba40: 65 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  e only..**.** <l
ba50: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
ba60: 5f 50 52 41 47 4d 41 5d 5d 0a 2a 2a 20 5e 57 68  _PRAGMA]].** ^Wh
ba70: 65 6e 65 76 65 72 20 61 20 5b 50 52 41 47 4d 41  enever a [PRAGMA
ba80: 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 70  ] statement is p
ba90: 61 72 73 65 64 2c 20 61 6e 20 5b 53 51 4c 49 54  arsed, an [SQLIT
baa0: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20  E_FCNTL_PRAGMA] 
bab0: 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  .** file control
bac0: 20 69 73 20 73 65 6e 74 20 74 6f 20 74 68 65 20   is sent to the 
bad0: 6f 70 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69  open [sqlite3_fi
bae0: 6c 65 5d 20 6f 62 6a 65 63 74 20 63 6f 72 72 65  le] object corre
baf0: 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 74 6f 20 74  sponding.** to t
bb00: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
bb10: 20 74 6f 20 77 68 69 63 68 20 74 68 65 20 70 72   to which the pr
bb20: 61 67 6d 61 20 73 74 61 74 65 6d 65 6e 74 20 72  agma statement r
bb30: 65 66 65 72 73 2e 20 5e 54 68 65 20 61 72 67 75  efers. ^The argu
bb40: 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b  ment.** to the [
bb50: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
bb60: 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f  GMA] file contro
bb70: 6c 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66  l is an array of
bb80: 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20  .** pointers to 
bb90: 73 74 72 69 6e 67 73 20 28 63 68 61 72 2a 2a 29  strings (char**)
bba0: 20 69 6e 20 77 68 69 63 68 20 74 68 65 20 73 65   in which the se
bbb0: 63 6f 6e 64 20 65 6c 65 6d 65 6e 74 20 6f 66 20  cond element of 
bbc0: 74 68 65 20 61 72 72 61 79 0a 2a 2a 20 69 73 20  the array.** is 
bbd0: 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
bbe0: 70 72 61 67 6d 61 20 61 6e 64 20 74 68 65 20 74  pragma and the t
bbf0: 68 69 72 64 20 65 6c 65 6d 65 6e 74 20 69 73 20  hird element is 
bc00: 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  the argument to 
bc10: 74 68 65 0a 2a 2a 20 70 72 61 67 6d 61 20 6f 72  the.** pragma or
bc20: 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 70 72 61   NULL if the pra
bc30: 67 6d 61 20 68 61 73 20 6e 6f 20 61 72 67 75 6d  gma has no argum
bc40: 65 6e 74 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c  ent.  ^The handl
bc50: 65 72 20 66 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51  er for an.** [SQ
bc60: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
bc70: 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  A] file control 
bc80: 63 61 6e 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 6d  can optionally m
bc90: 61 6b 65 20 74 68 65 20 66 69 72 73 74 20 65 6c  ake the first el
bca0: 65 6d 65 6e 74 0a 2a 2a 20 6f 66 20 74 68 65 20  ement.** of the 
bcb0: 63 68 61 72 2a 2a 20 61 72 67 75 6d 65 6e 74 20  char** argument 
bcc0: 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e  point to a strin
bcd0: 67 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  g obtained from 
bce0: 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66  [sqlite3_mprintf
bcf0: 28 29 5d 0a 2a 2a 20 6f 72 20 74 68 65 20 65 71  ()].** or the eq
bd00: 75 69 76 61 6c 65 6e 74 20 61 6e 64 20 74 68 61  uivalent and tha
bd10: 74 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65  t string will be
bd20: 63 6f 6d 65 20 74 68 65 20 72 65 73 75 6c 74 20  come the result 
bd30: 6f 66 20 74 68 65 20 70 72 61 67 6d 61 20 6f 72  of the pragma or
bd40: 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 6d 65  .** the error me
bd50: 73 73 61 67 65 20 69 66 20 74 68 65 20 70 72 61  ssage if the pra
bd60: 67 6d 61 20 66 61 69 6c 73 2e 20 5e 49 66 20 74  gma fails. ^If t
bd70: 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43  he.** [SQLITE_FC
bd80: 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65  NTL_PRAGMA] file
bd90: 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73   control returns
bda0: 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e   [SQLITE_NOTFOUN
bdb0: 44 5d 2c 20 74 68 65 6e 20 6e 6f 72 6d 61 6c 20  D], then normal 
bdc0: 0a 2a 2a 20 5b 50 52 41 47 4d 41 5d 20 70 72 6f  .** [PRAGMA] pro
bdd0: 63 65 73 73 69 6e 67 20 63 6f 6e 74 69 6e 75 65  cessing continue
bde0: 73 2e 20 20 5e 49 66 20 74 68 65 20 5b 53 51 4c  s.  ^If the [SQL
bdf0: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
be00: 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f  ].** file contro
be10: 6c 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  l returns [SQLIT
be20: 45 5f 4f 4b 5d 2c 20 74 68 65 6e 20 74 68 65 20  E_OK], then the 
be30: 70 61 72 73 65 72 20 61 73 73 75 6d 65 73 20 74  parser assumes t
be40: 68 61 74 20 74 68 65 0a 2a 2a 20 56 46 53 20 68  hat the.** VFS h
be50: 61 73 20 68 61 6e 64 6c 65 64 20 74 68 65 20 50  as handled the P
be60: 52 41 47 4d 41 20 69 74 73 65 6c 66 20 61 6e 64  RAGMA itself and
be70: 20 74 68 65 20 70 61 72 73 65 72 20 67 65 6e 65   the parser gene
be80: 72 61 74 65 73 20 61 20 6e 6f 2d 6f 70 0a 2a 2a  rates a no-op.**
be90: 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
bea0: 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 20 5b 53  ent.  ^If the [S
beb0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47  QLITE_FCNTL_PRAG
bec0: 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  MA] file control
bed0: 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20   returns.** any 
bee0: 72 65 73 75 6c 74 20 63 6f 64 65 20 6f 74 68 65  result code othe
bef0: 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f  r than [SQLITE_O
bf00: 4b 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 4f  K] or [SQLITE_NO
bf10: 54 46 4f 55 4e 44 5d 2c 20 74 68 61 74 20 6d 65  TFOUND], that me
bf20: 61 6e 73 0a 2a 2a 20 74 68 61 74 20 74 68 65 20  ans.** that the 
bf30: 56 46 53 20 65 6e 63 6f 75 6e 74 65 72 65 64 20  VFS encountered 
bf40: 61 6e 20 65 72 72 6f 72 20 77 68 69 6c 65 20 68  an error while h
bf50: 61 6e 64 6c 69 6e 67 20 74 68 65 20 5b 50 52 41  andling the [PRA
bf60: 47 4d 41 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20  GMA] and the.** 
bf70: 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 6f 66 20 74  compilation of t
bf80: 68 65 20 50 52 41 47 4d 41 20 66 61 69 6c 73 20  he PRAGMA fails 
bf90: 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20  with an error.  
bfa0: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e  ^The [SQLITE_FCN
bfb0: 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69  TL_PRAGMA].** fi
bfc0: 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 63 63 75 72  le control occur
bfd0: 73 20 61 74 20 74 68 65 20 62 65 67 69 6e 6e 69  s at the beginni
bfe0: 6e 67 20 6f 66 20 70 72 61 67 6d 61 20 73 74 61  ng of pragma sta
bff0: 74 65 6d 65 6e 74 20 61 6e 61 6c 79 73 69 73 20  tement analysis 
c000: 61 6e 64 20 73 6f 0a 2a 2a 20 69 74 20 69 73 20  and so.** it is 
c010: 61 62 6c 65 20 74 6f 20 6f 76 65 72 72 69 64 65  able to override
c020: 20 62 75 69 6c 74 2d 69 6e 20 5b 50 52 41 47 4d   built-in [PRAGM
c030: 41 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  A] statements..*
c040: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
c050: 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44  E_FCNTL_BUSYHAND
c060: 4c 45 52 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  LER]].** ^The [S
c070: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59  QLITE_FCNTL_BUSY
c080: 48 41 4e 44 4c 45 52 5d 0a 2a 2a 20 66 69 6c 65  HANDLER].** file
c090: 2d 63 6f 6e 74 72 6f 6c 20 6d 61 79 20 62 65 20  -control may be 
c0a0: 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c 69 74  invoked by SQLit
c0b0: 65 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73  e on the databas
c0c0: 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 0a 2a 2a  e file handle.**
c0d0: 20 73 68 6f 72 74 6c 79 20 61 66 74 65 72 20 69   shortly after i
c0e0: 74 20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 6f  t is opened in o
c0f0: 72 64 65 72 20 74 6f 20 70 72 6f 76 69 64 65 20  rder to provide 
c100: 61 20 63 75 73 74 6f 6d 20 56 46 53 20 77 69 74  a custom VFS wit
c110: 68 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 74  h access.** to t
c120: 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 62  he connections b
c130: 75 73 79 2d 68 61 6e 64 6c 65 72 20 63 61 6c 6c  usy-handler call
c140: 62 61 63 6b 2e 20 54 68 65 20 61 72 67 75 6d 65  back. The argume
c150: 6e 74 20 69 73 20 6f 66 20 74 79 70 65 20 28 76  nt is of type (v
c160: 6f 69 64 20 2a 2a 29 0a 2a 2a 20 2d 20 61 6e 20  oid **).** - an 
c170: 61 72 72 61 79 20 6f 66 20 74 77 6f 20 28 76 6f  array of two (vo
c180: 69 64 20 2a 29 20 76 61 6c 75 65 73 2e 20 54 68  id *) values. Th
c190: 65 20 66 69 72 73 74 20 28 76 6f 69 64 20 2a 29  e first (void *)
c1a0: 20 61 63 74 75 61 6c 6c 79 20 70 6f 69 6e 74 73   actually points
c1b0: 0a 2a 2a 20 74 6f 20 61 20 66 75 6e 63 74 69 6f  .** to a functio
c1c0: 6e 20 6f 66 20 74 79 70 65 20 28 69 6e 74 20 28  n of type (int (
c1d0: 2a 29 28 76 6f 69 64 20 2a 29 29 2e 20 49 6e 20  *)(void *)). In 
c1e0: 6f 72 64 65 72 20 74 6f 20 69 6e 76 6f 6b 65 20  order to invoke 
c1f0: 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a  the connections.
c200: 2a 2a 20 62 75 73 79 2d 68 61 6e 64 6c 65 72 2c  ** busy-handler,
c210: 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 73   this function s
c220: 68 6f 75 6c 64 20 62 65 20 69 6e 76 6f 6b 65 64  hould be invoked
c230: 20 77 69 74 68 20 74 68 65 20 73 65 63 6f 6e 64   with the second
c240: 20 28 76 6f 69 64 20 2a 29 20 69 6e 0a 2a 2a 20   (void *) in.** 
c250: 74 68 65 20 61 72 72 61 79 20 61 73 20 74 68 65  the array as the
c260: 20 6f 6e 6c 79 20 61 72 67 75 6d 65 6e 74 2e 20   only argument. 
c270: 49 66 20 69 74 20 72 65 74 75 72 6e 73 20 6e 6f  If it returns no
c280: 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65  n-zero, then the
c290: 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 73 68   operation.** sh
c2a0: 6f 75 6c 64 20 62 65 20 72 65 74 72 69 65 64 2e  ould be retried.
c2b0: 20 49 66 20 69 74 20 72 65 74 75 72 6e 73 20 7a   If it returns z
c2c0: 65 72 6f 2c 20 74 68 65 20 63 75 73 74 6f 6d 20  ero, the custom 
c2d0: 56 46 53 20 73 68 6f 75 6c 64 20 61 62 61 6e 64  VFS should aband
c2e0: 6f 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e  on the.** curren
c2f0: 74 20 6f 70 65 72 61 74 69 6f 6e 2e 0a 2a 2a 0a  t operation..**.
c300: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
c310: 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41  FCNTL_TEMPFILENA
c320: 4d 45 5d 5d 0a 2a 2a 20 5e 41 70 70 6c 69 63 61  ME]].** ^Applica
c330: 74 69 6f 6e 20 63 61 6e 20 69 6e 76 6f 6b 65 20  tion can invoke 
c340: 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  the [SQLITE_FCNT
c350: 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 20  L_TEMPFILENAME] 
c360: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20  file-control.** 
c370: 74 6f 20 68 61 76 65 20 53 51 4c 69 74 65 20 67  to have SQLite g
c380: 65 6e 65 72 61 74 65 20 61 0a 2a 2a 20 74 65 6d  enerate a.** tem
c390: 70 6f 72 61 72 79 20 66 69 6c 65 6e 61 6d 65 20  porary filename 
c3a0: 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65 20 61  using the same a
c3b0: 6c 67 6f 72 69 74 68 6d 20 74 68 61 74 20 69 73  lgorithm that is
c3c0: 20 66 6f 6c 6c 6f 77 65 64 20 74 6f 20 67 65 6e   followed to gen
c3d0: 65 72 61 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61  erate.** tempora
c3e0: 72 79 20 66 69 6c 65 6e 61 6d 65 73 20 66 6f 72  ry filenames for
c3f0: 20 54 45 4d 50 20 74 61 62 6c 65 73 20 61 6e 64   TEMP tables and
c400: 20 6f 74 68 65 72 20 69 6e 74 65 72 6e 61 6c 20   other internal 
c410: 75 73 65 73 2e 20 20 54 68 65 0a 2a 2a 20 61 72  uses.  The.** ar
c420: 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65  gument should be
c430: 20 61 20 63 68 61 72 2a 2a 20 77 68 69 63 68 20   a char** which 
c440: 77 69 6c 6c 20 62 65 20 66 69 6c 6c 65 64 20 77  will be filled w
c450: 69 74 68 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  ith the filename
c460: 0a 2a 2a 20 77 72 69 74 74 65 6e 20 69 6e 74 6f  .** written into
c470: 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64   memory obtained
c480: 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
c490: 61 6c 6c 6f 63 28 29 5d 2e 20 20 54 68 65 20 63  alloc()].  The c
c4a0: 61 6c 6c 65 72 20 73 68 6f 75 6c 64 0a 2a 2a 20  aller should.** 
c4b0: 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f  invoke [sqlite3_
c4c0: 66 72 65 65 28 29 5d 20 6f 6e 20 74 68 65 20 72  free()] on the r
c4d0: 65 73 75 6c 74 20 74 6f 20 61 76 6f 69 64 20 61  esult to avoid a
c4e0: 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 2e 0a 2a 2a   memory leak..**
c4f0: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
c500: 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45  _FCNTL_MMAP_SIZE
c510: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
c520: 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a  E_FCNTL_MMAP_SIZ
c530: 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  E] file control 
c540: 69 73 20 75 73 65 64 20 74 6f 20 71 75 65 72 79  is used to query
c550: 20 6f 72 20 73 65 74 20 74 68 65 0a 2a 2a 20 6d   or set the.** m
c560: 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
c570: 20 62 79 74 65 73 20 74 68 61 74 20 77 69 6c 6c   bytes that will
c580: 20 62 65 20 75 73 65 64 20 66 6f 72 20 6d 65 6d   be used for mem
c590: 6f 72 79 2d 6d 61 70 70 65 64 20 49 2f 4f 2e 0a  ory-mapped I/O..
c5a0: 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20  ** The argument 
c5b0: 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
c5c0: 61 20 76 61 6c 75 65 20 6f 66 20 74 79 70 65 20  a value of type 
c5d0: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 74 68  sqlite3_int64 th
c5e0: 61 74 0a 2a 2a 20 69 73 20 61 6e 20 61 64 76 69  at.** is an advi
c5f0: 73 6f 72 79 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  sory maximum num
c600: 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
c610: 74 68 65 20 66 69 6c 65 20 74 6f 20 6d 65 6d 6f  the file to memo
c620: 72 79 20 6d 61 70 2e 20 20 54 68 65 0a 2a 2a 20  ry map.  The.** 
c630: 70 6f 69 6e 74 65 72 20 69 73 20 6f 76 65 72 77  pointer is overw
c640: 72 69 74 74 65 6e 20 77 69 74 68 20 74 68 65 20  ritten with the 
c650: 6f 6c 64 20 76 61 6c 75 65 2e 20 20 54 68 65 20  old value.  The 
c660: 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20 63 68 61  limit is not cha
c670: 6e 67 65 64 20 69 66 0a 2a 2a 20 74 68 65 20 76  nged if.** the v
c680: 61 6c 75 65 20 6f 72 69 67 69 6e 61 6c 6c 79 20  alue originally 
c690: 70 6f 69 6e 74 65 64 20 74 6f 20 69 73 20 6e 65  pointed to is ne
c6a0: 67 61 74 69 76 65 2c 20 61 6e 64 20 73 6f 20 74  gative, and so t
c6b0: 68 65 20 63 75 72 72 65 6e 74 20 6c 69 6d 69 74  he current limit
c6c0: 20 0a 2a 2a 20 63 61 6e 20 62 65 20 71 75 65 72   .** can be quer
c6d0: 69 65 64 20 62 79 20 70 61 73 73 69 6e 67 20 69  ied by passing i
c6e0: 6e 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  n a pointer to a
c6f0: 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62 65 72   negative number
c700: 2e 20 20 54 68 69 73 0a 2a 2a 20 66 69 6c 65 2d  .  This.** file-
c710: 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65 64 20  control is used 
c720: 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 69 6d  internally to im
c730: 70 6c 65 6d 65 6e 74 20 5b 50 52 41 47 4d 41 20  plement [PRAGMA 
c740: 6d 6d 61 70 5f 73 69 7a 65 5d 2e 0a 2a 2a 0a 2a  mmap_size]..**.*
c750: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
c760: 43 4e 54 4c 5f 54 52 41 43 45 5d 5d 0a 2a 2a 20  CNTL_TRACE]].** 
c770: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
c780: 4c 5f 54 52 41 43 45 5d 20 66 69 6c 65 20 63 6f  L_TRACE] file co
c790: 6e 74 72 6f 6c 20 70 72 6f 76 69 64 65 73 20 61  ntrol provides a
c7a0: 64 76 69 73 6f 72 79 20 69 6e 66 6f 72 6d 61 74  dvisory informat
c7b0: 69 6f 6e 0a 2a 2a 20 74 6f 20 74 68 65 20 56 46  ion.** to the VF
c7c0: 53 20 61 62 6f 75 74 20 77 68 61 74 20 74 68 65  S about what the
c7d0: 20 68 69 67 68 65 72 20 6c 61 79 65 72 73 20 6f   higher layers o
c7e0: 66 20 74 68 65 20 53 51 4c 69 74 65 20 73 74 61  f the SQLite sta
c7f0: 63 6b 20 61 72 65 20 64 6f 69 6e 67 2e 0a 2a 2a  ck are doing..**
c800: 20 54 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 72   This file contr
c810: 6f 6c 20 69 73 20 75 73 65 64 20 62 79 20 73 6f  ol is used by so
c820: 6d 65 20 56 46 53 20 61 63 74 69 76 69 74 79 20  me VFS activity 
c830: 74 72 61 63 69 6e 67 20 5b 73 68 69 6d 73 5d 2e  tracing [shims].
c840: 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74  .** The argument
c850: 20 69 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   is a zero-termi
c860: 6e 61 74 65 64 20 73 74 72 69 6e 67 2e 20 20 48  nated string.  H
c870: 69 67 68 65 72 20 6c 61 79 65 72 73 20 69 6e 20  igher layers in 
c880: 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 73 74  the.** SQLite st
c890: 61 63 6b 20 6d 61 79 20 67 65 6e 65 72 61 74 65  ack may generate
c8a0: 20 69 6e 73 74 61 6e 63 65 73 20 6f 66 20 74 68   instances of th
c8b0: 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  is file control 
c8c0: 69 66 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54  if.** the [SQLIT
c8d0: 45 5f 55 53 45 5f 46 43 4e 54 4c 5f 54 52 41 43  E_USE_FCNTL_TRAC
c8e0: 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  E] compile-time 
c8f0: 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65  option is enable
c900: 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  d..**.** <li>[[S
c910: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f  QLITE_FCNTL_HAS_
c920: 4d 4f 56 45 44 5d 5d 0a 2a 2a 20 54 68 65 20 5b  MOVED]].** The [
c930: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53  SQLITE_FCNTL_HAS
c940: 5f 4d 4f 56 45 44 5d 20 66 69 6c 65 20 63 6f 6e  _MOVED] file con
c950: 74 72 6f 6c 20 69 6e 74 65 72 70 72 65 74 73 20  trol interprets 
c960: 69 74 73 20 61 72 67 75 6d 65 6e 74 20 61 73 20  its argument as 
c970: 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20  a.** pointer to 
c980: 61 6e 20 69 6e 74 65 67 65 72 20 61 6e 64 20 69  an integer and i
c990: 74 20 77 72 69 74 65 73 20 61 20 62 6f 6f 6c 65  t writes a boole
c9a0: 61 6e 20 69 6e 74 6f 20 74 68 61 74 20 69 6e 74  an into that int
c9b0: 65 67 65 72 20 64 65 70 65 6e 64 69 6e 67 0a 2a  eger depending.*
c9c0: 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 6f 72 20  * on whether or 
c9d0: 6e 6f 74 20 74 68 65 20 66 69 6c 65 20 68 61 73  not the file has
c9e0: 20 62 65 65 6e 20 72 65 6e 61 6d 65 64 2c 20 6d   been renamed, m
c9f0: 6f 76 65 64 2c 20 6f 72 20 64 65 6c 65 74 65 64  oved, or deleted
ca00: 20 73 69 6e 63 65 20 69 74 0a 2a 2a 20 77 61 73   since it.** was
ca10: 20 66 69 72 73 74 20 6f 70 65 6e 65 64 2e 0a 2a   first opened..*
ca20: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
ca30: 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45  E_FCNTL_WIN32_SE
ca40: 54 5f 48 41 4e 44 4c 45 5d 5d 0a 2a 2a 20 54 68  T_HANDLE]].** Th
ca50: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
ca60: 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45  WIN32_SET_HANDLE
ca70: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
ca80: 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20   for debugging. 
ca90: 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20   This.** opcode 
caa0: 63 61 75 73 65 73 20 74 68 65 20 78 46 69 6c 65  causes the xFile
cab0: 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74  Control method t
cac0: 6f 20 73 77 61 70 20 74 68 65 20 66 69 6c 65 20  o swap the file 
cad0: 68 61 6e 64 6c 65 20 77 69 74 68 20 74 68 65 20  handle with the 
cae0: 6f 6e 65 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74  one.** pointed t
caf0: 6f 20 62 79 20 74 68 65 20 70 41 72 67 20 61 72  o by the pArg ar
cb00: 67 75 6d 65 6e 74 2e 20 20 54 68 69 73 20 63 61  gument.  This ca
cb10: 70 61 62 69 6c 69 74 79 20 69 73 20 75 73 65 64  pability is used
cb20: 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 0a   during testing.
cb30: 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64  ** and only need
cb40: 73 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65  s to be supporte
cb50: 64 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 54 45  d when SQLITE_TE
cb60: 53 54 20 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a  ST is defined..*
cb70: 2a 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 23 64  *.** </ul>.*/.#d
cb80: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
cb90: 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20 20  TL_LOCKSTATE    
cba0: 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65             1.#de
cbb0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 47 45 54 5f  fine SQLITE_GET_
cbc0: 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20  LOCKPROXYFILE   
cbd0: 20 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66            2.#def
cbe0: 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 54 5f 4c  ine SQLITE_SET_L
cbf0: 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20  OCKPROXYFILE    
cc00: 20 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69           3.#defi
cc10: 6e 65 20 53 51 4c 49 54 45 5f 4c 41 53 54 5f 45  ne SQLITE_LAST_E
cc20: 52 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20 20  RRNO            
cc30: 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e          4.#defin
cc40: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53  e SQLITE_FCNTL_S
cc50: 49 5a 45 5f 48 49 4e 54 20 20 20 20 20 20 20 20  IZE_HINT        
cc60: 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65         5.#define
cc70: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48   SQLITE_FCNTL_CH
cc80: 55 4e 4b 5f 53 49 5a 45 20 20 20 20 20 20 20 20  UNK_SIZE        
cc90: 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20        6.#define 
cca0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c  SQLITE_FCNTL_FIL
ccb0: 45 5f 50 4f 49 4e 54 45 52 20 20 20 20 20 20 20  E_POINTER       
ccc0: 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53       7.#define S
ccd0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43  QLITE_FCNTL_SYNC
cce0: 5f 4f 4d 49 54 54 45 44 20 20 20 20 20 20 20 20  _OMITTED        
ccf0: 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51      8.#define SQ
cd00: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32  LITE_FCNTL_WIN32
cd10: 5f 41 56 5f 52 45 54 52 59 20 20 20 20 20 20 20  _AV_RETRY       
cd20: 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c     9.#define SQL
cd30: 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53  ITE_FCNTL_PERSIS
cd40: 54 5f 57 41 4c 20 20 20 20 20 20 20 20 20 20 20  T_WAL           
cd50: 20 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   10.#define SQLI
cd60: 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49  TE_FCNTL_OVERWRI
cd70: 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TE              
cd80: 31 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  11.#define SQLIT
cd90: 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 20  E_FCNTL_VFSNAME 
cda0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
cdb0: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
cdc0: 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45  _FCNTL_POWERSAFE
cdd0: 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20 31 33  _OVERWRITE    13
cde0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
cdf0: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 20 20 20 20  FCNTL_PRAGMA    
ce00: 20 20 20 20 20 20 20 20 20 20 20 20 20 31 34 0a               14.
ce10: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
ce20: 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52  CNTL_BUSYHANDLER
ce30: 20 20 20 20 20 20 20 20 20 20 20 20 31 35 0a 23              15.#
ce40: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
ce50: 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45  NTL_TEMPFILENAME
ce60: 20 20 20 20 20 20 20 20 20 20 20 31 36 0a 23 64             16.#d
ce70: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
ce80: 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 20 20 20 20  TL_MMAP_SIZE    
ce90: 20 20 20 20 20 20 20 20 20 20 31 38 0a 23 64 65            18.#de
cea0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
ceb0: 4c 5f 54 52 41 43 45 20 20 20 20 20 20 20 20 20  L_TRACE         
cec0: 20 20 20 20 20 20 20 20 20 31 39 0a 23 64 65 66           19.#def
ced0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
cee0: 5f 48 41 53 5f 4d 4f 56 45 44 20 20 20 20 20 20  _HAS_MOVED      
cef0: 20 20 20 20 20 20 20 20 32 30 0a 23 64 65 66 69          20.#defi
cf00: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
cf10: 53 59 4e 43 20 20 20 20 20 20 20 20 20 20 20 20  SYNC            
cf20: 20 20 20 20 20 20 20 32 31 0a 23 64 65 66 69 6e         21.#defin
cf30: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43  e SQLITE_FCNTL_C
cf40: 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f 20 20  OMMIT_PHASETWO  
cf50: 20 20 20 20 20 20 32 32 0a 23 64 65 66 69 6e 65        22.#define
cf60: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49   SQLITE_FCNTL_WI
cf70: 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45 20 20  N32_SET_HANDLE  
cf80: 20 20 20 20 20 32 33 0a 0a 2f 2a 0a 2a 2a 20 43       23../*.** C
cf90: 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20 48  API3REF: Mutex H
cfa0: 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20  andle.**.** The 
cfb0: 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20 77 69 74  mutex module wit
cfc0: 68 69 6e 20 53 51 4c 69 74 65 20 64 65 66 69 6e  hin SQLite defin
cfd0: 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  es [sqlite3_mute
cfe0: 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20 61  x] to be an.** a
cff0: 62 73 74 72 61 63 74 20 74 79 70 65 20 66 6f 72  bstract type for
d000: 20 61 20 6d 75 74 65 78 20 6f 62 6a 65 63 74 2e   a mutex object.
d010: 20 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72    The SQLite cor
d020: 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a  e never looks.**
d030: 20 61 74 20 74 68 65 20 69 6e 74 65 72 6e 61 6c   at the internal
d040: 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20   representation 
d050: 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 6d  of an [sqlite3_m
d060: 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a  utex].  It only.
d070: 2a 2a 20 64 65 61 6c 73 20 77 69 74 68 20 70 6f  ** deals with po
d080: 69 6e 74 65 72 73 20 74 6f 20 74 68 65 20 5b 73  inters to the [s
d090: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f 62  qlite3_mutex] ob
d0a0: 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65  ject..**.** Mute
d0b0: 78 65 73 20 61 72 65 20 63 72 65 61 74 65 64 20  xes are created 
d0c0: 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d  using [sqlite3_m
d0d0: 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a  utex_alloc()]..*
d0e0: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
d0f0: 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 73   sqlite3_mutex s
d100: 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f  qlite3_mutex;../
d110: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
d120: 53 20 49 6e 74 65 72 66 61 63 65 20 4f 62 6a 65  S Interface Obje
d130: 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74  ct.**.** An inst
d140: 61 6e 63 65 20 6f 66 20 74 68 65 20 73 71 6c 69  ance of the sqli
d150: 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 64  te3_vfs object d
d160: 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72  efines the inter
d170: 66 61 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a 20  face between.** 
d180: 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20  the SQLite core 
d190: 61 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69  and the underlyi
d1a0: 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  ng operating sys
d1b0: 74 65 6d 2e 20 20 54 68 65 20 22 76 66 73 22 0a  tem.  The "vfs".
d1c0: 2a 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 6f  ** in the name o
d1d0: 66 20 74 68 65 20 6f 62 6a 65 63 74 20 73 74 61  f the object sta
d1e0: 6e 64 73 20 66 6f 72 20 22 76 69 72 74 75 61 6c  nds for "virtual
d1f0: 20 66 69 6c 65 20 73 79 73 74 65 6d 22 2e 20 20   file system".  
d200: 53 65 65 0a 2a 2a 20 74 68 65 20 5b 56 46 53 20  See.** the [VFS 
d210: 7c 20 56 46 53 20 64 6f 63 75 6d 65 6e 74 61 74  | VFS documentat
d220: 69 6f 6e 5d 20 66 6f 72 20 66 75 72 74 68 65 72  ion] for further
d230: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a   information..**
d240: 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 6f 66  .** The value of
d250: 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69   the iVersion fi
d260: 65 6c 64 20 69 73 20 69 6e 69 74 69 61 6c 6c 79  eld is initially
d270: 20 31 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61   1 but may be la
d280: 72 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74 75 72  rger in.** futur
d290: 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
d2a0: 4c 69 74 65 2e 20 20 41 64 64 69 74 69 6f 6e 61  Lite.  Additiona
d2b0: 6c 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20  l fields may be 
d2c0: 61 70 70 65 6e 64 65 64 20 74 6f 20 74 68 69 73  appended to this
d2d0: 0a 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65 6e 20  .** object when 
d2e0: 74 68 65 20 69 56 65 72 73 69 6f 6e 20 76 61 6c  the iVersion val
d2f0: 75 65 20 69 73 20 69 6e 63 72 65 61 73 65 64 2e  ue is increased.
d300: 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20    Note that the 
d310: 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f 66 20  structure.** of 
d320: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20  the sqlite3_vfs 
d330: 6f 62 6a 65 63 74 20 63 68 61 6e 67 65 73 20 69  object changes i
d340: 6e 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f  n the transactio
d350: 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53 51 4c  n between.** SQL
d360: 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e  ite version 3.5.
d370: 39 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e 64 20  9 and 3.6.0 and 
d380: 79 65 74 20 74 68 65 20 69 56 65 72 73 69 6f 6e  yet the iVersion
d390: 20 66 69 65 6c 64 20 77 61 73 20 6e 6f 74 0a 2a   field was not.*
d3a0: 2a 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a  * modified..**.*
d3b0: 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c 65 20 66  * The szOsFile f
d3c0: 69 65 6c 64 20 69 73 20 74 68 65 20 73 69 7a 65  ield is the size
d3d0: 20 6f 66 20 74 68 65 20 73 75 62 63 6c 61 73 73   of the subclass
d3e0: 65 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ed [sqlite3_file
d3f0: 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 75  ].** structure u
d400: 73 65 64 20 62 79 20 74 68 69 73 20 56 46 53 2e  sed by this VFS.
d410: 20 20 6d 78 50 61 74 68 6e 61 6d 65 20 69 73 20    mxPathname is 
d420: 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67  the maximum leng
d430: 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68 6e  th of.** a pathn
d440: 61 6d 65 20 69 6e 20 74 68 69 73 20 56 46 53 2e  ame in this VFS.
d450: 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 65  .**.** Registere
d460: 64 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62  d sqlite3_vfs ob
d470: 6a 65 63 74 73 20 61 72 65 20 6b 65 70 74 20 6f  jects are kept o
d480: 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74 20  n a linked list 
d490: 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68 65  formed by.** the
d4a0: 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 20   pNext pointer. 
d4b0: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   The [sqlite3_vf
d4c0: 73 5f 72 65 67 69 73 74 65 72 28 29 5d 0a 2a 2a  s_register()].**
d4d0: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76 66   and [sqlite3_vf
d4e0: 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29 5d 20  s_unregister()] 
d4f0: 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6e 61 67  interfaces manag
d500: 65 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20 69  e this list.** i
d510: 6e 20 61 20 74 68 72 65 61 64 2d 73 61 66 65 20  n a thread-safe 
d520: 77 61 79 2e 20 20 54 68 65 20 5b 73 71 6c 69 74  way.  The [sqlit
d530: 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20 69  e3_vfs_find()] i
d540: 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 65 61 72  nterface.** sear
d550: 63 68 65 73 20 74 68 65 20 6c 69 73 74 2e 20 20  ches the list.  
d560: 4e 65 69 74 68 65 72 20 74 68 65 20 61 70 70 6c  Neither the appl
d570: 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f 72  ication code nor
d580: 20 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70 6c   the VFS.** impl
d590: 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c  ementation shoul
d5a0: 64 20 75 73 65 20 74 68 65 20 70 4e 65 78 74 20  d use the pNext 
d5b0: 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54  pointer..**.** T
d5c0: 68 65 20 70 4e 65 78 74 20 66 69 65 6c 64 20 69  he pNext field i
d5d0: 73 20 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c 64  s the only field
d5e0: 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f   in the sqlite3_
d5f0: 76 66 73 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  vfs.** structure
d600: 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c   that SQLite wil
d610: 6c 20 65 76 65 72 20 6d 6f 64 69 66 79 2e 20 20  l ever modify.  
d620: 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79  SQLite will only
d630: 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f   access.** or mo
d640: 64 69 66 79 20 74 68 69 73 20 66 69 65 6c 64 20  dify this field 
d650: 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61 20  while holding a 
d660: 70 61 72 74 69 63 75 6c 61 72 20 73 74 61 74 69  particular stati
d670: 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65 20  c mutex..** The 
d680: 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
d690: 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69 66 79 20  ld never modify 
d6a0: 61 6e 79 74 68 69 6e 67 20 77 69 74 68 69 6e 20  anything within 
d6b0: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a  the sqlite3_vfs.
d6c0: 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20 74  ** object once t
d6d0: 68 65 20 6f 62 6a 65 63 74 20 68 61 73 20 62 65  he object has be
d6e0: 65 6e 20 72 65 67 69 73 74 65 72 65 64 2e 0a 2a  en registered..*
d6f0: 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20 66  *.** The zName f
d700: 69 65 6c 64 20 68 6f 6c 64 73 20 74 68 65 20 6e  ield holds the n
d710: 61 6d 65 20 6f 66 20 74 68 65 20 56 46 53 20 6d  ame of the VFS m
d720: 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d 65  odule.  The name
d730: 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69 71   must.** be uniq
d740: 75 65 20 61 63 72 6f 73 73 20 61 6c 6c 20 56 46  ue across all VF
d750: 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a  S modules..**.**
d760: 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78   [[sqlite3_vfs.x
d770: 4f 70 65 6e 5d 5d 0a 2a 2a 20 5e 53 51 4c 69 74  Open]].** ^SQLit
d780: 65 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61  e guarantees tha
d790: 74 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20  t the zFilename 
d7a0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70  parameter to xOp
d7b0: 65 6e 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20  en.** is either 
d7c0: 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f  a NULL pointer o
d7d0: 72 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65  r string obtaine
d7e0: 64 0a 2a 2a 20 66 72 6f 6d 20 78 46 75 6c 6c 50  d.** from xFullP
d7f0: 61 74 68 6e 61 6d 65 28 29 20 77 69 74 68 20 61  athname() with a
d800: 6e 20 6f 70 74 69 6f 6e 61 6c 20 73 75 66 66 69  n optional suffi
d810: 78 20 61 64 64 65 64 2e 0a 2a 2a 20 5e 49 66 20  x added..** ^If 
d820: 61 20 73 75 66 66 69 78 20 69 73 20 61 64 64 65  a suffix is adde
d830: 64 20 74 6f 20 74 68 65 20 7a 46 69 6c 65 6e 61  d to the zFilena
d840: 6d 65 20 70 61 72 61 6d 65 74 65 72 2c 20 69 74  me parameter, it
d850: 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 73 69 73 74   will.** consist
d860: 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 22 2d 22   of a single "-"
d870: 20 63 68 61 72 61 63 74 65 72 20 66 6f 6c 6c 6f   character follo
d880: 77 65 64 20 62 79 20 6e 6f 20 6d 6f 72 65 20 74  wed by no more t
d890: 68 61 6e 0a 2a 2a 20 31 31 20 61 6c 70 68 61 6e  han.** 11 alphan
d8a0: 75 6d 65 72 69 63 20 61 6e 64 2f 6f 72 20 22 2d  umeric and/or "-
d8b0: 22 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a  " characters..**
d8c0: 20 5e 53 51 4c 69 74 65 20 66 75 72 74 68 65 72   ^SQLite further
d8d0: 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74   guarantees that
d8e0: 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 77  .** the string w
d8f0: 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 6e 64  ill be valid and
d900: 20 75 6e 63 68 61 6e 67 65 64 20 75 6e 74 69 6c   unchanged until
d910: 20 78 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a 20   xClose() is.** 
d920: 63 61 6c 6c 65 64 2e 20 42 65 63 61 75 73 65 20  called. Because 
d930: 6f 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 20  of the previous 
d940: 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20 74 68 65  sentence,.** the
d950: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
d960: 63 61 6e 20 73 61 66 65 6c 79 20 73 74 6f 72 65  can safely store
d970: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
d980: 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 66  e.** filename if
d990: 20 69 74 20 6e 65 65 64 73 20 74 6f 20 72 65 6d   it needs to rem
d9a0: 65 6d 62 65 72 20 74 68 65 20 66 69 6c 65 6e 61  ember the filena
d9b0: 6d 65 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73  me for some reas
d9c0: 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 20 7a 46  on..** If the zF
d9d0: 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65  ilename paramete
d9e0: 72 20 74 6f 20 78 4f 70 65 6e 20 69 73 20 61 20  r to xOpen is a 
d9f0: 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65  NULL pointer the
da00: 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74 20  n xOpen.** must 
da10: 69 6e 76 65 6e 74 20 69 74 73 20 6f 77 6e 20 74  invent its own t
da20: 65 6d 70 6f 72 61 72 79 20 6e 61 6d 65 20 66 6f  emporary name fo
da30: 72 20 74 68 65 20 66 69 6c 65 2e 20 20 5e 57 68  r the file.  ^Wh
da40: 65 6e 65 76 65 72 20 74 68 65 20 0a 2a 2a 20 78  enever the .** x
da50: 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74  Filename paramet
da60: 65 72 20 69 73 20 4e 55 4c 4c 20 69 74 20 77 69  er is NULL it wi
da70: 6c 6c 20 61 6c 73 6f 20 62 65 20 74 68 65 20 63  ll also be the c
da80: 61 73 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  ase that the.** 
da90: 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20  flags parameter 
daa0: 77 69 6c 6c 20 69 6e 63 6c 75 64 65 20 5b 53 51  will include [SQ
dab0: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
dac0: 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20  ONCLOSE]..**.** 
dad0: 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  The flags argume
dae0: 6e 74 20 74 6f 20 78 4f 70 65 6e 28 29 20 69 6e  nt to xOpen() in
daf0: 63 6c 75 64 65 73 20 61 6c 6c 20 62 69 74 73 20  cludes all bits 
db00: 73 65 74 20 69 6e 0a 2a 2a 20 74 68 65 20 66 6c  set in.** the fl
db10: 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ags argument to 
db20: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
db30: 28 29 5d 2e 20 20 4f 72 20 69 66 20 5b 73 71 6c  ()].  Or if [sql
db40: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20  ite3_open()].** 
db50: 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  or [sqlite3_open
db60: 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20 74  16()] is used, t
db70: 68 65 6e 20 66 6c 61 67 73 20 69 6e 63 6c 75 64  hen flags includ
db80: 65 73 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20 5b  es at least.** [
db90: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
dba0: 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45  WRITE] | [SQLITE
dbb0: 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e 20 0a  _OPEN_CREATE]. .
dbc0: 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29 20 6f 70  ** If xOpen() op
dbd0: 65 6e 73 20 61 20 66 69 6c 65 20 72 65 61 64 2d  ens a file read-
dbe0: 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20 73 65 74  only then it set
dbf0: 73 20 2a 70 4f 75 74 46 6c 61 67 73 20 74 6f 0a  s *pOutFlags to.
dc00: 2a 2a 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49  ** include [SQLI
dc10: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
dc20: 5d 2e 20 20 4f 74 68 65 72 20 62 69 74 73 20 69  ].  Other bits i
dc30: 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d 61 79  n *pOutFlags may
dc40: 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e   be set..**.** ^
dc50: 28 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73  (SQLite will als
dc60: 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65  o add one of the
dc70: 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73   following flags
dc80: 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 0a   to the xOpen().
dc90: 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e 64 69  ** call, dependi
dca0: 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65 63 74  ng on the object
dcb0: 20 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a   being opened:.*
dcc0: 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
dcd0: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
dce0: 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e  MAIN_DB].** <li>
dcf0: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d    [SQLITE_OPEN_M
dd00: 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20  AIN_JOURNAL].** 
dd10: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
dd20: 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c  EN_TEMP_DB].** <
dd30: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
dd40: 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a  N_TEMP_JOURNAL].
dd50: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
dd60: 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f  _OPEN_TRANSIENT_
dd70: 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  DB].** <li>  [SQ
dd80: 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55  LITE_OPEN_SUBJOU
dd90: 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  RNAL].** <li>  [
dda0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54  SQLITE_OPEN_MAST
ddb0: 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c  ER_JOURNAL].** <
ddc0: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
ddd0: 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 29  N_WAL].** </ul>)
dde0: 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c 65  ^.**.** The file
ddf0: 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61 74   I/O implementat
de00: 69 6f 6e 20 63 61 6e 20 75 73 65 20 74 68 65 20  ion can use the 
de10: 6f 62 6a 65 63 74 20 74 79 70 65 20 66 6c 61 67  object type flag
de20: 73 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 20 74  s to.** change t
de30: 68 65 20 77 61 79 20 69 74 20 64 65 61 6c 73 20  he way it deals 
de40: 77 69 74 68 20 66 69 6c 65 73 2e 20 20 46 6f 72  with files.  For
de50: 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70   example, an app
de60: 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61 74  lication.** that
de70: 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 61   does not care a
de80: 62 6f 75 74 20 63 72 61 73 68 20 72 65 63 6f 76  bout crash recov
de90: 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20  ery or rollback 
dea0: 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74 68  might make.** th
deb0: 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75 72  e open of a jour
dec0: 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f 70  nal file a no-op
ded0: 2e 20 20 57 72 69 74 65 73 20 74 6f 20 74 68 69  .  Writes to thi
dee0: 73 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 0a  s journal would.
def0: 2a 2a 20 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70  ** also be no-op
df00: 73 2c 20 61 6e 64 20 61 6e 79 20 61 74 74 65 6d  s, and any attem
df10: 70 74 20 74 6f 20 72 65 61 64 20 74 68 65 20 6a  pt to read the j
df20: 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 20 72 65 74  ournal would ret
df30: 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f  urn.** SQLITE_IO
df40: 45 52 52 2e 20 20 4f 72 20 74 68 65 20 69 6d 70  ERR.  Or the imp
df50: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68  lementation migh
df60: 74 20 72 65 63 6f 67 6e 69 7a 65 20 74 68 61 74  t recognize that
df70: 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66   a database.** f
df80: 69 6c 65 20 77 69 6c 6c 20 62 65 20 64 6f 69 6e  ile will be doin
df90: 67 20 70 61 67 65 2d 61 6c 69 67 6e 65 64 20 73  g page-aligned s
dfa0: 65 63 74 6f 72 20 72 65 61 64 73 20 61 6e 64 20  ector reads and 
dfb0: 77 72 69 74 65 73 20 69 6e 20 61 20 72 61 6e 64  writes in a rand
dfc0: 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20 61 6e 64 20  om.** order and 
dfd0: 73 65 74 20 75 70 20 69 74 73 20 49 2f 4f 20 73  set up its I/O s
dfe0: 75 62 73 79 73 74 65 6d 20 61 63 63 6f 72 64 69  ubsystem accordi
dff0: 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  ngly..**.** SQLi
e000: 74 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 61 64  te might also ad
e010: 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c  d one of the fol
e020: 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20  lowing flags to 
e030: 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64  the xOpen method
e040: 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
e050: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45  <li> [SQLITE_OPE
e060: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d  N_DELETEONCLOSE]
e070: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
e080: 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d  _OPEN_EXCLUSIVE]
e090: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
e0a0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  The [SQLITE_OPEN
e0b0: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 20  _DELETEONCLOSE] 
e0c0: 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 65 20 66  flag means the f
e0d0: 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a  ile should be.**
e0e0: 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 69 74   deleted when it
e0f0: 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 5e 54 68   is closed.  ^Th
e100: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44  e [SQLITE_OPEN_D
e110: 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a  ELETEONCLOSE].**
e120: 20 77 69 6c 6c 20 62 65 20 73 65 74 20 66 6f 72   will be set for
e130: 20 54 45 4d 50 20 64 61 74 61 62 61 73 65 73 20   TEMP databases 
e140: 61 6e 64 20 74 68 65 69 72 20 6a 6f 75 72 6e 61  and their journa
e150: 6c 73 2c 20 74 72 61 6e 73 69 65 6e 74 0a 2a 2a  ls, transient.**
e160: 20 64 61 74 61 62 61 73 65 73 2c 20 61 6e 64 20   databases, and 
e170: 73 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a  subjournals..**.
e180: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
e190: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 20  OPEN_EXCLUSIVE] 
e1a0: 66 6c 61 67 20 69 73 20 61 6c 77 61 79 73 20 75  flag is always u
e1b0: 73 65 64 20 69 6e 20 63 6f 6e 6a 75 6e 63 74 69  sed in conjuncti
e1c0: 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b  on.** with the [
e1d0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
e1e0: 54 45 5d 20 66 6c 61 67 2c 20 77 68 69 63 68 20  TE] flag, which 
e1f0: 61 72 65 20 62 6f 74 68 20 64 69 72 65 63 74 6c  are both directl
e200: 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75 73 20 74  y.** analogous t
e210: 6f 20 74 68 65 20 4f 5f 45 58 43 4c 20 61 6e 64  o the O_EXCL and
e220: 20 4f 5f 43 52 45 41 54 20 66 6c 61 67 73 20 6f   O_CREAT flags o
e230: 66 20 74 68 65 20 50 4f 53 49 58 20 6f 70 65 6e  f the POSIX open
e240: 28 29 0a 2a 2a 20 41 50 49 2e 20 20 54 68 65 20  ().** API.  The 
e250: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c  SQLITE_OPEN_EXCL
e260: 55 53 49 56 45 20 66 6c 61 67 2c 20 77 68 65 6e  USIVE flag, when
e270: 20 70 61 69 72 65 64 20 77 69 74 68 20 74 68 65   paired with the
e280: 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 50 45 4e   .** SQLITE_OPEN
e290: 5f 43 52 45 41 54 45 2c 20 69 73 20 75 73 65 64  _CREATE, is used
e2a0: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61   to indicate tha
e2b0: 74 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 61 6c  t file should al
e2c0: 77 61 79 73 0a 2a 2a 20 62 65 20 63 72 65 61 74  ways.** be creat
e2d0: 65 64 2c 20 61 6e 64 20 74 68 61 74 20 69 74 20  ed, and that it 
e2e0: 69 73 20 61 6e 20 65 72 72 6f 72 20 69 66 20 69  is an error if i
e2f0: 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 73  t already exists
e300: 2e 0a 2a 2a 20 49 74 20 69 73 20 3c 69 3e 6e 6f  ..** It is <i>no
e310: 74 3c 2f 69 3e 20 75 73 65 64 20 74 6f 20 69 6e  t</i> used to in
e320: 64 69 63 61 74 65 20 74 68 65 20 66 69 6c 65 20  dicate the file 
e330: 73 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65 64  should be opened
e340: 20 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73 69   .** for exclusi
e350: 76 65 20 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a  ve access..**.**
e360: 20 5e 41 74 20 6c 65 61 73 74 20 73 7a 4f 73 46   ^At least szOsF
e370: 69 6c 65 20 62 79 74 65 73 20 6f 66 20 6d 65 6d  ile bytes of mem
e380: 6f 72 79 20 61 72 65 20 61 6c 6c 6f 63 61 74 65  ory are allocate
e390: 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 74  d by SQLite.** t
e3a0: 6f 20 68 6f 6c 64 20 74 68 65 20 20 5b 73 71 6c  o hold the  [sql
e3b0: 69 74 65 33 5f 66 69 6c 65 5d 20 73 74 72 75 63  ite3_file] struc
e3c0: 74 75 72 65 20 70 61 73 73 65 64 20 61 73 20 74  ture passed as t
e3d0: 68 65 20 74 68 69 72 64 0a 2a 2a 20 61 72 67 75  he third.** argu
e3e0: 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 2e 20 20  ment to xOpen.  
e3f0: 54 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64  The xOpen method
e400: 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 74   does not have t
e410: 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 74 68  o.** allocate th
e420: 65 20 73 74 72 75 63 74 75 72 65 3b 20 69 74 20  e structure; it 
e430: 73 68 6f 75 6c 64 20 6a 75 73 74 20 66 69 6c 6c  should just fill
e440: 20 69 74 20 69 6e 2e 20 20 4e 6f 74 65 20 74 68   it in.  Note th
e450: 61 74 0a 2a 2a 20 74 68 65 20 78 4f 70 65 6e 20  at.** the xOpen 
e460: 6d 65 74 68 6f 64 20 6d 75 73 74 20 73 65 74 20  method must set 
e470: 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  the sqlite3_file
e480: 2e 70 4d 65 74 68 6f 64 73 20 74 6f 20 65 69 74  .pMethods to eit
e490: 68 65 72 0a 2a 2a 20 61 20 76 61 6c 69 64 20 5b  her.** a valid [
e4a0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
e4b0: 64 73 5d 20 6f 62 6a 65 63 74 20 6f 72 20 74 6f  ds] object or to
e4c0: 20 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e 20 6d 75   NULL.  xOpen mu
e4d0: 73 74 20 64 6f 0a 2a 2a 20 74 68 69 73 20 65 76  st do.** this ev
e4e0: 65 6e 20 69 66 20 74 68 65 20 6f 70 65 6e 20 66  en if the open f
e4f0: 61 69 6c 73 2e 20 20 53 51 4c 69 74 65 20 65 78  ails.  SQLite ex
e500: 70 65 63 74 73 20 74 68 61 74 20 74 68 65 20 73  pects that the s
e510: 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74  qlite3_file.pMet
e520: 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65 6e 74 20  hods.** element 
e530: 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 66  will be valid af
e540: 74 65 72 20 78 4f 70 65 6e 20 72 65 74 75 72 6e  ter xOpen return
e550: 73 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20  s regardless of 
e560: 74 68 65 20 73 75 63 63 65 73 73 0a 2a 2a 20 6f  the success.** o
e570: 72 20 66 61 69 6c 75 72 65 20 6f 66 20 74 68 65  r failure of the
e580: 20 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a   xOpen call..**.
e590: 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73  ** [[sqlite3_vfs
e5a0: 2e 78 41 63 63 65 73 73 5d 5d 0a 2a 2a 20 5e 54  .xAccess]].** ^T
e5b0: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
e5c0: 74 20 74 6f 20 78 41 63 63 65 73 73 28 29 20 6d  t to xAccess() m
e5d0: 61 79 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 43  ay be [SQLITE_AC
e5e0: 43 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a 20  CESS_EXISTS].** 
e5f0: 74 6f 20 74 65 73 74 20 66 6f 72 20 74 68 65 20  to test for the 
e600: 65 78 69 73 74 65 6e 63 65 20 6f 66 20 61 20 66  existence of a f
e610: 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ile, or [SQLITE_
e620: 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45  ACCESS_READWRITE
e630: 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68 65  ] to.** test whe
e640: 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 72  ther a file is r
e650: 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74  eadable and writ
e660: 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45  able, or [SQLITE
e670: 5f 41 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a 2a  _ACCESS_READ].**
e680: 20 74 6f 20 74 65 73 74 20 77 68 65 74 68 65 72   to test whether
e690: 20 61 20 66 69 6c 65 20 69 73 20 61 74 20 6c 65   a file is at le
e6a0: 61 73 74 20 72 65 61 64 61 62 6c 65 2e 20 20 20  ast readable.   
e6b0: 54 68 65 20 66 69 6c 65 20 63 61 6e 20 62 65 20  The file can be 
e6c0: 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e 0a  a.** directory..
e6d0: 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69  **.** ^SQLite wi
e6e0: 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63 61  ll always alloca
e6f0: 74 65 20 61 74 20 6c 65 61 73 74 20 6d 78 50 61  te at least mxPa
e700: 74 68 6e 61 6d 65 2b 31 20 62 79 74 65 73 20 66  thname+1 bytes f
e710: 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75 74  or the.** output
e720: 20 62 75 66 66 65 72 20 78 46 75 6c 6c 50 61 74   buffer xFullPat
e730: 68 6e 61 6d 65 2e 20 20 54 68 65 20 65 78 61 63  hname.  The exac
e740: 74 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6f 75  t size of the ou
e750: 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69  tput buffer.** i
e760: 73 20 61 6c 73 6f 20 70 61 73 73 65 64 20 61 73  s also passed as
e770: 20 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20   a parameter to 
e780: 62 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e 20 49  both  methods. I
e790: 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66  f the output buf
e7a0: 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c 61  fer.** is not la
e7b0: 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51 4c  rge enough, [SQL
e7c0: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73 68  ITE_CANTOPEN] sh
e7d0: 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64  ould be returned
e7e0: 2e 20 53 69 6e 63 65 20 74 68 69 73 20 69 73 0a  . Since this is.
e7f0: 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73 20 61 20  ** handled as a 
e800: 66 61 74 61 6c 20 65 72 72 6f 72 20 62 79 20 53  fatal error by S
e810: 51 4c 69 74 65 2c 20 76 66 73 20 69 6d 70 6c 65  QLite, vfs imple
e820: 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c  mentations shoul
e830: 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74 6f  d endeavor.** to
e840: 20 70 72 65 76 65 6e 74 20 74 68 69 73 20 62 79   prevent this by
e850: 20 73 65 74 74 69 6e 67 20 6d 78 50 61 74 68 6e   setting mxPathn
e860: 61 6d 65 20 74 6f 20 61 20 73 75 66 66 69 63 69  ame to a suffici
e870: 65 6e 74 6c 79 20 6c 61 72 67 65 20 76 61 6c 75  ently large valu
e880: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 61  e..**.** The xRa
e890: 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c 65  ndomness(), xSle
e8a0: 65 70 28 29 2c 20 78 43 75 72 72 65 6e 74 54 69  ep(), xCurrentTi
e8b0: 6d 65 28 29 2c 20 61 6e 64 20 78 43 75 72 72 65  me(), and xCurre
e8c0: 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 0a 2a 2a  ntTimeInt64().**
e8d0: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
e8e0: 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 61 20 70  not strictly a p
e8f0: 61 72 74 20 6f 66 20 74 68 65 20 66 69 6c 65 73  art of the files
e900: 79 73 74 65 6d 2c 20 62 75 74 20 74 68 65 79 20  ystem, but they 
e910: 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64 20  are.** included 
e920: 69 6e 20 74 68 65 20 56 46 53 20 73 74 72 75 63  in the VFS struc
e930: 74 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65 74  ture for complet
e940: 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78 52  eness..** The xR
e950: 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e 63  andomness() func
e960: 74 69 6f 6e 20 61 74 74 65 6d 70 74 73 20 74 6f  tion attempts to
e970: 20 72 65 74 75 72 6e 20 6e 42 79 74 65 73 20 62   return nBytes b
e980: 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d  ytes.** of good-
e990: 71 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e 65  quality randomne
e9a0: 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20 54  ss into zOut.  T
e9b0: 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
e9c0: 69 73 0a 2a 2a 20 74 68 65 20 61 63 74 75 61 6c  is.** the actual
e9d0: 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
e9e0: 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f   of randomness o
e9f0: 62 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20  btained..** The 
ea00: 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 20  xSleep() method 
ea10: 63 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c 69  causes the calli
ea20: 6e 67 20 74 68 72 65 61 64 20 74 6f 20 73 6c 65  ng thread to sle
ea30: 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65 61  ep for at.** lea
ea40: 73 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  st the number of
ea50: 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20 67 69   microseconds gi
ea60: 76 65 6e 2e 20 20 5e 54 68 65 20 78 43 75 72 72  ven.  ^The xCurr
ea70: 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65 74  entTime().** met
ea80: 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 4a 75  hod returns a Ju
ea90: 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62 65 72 20  lian Day Number 
eaa0: 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74 20  for the current 
eab0: 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20 61 73  date and time as
eac0: 0a 2a 2a 20 61 20 66 6c 6f 61 74 69 6e 67 20 70  .** a floating p
ead0: 6f 69 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a 20 5e  oint value..** ^
eae0: 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65  The xCurrentTime
eaf0: 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 72  Int64() method r
eb00: 65 74 75 72 6e 73 2c 20 61 73 20 61 6e 20 69 6e  eturns, as an in
eb10: 74 65 67 65 72 2c 20 74 68 65 20 4a 75 6c 69 61  teger, the Julia
eb20: 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d 62 65 72 20  n.** Day Number 
eb30: 6d 75 6c 74 69 70 6c 69 65 64 20 62 79 20 38 36  multiplied by 86
eb40: 34 30 30 30 30 30 20 28 74 68 65 20 6e 75 6d 62  400000 (the numb
eb50: 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e  er of millisecon
eb60: 64 73 20 69 6e 20 0a 2a 2a 20 61 20 32 34 2d 68  ds in .** a 24-h
eb70: 6f 75 72 20 64 61 79 29 2e 20 20 0a 2a 2a 20 5e  our day).  .** ^
eb80: 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20  SQLite will use 
eb90: 74 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65  the xCurrentTime
eba0: 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 74  Int64() method t
ebb0: 6f 20 67 65 74 20 74 68 65 20 63 75 72 72 65 6e  o get the curren
ebc0: 74 0a 2a 2a 20 64 61 74 65 20 61 6e 64 20 74 69  t.** date and ti
ebd0: 6d 65 20 69 66 20 74 68 61 74 20 6d 65 74 68 6f  me if that metho
ebe0: 64 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 28  d is available (
ebf0: 69 66 20 69 56 65 72 73 69 6f 6e 20 69 73 20 32  if iVersion is 2
ec00: 20 6f 72 20 0a 2a 2a 20 67 72 65 61 74 65 72 20   or .** greater 
ec10: 61 6e 64 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  and the function
ec20: 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20   pointer is not 
ec30: 4e 55 4c 4c 29 20 61 6e 64 20 77 69 6c 6c 20 66  NULL) and will f
ec40: 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f 20 78  all back.** to x
ec50: 43 75 72 72 65 6e 74 54 69 6d 65 28 29 20 69 66  CurrentTime() if
ec60: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74   xCurrentTimeInt
ec70: 36 34 28 29 20 69 73 20 75 6e 61 76 61 69 6c 61  64() is unavaila
ec80: 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ble..**.** ^The 
ec90: 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 29  xSetSystemCall()
eca0: 2c 20 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c  , xGetSystemCall
ecb0: 28 29 2c 20 61 6e 64 20 78 4e 65 73 74 53 79 73  (), and xNestSys
ecc0: 74 65 6d 43 61 6c 6c 28 29 20 69 6e 74 65 72 66  temCall() interf
ecd0: 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 20  aces.** are not 
ece0: 75 73 65 64 20 62 79 20 74 68 65 20 53 51 4c 69  used by the SQLi
ecf0: 74 65 20 63 6f 72 65 2e 20 20 54 68 65 73 65 20  te core.  These 
ed00: 6f 70 74 69 6f 6e 61 6c 20 69 6e 74 65 72 66 61  optional interfa
ed10: 63 65 73 20 61 72 65 20 70 72 6f 76 69 64 65 64  ces are provided
ed20: 0a 2a 2a 20 62 79 20 73 6f 6d 65 20 56 46 53 65  .** by some VFSe
ed30: 73 20 74 6f 20 66 61 63 69 6c 69 74 61 74 65 20  s to facilitate 
ed40: 74 65 73 74 69 6e 67 20 6f 66 20 74 68 65 20 56  testing of the V
ed50: 46 53 20 63 6f 64 65 2e 20 42 79 20 6f 76 65 72  FS code. By over
ed60: 72 69 64 69 6e 67 20 0a 2a 2a 20 73 79 73 74 65  riding .** syste
ed70: 6d 20 63 61 6c 6c 73 20 77 69 74 68 20 66 75 6e  m calls with fun
ed80: 63 74 69 6f 6e 73 20 75 6e 64 65 72 20 69 74 73  ctions under its
ed90: 20 63 6f 6e 74 72 6f 6c 2c 20 61 20 74 65 73 74   control, a test
eda0: 20 70 72 6f 67 72 61 6d 20 63 61 6e 0a 2a 2a 20   program can.** 
edb0: 73 69 6d 75 6c 61 74 65 20 66 61 75 6c 74 73 20  simulate faults 
edc0: 61 6e 64 20 65 72 72 6f 72 20 63 6f 6e 64 69 74  and error condit
edd0: 69 6f 6e 73 20 74 68 61 74 20 77 6f 75 6c 64 20  ions that would 
ede0: 6f 74 68 65 72 77 69 73 65 20 62 65 20 64 69 66  otherwise be dif
edf0: 66 69 63 75 6c 74 0a 2a 2a 20 6f 72 20 69 6d 70  ficult.** or imp
ee00: 6f 73 73 69 62 6c 65 20 74 6f 20 69 6e 64 75 63  ossible to induc
ee10: 65 2e 20 20 54 68 65 20 73 65 74 20 6f 66 20 73  e.  The set of s
ee20: 79 73 74 65 6d 20 63 61 6c 6c 73 20 74 68 61 74  ystem calls that
ee30: 20 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64 64   can be overridd
ee40: 65 6e 0a 2a 2a 20 76 61 72 69 65 73 20 66 72 6f  en.** varies fro
ee50: 6d 20 6f 6e 65 20 56 46 53 20 74 6f 20 61 6e 6f  m one VFS to ano
ee60: 74 68 65 72 2c 20 61 6e 64 20 66 72 6f 6d 20 6f  ther, and from o
ee70: 6e 65 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68  ne version of th
ee80: 65 20 73 61 6d 65 20 56 46 53 20 74 6f 20 74 68  e same VFS to th
ee90: 65 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70 70 6c  e.** next.  Appl
eea0: 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 75 73  ications that us
eeb0: 65 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63  e these interfac
eec0: 65 73 20 6d 75 73 74 20 62 65 20 70 72 65 70 61  es must be prepa
eed0: 72 65 64 20 66 6f 72 20 61 6e 79 0a 2a 2a 20 6f  red for any.** o
eee0: 72 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 69  r all of these i
eef0: 6e 74 65 72 66 61 63 65 73 20 74 6f 20 62 65 20  nterfaces to be 
ef00: 4e 55 4c 4c 20 6f 72 20 66 6f 72 20 74 68 65 69  NULL or for thei
ef10: 72 20 62 65 68 61 76 69 6f 72 20 74 6f 20 63 68  r behavior to ch
ef20: 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f 6e 65  ange.** from one
ef30: 20 72 65 6c 65 61 73 65 20 74 6f 20 74 68 65 20   release to the 
ef40: 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69  next.  Applicati
ef50: 6f 6e 73 20 6d 75 73 74 20 6e 6f 74 20 61 74 74  ons must not att
ef60: 65 6d 70 74 20 74 6f 20 61 63 63 65 73 73 0a 2a  empt to access.*
ef70: 2a 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 6d  * any of these m
ef80: 65 74 68 6f 64 73 20 69 66 20 74 68 65 20 69 56  ethods if the iV
ef90: 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 56 46  ersion of the VF
efa0: 53 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 33  S is less than 3
efb0: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
efc0: 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20  uct sqlite3_vfs 
efd0: 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a 74 79 70  sqlite3_vfs;.typ
efe0: 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69  edef void (*sqli
eff0: 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29  te3_syscall_ptr)
f000: 28 76 6f 69 64 29 3b 0a 73 74 72 75 63 74 20 73  (void);.struct s
f010: 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20 69  qlite3_vfs {.  i
f020: 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20 20  nt iVersion;    
f030: 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75 63          /* Struc
f040: 74 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d  ture version num
f050: 62 65 72 20 28 63 75 72 72 65 6e 74 6c 79 20 33  ber (currently 3
f060: 29 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 46  ) */.  int szOsF
f070: 69 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20 20  ile;            
f080: 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63 6c  /* Size of subcl
f090: 61 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66 69  assed sqlite3_fi
f0a0: 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 61  le */.  int mxPa
f0b0: 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20 20  thname;         
f0c0: 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c 65   /* Maximum file
f0d0: 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74 68   pathname length
f0e0: 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76 66   */.  sqlite3_vf
f0f0: 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20 2f  s *pNext;      /
f100: 2a 20 4e 65 78 74 20 72 65 67 69 73 74 65 72 65  * Next registere
f110: 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 74  d VFS */.  const
f120: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 20   char *zName;   
f130: 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74      /* Name of t
f140: 68 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c 65  his virtual file
f150: 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f 69   system */.  voi
f160: 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20  d *pAppData;    
f170: 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65 72        /* Pointer
f180: 20 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   to application-
f190: 73 70 65 63 69 66 69 63 20 64 61 74 61 20 2a 2f  specific data */
f1a0: 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28  .  int (*xOpen)(
f1b0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
f1c0: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
f1d0: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 0a   sqlite3_file*,.
f1e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69                 i
f1f0: 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70  nt flags, int *p
f200: 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e 74  OutFlags);.  int
f210: 20 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c 69   (*xDelete)(sqli
f220: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
f230: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74  char *zName, int
f240: 20 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e 74   syncDir);.  int
f250: 20 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c 69   (*xAccess)(sqli
f260: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
f270: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74  char *zName, int
f280: 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52 65   flags, int *pRe
f290: 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  sOut);.  int (*x
f2a0: 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73 71  FullPathname)(sq
f2b0: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
f2c0: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69  t char *zName, i
f2d0: 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a  nt nOut, char *z
f2e0: 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a  Out);.  void *(*
f2f0: 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65 33  xDlOpen)(sqlite3
f300: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
f310: 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a 20  r *zFilename);. 
f320: 20 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f 72   void (*xDlError
f330: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
f340: 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20  int nByte, char 
f350: 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f 69  *zErrMsg);.  voi
f360: 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73 71  d (*(*xDlSym)(sq
f370: 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64 2a  lite3_vfs*,void*
f380: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53  , const char *zS
f390: 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a 20  ymbol))(void);. 
f3a0: 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65   void (*xDlClose
f3b0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
f3c0: 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  void*);.  int (*
f3d0: 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c  xRandomness)(sql
f3e0: 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e  ite3_vfs*, int n
f3f0: 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74  Byte, char *zOut
f400: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65 65  );.  int (*xSlee
f410: 70 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  p)(sqlite3_vfs*,
f420: 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64   int microsecond
f430: 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75 72  s);.  int (*xCur
f440: 72 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74 65  rentTime)(sqlite
f450: 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29  3_vfs*, double*)
f460: 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c 61  ;.  int (*xGetLa
f470: 73 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33  stError)(sqlite3
f480: 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61 72  _vfs*, int, char
f490: 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54   *);.  /*.  ** T
f4a0: 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65  he methods above
f4b0: 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 20   are in version 
f4c0: 31 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f  1 of the sqlite_
f4d0: 76 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a 2a 20  vfs object.  ** 
f4e0: 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 6f  definition.  Tho
f4f0: 73 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 61  se that follow a
f500: 72 65 20 61 64 64 65 64 20 69 6e 20 76 65 72 73  re added in vers
f510: 69 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72 0a 20  ion 2 or later. 
f520: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 43 75 72   */.  int (*xCur
f530: 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 29 28 73  rentTimeInt64)(s
f540: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 73 71 6c  qlite3_vfs*, sql
f550: 69 74 65 33 5f 69 6e 74 36 34 2a 29 3b 0a 20 20  ite3_int64*);.  
f560: 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68  /*.  ** The meth
f570: 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e  ods above are in
f580: 20 76 65 72 73 69 6f 6e 73 20 31 20 61 6e 64 20   versions 1 and 
f590: 32 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f  2 of the sqlite_
f5a0: 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a  vfs object..  **
f5b0: 20 54 68 6f 73 65 20 62 65 6c 6f 77 20 61 72 65   Those below are
f5c0: 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 61   for version 3 a
f5d0: 6e 64 20 67 72 65 61 74 65 72 2e 0a 20 20 2a 2f  nd greater..  */
f5e0: 0a 20 20 69 6e 74 20 28 2a 78 53 65 74 53 79 73  .  int (*xSetSys
f5f0: 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33  temCall)(sqlite3
f600: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
f610: 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65  r *zName, sqlite
f620: 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 3b 0a  3_syscall_ptr);.
f630: 20 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c    sqlite3_syscal
f640: 6c 5f 70 74 72 20 28 2a 78 47 65 74 53 79 73 74  l_ptr (*xGetSyst
f650: 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f  emCall)(sqlite3_
f660: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
f670: 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f 6e 73   *zName);.  cons
f680: 74 20 63 68 61 72 20 2a 28 2a 78 4e 65 78 74 53  t char *(*xNextS
f690: 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74  ystemCall)(sqlit
f6a0: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
f6b0: 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 2f  har *zName);.  /
f6c0: 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f  *.  ** The metho
f6d0: 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20  ds above are in 
f6e0: 76 65 72 73 69 6f 6e 73 20 31 20 74 68 72 6f 75  versions 1 throu
f6f0: 67 68 20 33 20 6f 66 20 74 68 65 20 73 71 6c 69  gh 3 of the sqli
f700: 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20  te_vfs object.. 
f710: 20 2a 2a 20 4e 65 77 20 66 69 65 6c 64 73 20 6d   ** New fields m
f720: 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 69  ay be appended i
f730: 6e 20 66 69 67 75 72 65 20 76 65 72 73 69 6f 6e  n figure version
f740: 73 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f 6e  s.  The iVersion
f750: 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c 6c  .  ** value will
f760: 20 69 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e 65   increment whene
f770: 76 65 72 20 74 68 69 73 20 68 61 70 70 65 6e 73  ver this happens
f780: 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  . .  */.};../*.*
f790: 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67  * CAPI3REF: Flag
f7a0: 73 20 66 6f 72 20 74 68 65 20 78 41 63 63 65 73  s for the xAcces
f7b0: 73 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a  s VFS method.**.
f7c0: 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72  ** These integer
f7d0: 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20 62   constants can b
f7e0: 65 20 75 73 65 64 20 61 73 20 74 68 65 20 74 68  e used as the th
f7f0: 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
f800: 0a 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73 20  .** the xAccess 
f810: 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71  method of an [sq
f820: 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
f830: 74 2e 20 20 54 68 65 79 20 64 65 74 65 72 6d 69  t.  They determi
f840: 6e 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64 20  ne.** what kind 
f850: 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e 73 20 74  of permissions t
f860: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
f870: 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72  d is looking for
f880: 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45  ..** With SQLITE
f890: 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 2c 20  _ACCESS_EXISTS, 
f8a0: 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68  the xAccess meth
f8b0: 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65  od.** simply che
f8c0: 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20  cks whether the 
f8d0: 66 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a 20  file exists..** 
f8e0: 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45  With SQLITE_ACCE
f8f0: 53 53 5f 52 45 41 44 57 52 49 54 45 2c 20 74 68  SS_READWRITE, th
f900: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
f910: 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68  .** checks wheth
f920: 65 72 20 74 68 65 20 6e 61 6d 65 64 20 64 69 72  er the named dir
f930: 65 63 74 6f 72 79 20 69 73 20 62 6f 74 68 20 72  ectory is both r
f940: 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74  eadable and writ
f950: 61 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74 68 65  able.** (in othe
f960: 72 20 77 6f 72 64 73 2c 20 69 66 20 66 69 6c 65  r words, if file
f970: 73 20 63 61 6e 20 62 65 20 61 64 64 65 64 2c 20  s can be added, 
f980: 72 65 6d 6f 76 65 64 2c 20 61 6e 64 20 72 65 6e  removed, and ren
f990: 61 6d 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 74  amed within.** t
f9a0: 68 65 20 64 69 72 65 63 74 6f 72 79 29 2e 0a 2a  he directory)..*
f9b0: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43  * The SQLITE_ACC
f9c0: 45 53 53 5f 52 45 41 44 57 52 49 54 45 20 63 6f  ESS_READWRITE co
f9d0: 6e 73 74 61 6e 74 20 69 73 20 63 75 72 72 65 6e  nstant is curren
f9e0: 74 6c 79 20 75 73 65 64 20 6f 6e 6c 79 20 62 79  tly used only by
f9f0: 20 74 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73 74   the.** [temp_st
fa00: 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72  ore_directory pr
fa10: 61 67 6d 61 5d 2c 20 74 68 6f 75 67 68 20 74 68  agma], though th
fa20: 69 73 20 63 6f 75 6c 64 20 63 68 61 6e 67 65 20  is could change 
fa30: 69 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a 20 72  in a future.** r
fa40: 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65  elease of SQLite
fa50: 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45  ..** With SQLITE
fa60: 5f 41 43 43 45 53 53 5f 52 45 41 44 2c 20 74 68  _ACCESS_READ, th
fa70: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
fa80: 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68  .** checks wheth
fa90: 65 72 20 74 68 65 20 66 69 6c 65 20 69 73 20 72  er the file is r
faa0: 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20 53 51  eadable.  The SQ
fab0: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
fac0: 20 63 6f 6e 73 74 61 6e 74 20 69 73 0a 2a 2a 20   constant is.** 
fad0: 63 75 72 72 65 6e 74 6c 79 20 75 6e 75 73 65 64  currently unused
fae0: 2c 20 74 68 6f 75 67 68 20 69 74 20 6d 69 67 68  , though it migh
faf0: 74 20 62 65 20 75 73 65 64 20 69 6e 20 61 20 66  t be used in a f
fb00: 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66  uture release of
fb10: 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23  .** SQLite..*/.#
fb20: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43  define SQLITE_AC
fb30: 43 45 53 53 5f 45 58 49 53 54 53 20 20 20 20 30  CESS_EXISTS    0
fb40: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
fb50: 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45  ACCESS_READWRITE
fb60: 20 31 20 20 20 2f 2a 20 55 73 65 64 20 62 79 20   1   /* Used by 
fb70: 50 52 41 47 4d 41 20 74 65 6d 70 5f 73 74 6f 72  PRAGMA temp_stor
fb80: 65 5f 64 69 72 65 63 74 6f 72 79 20 2a 2f 0a 23  e_directory */.#
fb90: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43  define SQLITE_AC
fba0: 43 45 53 53 5f 52 45 41 44 20 20 20 20 20 20 32  CESS_READ      2
fbb0: 20 20 20 2f 2a 20 55 6e 75 73 65 64 20 2a 2f 0a     /* Unused */.
fbc0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
fbd0: 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78   Flags for the x
fbe0: 53 68 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74 68  ShmLock VFS meth
fbf0: 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69  od.**.** These i
fc00: 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73  nteger constants
fc10: 20 64 65 66 69 6e 65 20 74 68 65 20 76 61 72 69   define the vari
fc20: 6f 75 73 20 6c 6f 63 6b 69 6e 67 20 6f 70 65 72  ous locking oper
fc30: 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77 65  ations.** allowe
fc40: 64 20 62 79 20 74 68 65 20 78 53 68 6d 4c 6f 63  d by the xShmLoc
fc50: 6b 20 6d 65 74 68 6f 64 20 6f 66 20 5b 73 71 6c  k method of [sql
fc60: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
fc70: 2e 20 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77  .  The.** follow
fc80: 69 6e 67 20 61 72 65 20 74 68 65 20 6f 6e 6c 79  ing are the only
fc90: 20 6c 65 67 61 6c 20 63 6f 6d 62 69 6e 61 74 69   legal combinati
fca0: 6f 6e 73 20 6f 66 20 66 6c 61 67 73 20 74 6f 20  ons of flags to 
fcb0: 74 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b 20  the.** xShmLock 
fcc0: 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75  method:.**.** <u
fcd0: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49  l>.** <li>  SQLI
fce0: 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51  TE_SHM_LOCK | SQ
fcf0: 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a  LITE_SHM_SHARED.
fd00: 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f  ** <li>  SQLITE_
fd10: 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54  SHM_LOCK | SQLIT
fd20: 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a  E_SHM_EXCLUSIVE.
fd30: 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f  ** <li>  SQLITE_
fd40: 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c  SHM_UNLOCK | SQL
fd50: 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a  ITE_SHM_SHARED.*
fd60: 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53  * <li>  SQLITE_S
fd70: 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49  HM_UNLOCK | SQLI
fd80: 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45  TE_SHM_EXCLUSIVE
fd90: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
fda0: 57 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c 20  When unlocking, 
fdb0: 74 68 65 20 73 61 6d 65 20 53 48 41 52 45 44 20  the same SHARED 
fdc0: 6f 72 20 45 58 43 4c 55 53 49 56 45 20 66 6c 61  or EXCLUSIVE fla
fdd0: 67 20 6d 75 73 74 20 62 65 20 73 75 70 70 6c 69  g must be suppli
fde0: 65 64 20 61 73 0a 2a 2a 20 77 61 73 20 67 69 76  ed as.** was giv
fdf0: 65 6e 20 6e 6f 20 74 68 65 20 63 6f 72 72 65 73  en no the corres
fe00: 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20 20 0a  ponding lock.  .
fe10: 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f  **.** The xShmLo
fe20: 63 6b 20 6d 65 74 68 6f 64 20 63 61 6e 20 74 72  ck method can tr
fe30: 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e  ansition between
fe40: 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 53 48   unlocked and SH
fe50: 41 52 45 44 20 6f 72 0a 2a 2a 20 62 65 74 77 65  ARED or.** betwe
fe60: 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20  en unlocked and 
fe70: 45 58 43 4c 55 53 49 56 45 2e 20 20 49 74 20 63  EXCLUSIVE.  It c
fe80: 61 6e 6e 6f 74 20 74 72 61 6e 73 69 74 69 6f 6e  annot transition
fe90: 20 62 65 74 77 65 65 6e 20 53 48 41 52 45 44 0a   between SHARED.
fea0: 2a 2a 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45  ** and EXCLUSIVE
feb0: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
fec0: 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 20  ITE_SHM_UNLOCK  
fed0: 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
fee0: 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 20  QLITE_SHM_LOCK  
fef0: 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65         2.#define
ff00: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52   SQLITE_SHM_SHAR
ff10: 45 44 20 20 20 20 20 20 20 34 0a 23 64 65 66 69  ED       4.#defi
ff20: 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58  ne SQLITE_SHM_EX
ff30: 43 4c 55 53 49 56 45 20 20 20 20 38 0a 0a 2f 2a  CLUSIVE    8../*
ff40: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 61  .** CAPI3REF: Ma
ff50: 78 69 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b 20 69  ximum xShmLock i
ff60: 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ndex.**.** The x
ff70: 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f  ShmLock method o
ff80: 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  n [sqlite3_io_me
ff90: 74 68 6f 64 73 5d 20 6d 61 79 20 75 73 65 20 76  thods] may use v
ffa0: 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e  alues.** between
ffb0: 20 30 20 61 6e 64 20 74 68 69 73 20 75 70 70 65   0 and this uppe
ffc0: 72 20 62 6f 75 6e 64 20 61 73 20 69 74 73 20 22  r bound as its "
ffd0: 6f 66 66 73 65 74 22 20 61 72 67 75 6d 65 6e 74  offset" argument
ffe0: 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20  ..** The SQLite 
fff0: 63 6f 72 65 20 77 69 6c 6c 20 6e 65 76 65 72 20  core will never 
10000 61 74 74 65 6d 70 74 20 74 6f 20 61 63 71 75 69  attempt to acqui
10010 72 65 20 6f 72 20 72 65 6c 65 61 73 65 20 61 0a  re or release a.
10020 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73 69 64 65 20  ** lock outside 
10030 6f 66 20 74 68 69 73 20 72 61 6e 67 65 0a 2a 2f  of this range.*/
10040 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
10050 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20 20 20  SHM_NLOCK       
10060 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   8.../*.** CAPI3
10070 52 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65 20  REF: Initialize 
10080 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61  The SQLite Libra
10090 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ry.**.** ^The sq
100a0 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
100b0 28 29 20 72 6f 75 74 69 6e 65 20 69 6e 69 74 69  () routine initi
100c0 61 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53 51  alizes the.** SQ
100d0 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 5e  Lite library.  ^
100e0 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74  The sqlite3_shut
100f0 64 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a  down() routine.*
10100 2a 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 6e  * deallocates an
10110 79 20 72 65 73 6f 75 72 63 65 73 20 74 68 61 74  y resources that
10120 20 77 65 72 65 20 61 6c 6c 6f 63 61 74 65 64 20   were allocated 
10130 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  by sqlite3_initi
10140 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65 73  alize()..** Thes
10150 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 64  e routines are d
10160 65 73 69 67 6e 65 64 20 74 6f 20 61 69 64 20 69  esigned to aid i
10170 6e 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61  n process initia
10180 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20  lization and.** 
10190 73 68 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62 65  shutdown on embe
101a0 64 64 65 64 20 73 79 73 74 65 6d 73 2e 20 20 57  dded systems.  W
101b0 6f 72 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c 69  orkstation appli
101c0 63 61 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a 2a  cations using.**
101d0 20 53 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c 79   SQLite normally
101e0 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20   do not need to 
101f0 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 6f 66  invoke either of
10200 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e   these routines.
10210 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f  .**.** A call to
10220 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
10230 69 7a 65 28 29 20 69 73 20 61 6e 20 22 65 66 66  ize() is an "eff
10240 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20  ective" call if 
10250 69 74 20 69 73 0a 2a 2a 20 74 68 65 20 66 69 72  it is.** the fir
10260 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f  st time sqlite3_
10270 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20  initialize() is 
10280 69 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67 20 74  invoked during t
10290 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a  he lifetime of.*
102a0 2a 20 74 68 65 20 70 72 6f 63 65 73 73 2c 20 6f  * the process, o
102b0 72 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66  r if it is the f
102c0 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65  irst time sqlite
102d0 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
102e0 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c  s invoked.** fol
102f0 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f  lowing a call to
10300 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
10310 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e 20  n().  ^(Only an 
10320 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 0a 2a  effective call.*
10330 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e 69  * of sqlite3_ini
10340 74 69 61 6c 69 7a 65 28 29 20 64 6f 65 73 20 61  tialize() does a
10350 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  ny initializatio
10360 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 63 61  n.  All other ca
10370 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d 6c  lls.** are harml
10380 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a  ess no-ops.)^.**
10390 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71  .** A call to sq
103a0 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
103b0 20 69 73 20 61 6e 20 22 65 66 66 65 63 74 69 76   is an "effectiv
103c0 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73  e" call if it is
103d0 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 63 61   the first.** ca
103e0 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68  ll to sqlite3_sh
103f0 75 74 64 6f 77 6e 28 29 20 73 69 6e 63 65 20 74  utdown() since t
10400 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f  he last sqlite3_
10410 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20 20 5e  initialize().  ^
10420 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66 65  (Only.** an effe
10430 63 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 73 71  ctive call to sq
10440 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
10450 20 64 6f 65 73 20 61 6e 79 20 64 65 69 6e 69 74   does any deinit
10460 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41  ialization..** A
10470 6c 6c 20 6f 74 68 65 72 20 76 61 6c 69 64 20 63  ll other valid c
10480 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
10490 73 68 75 74 64 6f 77 6e 28 29 20 61 72 65 20 68  shutdown() are h
104a0 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29  armless no-ops.)
104b0 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ^.**.** The sqli
104c0 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
104d0 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 68   interface is th
104e0 72 65 61 64 73 61 66 65 2c 20 62 75 74 20 73 71  readsafe, but sq
104f0 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
10500 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68 65  .** is not.  The
10510 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
10520 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d 75  n() interface mu
10530 73 74 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65  st only be calle
10540 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e 67  d from a.** sing
10550 6c 65 20 74 68 72 65 61 64 2e 20 20 41 6c 6c 20  le thread.  All 
10560 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63  open [database c
10570 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73 74  onnections] must
10580 20 62 65 20 63 6c 6f 73 65 64 20 61 6e 64 20 61   be closed and a
10590 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c 69  ll.** other SQLi
105a0 74 65 20 72 65 73 6f 75 72 63 65 73 20 6d 75 73  te resources mus
105b0 74 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64  t be deallocated
105c0 20 70 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b 69   prior to invoki
105d0 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 68  ng.** sqlite3_sh
105e0 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20  utdown()..**.** 
105f0 41 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68 69 6e  Among other thin
10600 67 73 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e 69  gs, ^sqlite3_ini
10610 74 69 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20 69  tialize() will i
10620 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33  nvoke.** sqlite3
10630 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d  _os_init().  Sim
10640 69 6c 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65 33  ilarly, ^sqlite3
10650 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 77  _shutdown().** w
10660 69 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74  ill invoke sqlit
10670 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a  e3_os_end()..**.
10680 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
10690 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75  initialize() rou
106a0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51  tine returns [SQ
106b0 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63  LITE_OK] on succ
106c0 65 73 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72 20  ess..** ^If for 
106d0 73 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71 6c  some reason, sql
106e0 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
106f0 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 69  ) is unable to i
10700 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68 65  nitialize.** the
10710 20 6c 69 62 72 61 72 79 20 28 70 65 72 68 61 70   library (perhap
10720 73 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74  s it is unable t
10730 6f 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65 65  o allocate a nee
10740 64 65 64 20 72 65 73 6f 75 72 63 65 20 73 75 63  ded resource suc
10750 68 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65 78 29  h.** as a mutex)
10760 20 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20 5b   it returns an [
10770 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68 65  error code] othe
10780 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f  r than [SQLITE_O
10790 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  K]..**.** ^The s
107a0 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
107b0 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63  e() routine is c
107c0 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79  alled internally
107d0 20 62 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a   by many other.*
107e0 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  * SQLite interfa
107f0 63 65 73 20 73 6f 20 74 68 61 74 20 61 6e 20 61  ces so that an a
10800 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 75 61 6c  pplication usual
10810 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64  ly does not need
10820 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71   to.** invoke sq
10830 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
10840 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 46 6f  () directly.  Fo
10850 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c 69  r example, [sqli
10860 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63  te3_open()].** c
10870 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e 69  alls sqlite3_ini
10880 74 69 61 6c 69 7a 65 28 29 20 73 6f 20 74 68 65  tialize() so the
10890 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20   SQLite library 
108a0 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69  will be automati
108b0 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61 6c  cally.** initial
108c0 69 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74  ized when [sqlit
108d0 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63 61  e3_open()] is ca
108e0 6c 6c 65 64 20 69 66 20 69 74 20 68 61 73 20 6e  lled if it has n
108f0 6f 74 20 62 65 20 69 6e 69 74 69 61 6c 69 7a 65  ot be initialize
10900 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20 5e  d.** already.  ^
10910 48 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c 69  However, if SQLi
10920 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
10930 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ith the [SQLITE_
10940 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a  OMIT_AUTOINIT].*
10950 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  * compile-time o
10960 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20  ption, then the 
10970 61 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73 20  automatic calls 
10980 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  to sqlite3_initi
10990 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20 6f  alize().** are o
109a0 6d 69 74 74 65 64 20 61 6e 64 20 74 68 65 20 61  mitted and the a
109b0 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
109c0 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e 69  call sqlite3_ini
109d0 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74  tialize() direct
109e0 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 75  ly.** prior to u
109f0 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53  sing any other S
10a00 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e  QLite interface.
10a10 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70 6f    For maximum po
10a20 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69 74  rtability,.** it
10a30 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
10a40 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e  that application
10a50 73 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65 20  s always invoke 
10a60 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
10a70 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c 79  ze().** directly
10a80 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20   prior to using 
10a90 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65  any other SQLite
10aa0 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46 75 74   interface.  Fut
10ab0 75 72 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a 20  ure releases.** 
10ac0 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 72 65  of SQLite may re
10ad0 71 75 69 72 65 20 74 68 69 73 2e 20 20 49 6e 20  quire this.  In 
10ae0 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65  other words, the
10af0 20 62 65 68 61 76 69 6f 72 20 65 78 68 69 62 69   behavior exhibi
10b00 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69  ted.** when SQLi
10b10 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
10b20 69 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54  ith [SQLITE_OMIT
10b30 5f 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68 74  _AUTOINIT] might
10b40 20 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 64   become the.** d
10b50 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20  efault behavior 
10b60 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72  in some future r
10b70 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65  elease of SQLite
10b80 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
10b90 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72 6f  te3_os_init() ro
10ba0 75 74 69 6e 65 20 64 6f 65 73 20 6f 70 65 72 61  utine does opera
10bb0 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63  ting-system spec
10bc0 69 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c 69  ific.** initiali
10bd0 7a 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 53 51  zation of the SQ
10be0 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 54  Lite library.  T
10bf0 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  he sqlite3_os_en
10c00 64 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75  d().** routine u
10c10 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65 63 74  ndoes the effect
10c20 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69   of sqlite3_os_i
10c30 6e 69 74 28 29 2e 20 20 54 79 70 69 63 61 6c 20  nit().  Typical 
10c40 74 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 6d  tasks.** perform
10c50 65 64 20 62 79 20 74 68 65 73 65 20 72 6f 75 74  ed by these rout
10c60 69 6e 65 73 20 69 6e 63 6c 75 64 65 20 61 6c 6c  ines include all
10c70 6f 63 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c 6c  ocation or deall
10c80 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74  ocation.** of st
10c90 61 74 69 63 20 72 65 73 6f 75 72 63 65 73 2c 20  atic resources, 
10ca0 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f  initialization o
10cb0 66 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c  f global variabl
10cc0 65 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20 75  es,.** setting u
10cd0 70 20 61 20 64 65 66 61 75 6c 74 20 5b 73 71 6c  p a default [sql
10ce0 69 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c 65  ite3_vfs] module
10cf0 2c 20 6f 72 20 73 65 74 74 69 6e 67 20 75 70 0a  , or setting up.
10d00 2a 2a 20 61 20 64 65 66 61 75 6c 74 20 63 6f 6e  ** a default con
10d10 66 69 67 75 72 61 74 69 6f 6e 20 75 73 69 6e 67  figuration using
10d20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
10d30 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61  ()]..**.** The a
10d40 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
10d50 64 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 65  d never invoke e
10d60 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f 6f 73  ither sqlite3_os
10d70 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73 71  _init().** or sq
10d80 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 64  lite3_os_end() d
10d90 69 72 65 63 74 6c 79 2e 20 20 54 68 65 20 61 70  irectly.  The ap
10da0 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
10db0 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20   only invoke.** 
10dc0 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
10dd0 7a 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  ze() and sqlite3
10de0 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 54 68  _shutdown().  Th
10df0 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  e sqlite3_os_ini
10e00 74 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  t().** interface
10e10 20 69 73 20 63 61 6c 6c 65 64 20 61 75 74 6f 6d   is called autom
10e20 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69  atically by sqli
10e30 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
10e40 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   and.** sqlite3_
10e50 6f 73 5f 65 6e 64 28 29 20 69 73 20 63 61 6c 6c  os_end() is call
10e60 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73 68  ed by sqlite3_sh
10e70 75 74 64 6f 77 6e 28 29 2e 20 20 41 70 70 72 6f  utdown().  Appro
10e80 70 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d  priate.** implem
10e90 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 73 71  entations for sq
10ea0 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20  lite3_os_init() 
10eb0 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  and sqlite3_os_e
10ec0 6e 64 28 29 0a 2a 2a 20 61 72 65 20 62 75 69 6c  nd().** are buil
10ed0 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 77 68  t into SQLite wh
10ee0 65 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c 65  en it is compile
10ef0 64 20 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e 64  d for Unix, Wind
10f00 6f 77 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a 2a  ows, or OS/2..**
10f10 20 57 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62 75   When [custom bu
10f20 69 6c 64 73 20 7c 20 62 75 69 6c 74 20 66 6f 72  ilds | built for
10f30 20 6f 74 68 65 72 20 70 6c 61 74 66 6f 72 6d 73   other platforms
10f40 5d 0a 2a 2a 20 28 75 73 69 6e 67 20 74 68 65 20  ].** (using the 
10f50 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45 52  [SQLITE_OS_OTHER
10f60 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  =1] compile-time
10f70 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65 20  .** option) the 
10f80 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
10f90 20 73 75 70 70 6c 79 20 61 20 73 75 69 74 61 62   supply a suitab
10fa0 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
10fb0 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  n for.** sqlite3
10fc0 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73  _os_init() and s
10fd0 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e  qlite3_os_end().
10fe0 20 20 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e    An application
10ff0 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d 70  -supplied.** imp
11000 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73  lementation of s
11010 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
11020 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65   or sqlite3_os_e
11030 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65 74  nd().** must ret
11040 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  urn [SQLITE_OK] 
11050 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20 73  on success and s
11060 6f 6d 65 20 6f 74 68 65 72 20 5b 65 72 72 6f 72  ome other [error
11070 20 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66   code] upon.** f
11080 61 69 6c 75 72 65 2e 0a 2a 2f 0a 53 51 4c 49 54  ailure..*/.SQLIT
11090 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
110a0 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 76 6f 69  3_initialize(voi
110b0 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  d);.SQLITE_API i
110c0 6e 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  nt sqlite3_shutd
110d0 6f 77 6e 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54  own(void);.SQLIT
110e0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
110f0 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b  3_os_init(void);
11100 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
11110 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 76  sqlite3_os_end(v
11120 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  oid);../*.** CAP
11130 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 69  I3REF: Configuri
11140 6e 67 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69  ng The SQLite Li
11150 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65 20  brary.**.** The 
11160 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
11170 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73   interface is us
11180 65 64 20 74 6f 20 6d 61 6b 65 20 67 6c 6f 62 61  ed to make globa
11190 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a  l configuration.
111a0 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 53 51  ** changes to SQ
111b0 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f  Lite in order to
111c0 20 74 75 6e 65 20 53 51 4c 69 74 65 20 74 6f 20   tune SQLite to 
111d0 74 68 65 20 73 70 65 63 69 66 69 63 20 6e 65 65  the specific nee
111e0 64 73 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70  ds of.** the app
111f0 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68 65 20 64  lication.  The d
11200 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61  efault configura
11210 74 69 6f 6e 20 69 73 20 72 65 63 6f 6d 6d 65 6e  tion is recommen
11220 64 65 64 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20  ded for most.** 
11230 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6e 64  applications and
11240 20 73 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65   so this routine
11250 20 69 73 20 75 73 75 61 6c 6c 79 20 6e 6f 74 20   is usually not 
11260 6e 65 63 65 73 73 61 72 79 2e 20 20 49 74 20 69  necessary.  It i
11270 73 0a 2a 2a 20 70 72 6f 76 69 64 65 64 20 74 6f  s.** provided to
11280 20 73 75 70 70 6f 72 74 20 72 61 72 65 20 61 70   support rare ap
11290 70 6c 69 63 61 74 69 6f 6e 73 20 77 69 74 68 20  plications with 
112a0 75 6e 75 73 75 61 6c 20 6e 65 65 64 73 2e 0a 2a  unusual needs..*
112b0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
112c0 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66  _config() interf
112d0 61 63 65 20 69 73 20 6e 6f 74 20 74 68 72 65 61  ace is not threa
112e0 64 73 61 66 65 2e 20 20 54 68 65 20 61 70 70 6c  dsafe.  The appl
112f0 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20  ication.** must 
11300 69 6e 73 75 72 65 20 74 68 61 74 20 6e 6f 20 6f  insure that no o
11310 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65  ther SQLite inte
11320 72 66 61 63 65 73 20 61 72 65 20 69 6e 76 6f 6b  rfaces are invok
11330 65 64 20 62 79 20 6f 74 68 65 72 0a 2a 2a 20 74  ed by other.** t
11340 68 72 65 61 64 73 20 77 68 69 6c 65 20 73 71 6c  hreads while sql
11350 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73  ite3_config() is
11360 20 72 75 6e 6e 69 6e 67 2e 20 20 46 75 72 74 68   running.  Furth
11370 65 72 6d 6f 72 65 2c 20 73 71 6c 69 74 65 33 5f  ermore, sqlite3_
11380 63 6f 6e 66 69 67 28 29 0a 2a 2a 20 6d 61 79 20  config().** may 
11390 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64 20  only be invoked 
113a0 70 72 69 6f 72 20 74 6f 20 6c 69 62 72 61 72 79  prior to library
113b0 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
113c0 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
113d0 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20  3_initialize()] 
113e0 6f 72 20 61 66 74 65 72 20 73 68 75 74 64 6f 77  or after shutdow
113f0 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 68  n by [sqlite3_sh
11400 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49  utdown()]..** ^I
11410 66 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  f sqlite3_config
11420 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 66 74  () is called aft
11430 65 72 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74  er [sqlite3_init
11440 69 61 6c 69 7a 65 28 29 5d 20 61 6e 64 20 62 65  ialize()] and be
11450 66 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  fore.** [sqlite3
11460 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 74 68 65  _shutdown()] the
11470 6e 20 69 74 20 77 69 6c 6c 20 72 65 74 75 72 6e  n it will return
11480 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a   SQLITE_MISUSE..
11490 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72  ** Note, however
114a0 2c 20 74 68 61 74 20 5e 73 71 6c 69 74 65 33 5f  , that ^sqlite3_
114b0 63 6f 6e 66 69 67 28 29 20 63 61 6e 20 62 65 20  config() can be 
114c0 63 61 6c 6c 65 64 20 61 73 20 70 61 72 74 20 6f  called as part o
114d0 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65  f the.** impleme
114e0 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70  ntation of an ap
114f0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
11500 64 20 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  d [sqlite3_os_in
11510 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  it()]..**.** The
11520 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
11530 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  to sqlite3_confi
11540 67 28 29 20 69 73 20 61 6e 20 69 6e 74 65 67 65  g() is an intege
11550 72 0a 2a 2a 20 5b 63 6f 6e 66 69 67 75 72 61 74  r.** [configurat
11560 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74 68 61 74  ion option] that
11570 20 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 77   determines.** w
11580 68 61 74 20 70 72 6f 70 65 72 74 79 20 6f 66 20  hat property of 
11590 53 51 4c 69 74 65 20 69 73 20 74 6f 20 62 65 20  SQLite is to be 
115a0 63 6f 6e 66 69 67 75 72 65 64 2e 20 20 53 75 62  configured.  Sub
115b0 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74  sequent argument
115c0 73 0a 2a 2a 20 76 61 72 79 20 64 65 70 65 6e 64  s.** vary depend
115d0 69 6e 67 20 6f 6e 20 74 68 65 20 5b 63 6f 6e 66  ing on the [conf
115e0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
115f0 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73  ].** in the firs
11600 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  t argument..**.*
11610 2a 20 5e 57 68 65 6e 20 61 20 63 6f 6e 66 69 67  * ^When a config
11620 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69  uration option i
11630 73 20 73 65 74 2c 20 73 71 6c 69 74 65 33 5f 63  s set, sqlite3_c
11640 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e 73 20  onfig() returns 
11650 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20  [SQLITE_OK]..** 
11660 5e 49 66 20 74 68 65 20 6f 70 74 69 6f 6e 20 69  ^If the option i
11670 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c  s unknown or SQL
11680 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f  ite is unable to
11690 20 73 65 74 20 74 68 65 20 6f 70 74 69 6f 6e 0a   set the option.
116a0 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75  ** then this rou
116b0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 6e  tine returns a n
116c0 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63  on-zero [error c
116d0 6f 64 65 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  ode]..*/.SQLITE_
116e0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
116f0 63 6f 6e 66 69 67 28 69 6e 74 2c 20 2e 2e 2e 29  config(int, ...)
11700 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
11710 46 3a 20 43 6f 6e 66 69 67 75 72 65 20 64 61 74  F: Configure dat
11720 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
11730 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  s.**.** The sqli
11740 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20  te3_db_config() 
11750 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65  interface is use
11760 64 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 69 67  d to make config
11770 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67  uration.** chang
11780 65 73 20 74 6f 20 61 20 5b 64 61 74 61 62 61 73  es to a [databas
11790 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20  e connection].  
117a0 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 69 73  The interface is
117b0 20 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b   similar to.** [
117c0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
117d0 5d 20 65 78 63 65 70 74 20 74 68 61 74 20 74 68  ] except that th
117e0 65 20 63 68 61 6e 67 65 73 20 61 70 70 6c 79 20  e changes apply 
117f0 74 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b  to a single.** [
11800 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
11810 69 6f 6e 5d 20 28 73 70 65 63 69 66 69 65 64 20  ion] (specified 
11820 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67  in the first arg
11830 75 6d 65 6e 74 29 2e 0a 2a 2a 0a 2a 2a 20 54 68  ument)..**.** Th
11840 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
11850 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f  t to sqlite3_db_
11860 63 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e 29 20  config(D,V,...) 
11870 20 69 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49   is the.** [SQLI
11880 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
11890 41 53 49 44 45 20 7c 20 63 6f 6e 66 69 67 75 72  ASIDE | configur
118a0 61 74 69 6f 6e 20 76 65 72 62 5d 20 2d 20 61 6e  ation verb] - an
118b0 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 0a 2a   integer code .*
118c0 2a 20 74 68 61 74 20 69 6e 64 69 63 61 74 65 73  * that indicates
118d0 20 77 68 61 74 20 61 73 70 65 63 74 20 6f 66 20   what aspect of 
118e0 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
118f0 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 69  nnection] is bei
11900 6e 67 20 63 6f 6e 66 69 67 75 72 65 64 2e 0a 2a  ng configured..*
11910 2a 20 53 75 62 73 65 71 75 65 6e 74 20 61 72 67  * Subsequent arg
11920 75 6d 65 6e 74 73 20 76 61 72 79 20 64 65 70 65  uments vary depe
11930 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f 6e  nding on the con
11940 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62 2e  figuration verb.
11950 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f  .**.** ^Calls to
11960 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66   sqlite3_db_conf
11970 69 67 28 29 20 72 65 74 75 72 6e 20 53 51 4c 49  ig() return SQLI
11980 54 45 5f 4f 4b 20 69 66 20 61 6e 64 20 6f 6e 6c  TE_OK if and onl
11990 79 20 69 66 0a 2a 2a 20 74 68 65 20 63 61 6c 6c  y if.** the call
119a0 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 73   is considered s
119b0 75 63 63 65 73 73 66 75 6c 2e 0a 2a 2f 0a 53 51  uccessful..*/.SQ
119c0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
119d0 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 73  ite3_db_config(s
119e0 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c  qlite3*, int op,
119f0 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   ...);../*.** CA
11a00 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41  PI3REF: Memory A
11a10 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e  llocation Routin
11a20 65 73 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74  es.**.** An inst
11a30 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
11a40 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20  ect defines the 
11a50 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65  interface betwee
11a60 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20  n SQLite.** and 
11a70 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79  low-level memory
11a80 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74   allocation rout
11a90 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  ines..**.** This
11aa0 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 20   object is used 
11ab0 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63  in only one plac
11ac0 65 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20  e in the SQLite 
11ad0 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20  interface..** A 
11ae0 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
11af0 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f  stance of this o
11b00 62 6a 65 63 74 20 69 73 20 74 68 65 20 61 72 67  bject is the arg
11b10 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c  ument to.** [sql
11b20 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
11b30 68 65 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72  hen the configur
11b40 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a  ation option is.
11b50 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ** [SQLITE_CONFI
11b60 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51  G_MALLOC] or [SQ
11b70 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
11b80 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79 20  ALLOC].  .** By 
11b90 63 72 65 61 74 69 6e 67 20 61 6e 20 69 6e 73 74  creating an inst
11ba0 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
11bb0 65 63 74 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69  ect.** and passi
11bc0 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65  ng it to [sqlite
11bd0 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54  3_config]([SQLIT
11be0 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d  E_CONFIG_MALLOC]
11bf0 29 0a 2a 2a 20 64 75 72 69 6e 67 20 63 6f 6e 66  ).** during conf
11c00 69 67 75 72 61 74 69 6f 6e 2c 20 61 6e 20 61 70  iguration, an ap
11c10 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 73 70  plication can sp
11c20 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61  ecify an alterna
11c30 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  tive.** memory a
11c40 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73  llocation subsys
11c50 74 65 6d 20 66 6f 72 20 53 51 4c 69 74 65 20 74  tem for SQLite t
11c60 6f 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66  o use for all of
11c70 20 69 74 73 0a 2a 2a 20 64 79 6e 61 6d 69 63 20   its.** dynamic 
11c80 6d 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a  memory needs..**
11c90 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51  .** Note that SQ
11ca0 4c 69 74 65 20 63 6f 6d 65 73 20 77 69 74 68 20  Lite comes with 
11cb0 73 65 76 65 72 61 6c 20 5b 62 75 69 6c 74 2d 69  several [built-i
11cc0 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  n memory allocat
11cd0 6f 72 73 5d 0a 2a 2a 20 74 68 61 74 20 61 72 65  ors].** that are
11ce0 20 70 65 72 66 65 63 74 6c 79 20 61 64 65 71 75   perfectly adequ
11cf0 61 74 65 20 66 6f 72 20 74 68 65 20 6f 76 65 72  ate for the over
11d00 77 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74  whelming majorit
11d10 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e  y of application
11d20 73 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 74 68  s.** and that th
11d30 69 73 20 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c  is object is onl
11d40 79 20 75 73 65 66 75 6c 20 74 6f 20 61 20 74 69  y useful to a ti
11d50 6e 79 20 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61  ny minority of a
11d60 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77  pplications.** w
11d70 69 74 68 20 73 70 65 63 69 61 6c 69 7a 65 64 20  ith specialized 
11d80 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
11d90 6e 20 72 65 71 75 69 72 65 6d 65 6e 74 73 2e 20  n requirements. 
11da0 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 0a   This object is.
11db0 2a 2a 20 61 6c 73 6f 20 75 73 65 64 20 64 75 72  ** also used dur
11dc0 69 6e 67 20 74 65 73 74 69 6e 67 20 6f 66 20 53  ing testing of S
11dd0 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74  QLite in order t
11de0 6f 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74  o specify an alt
11df0 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f  ernative.** memo
11e00 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61  ry allocator tha
11e10 74 20 73 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f  t simulates memo
11e20 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79  ry out-of-memory
11e30 20 63 6f 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a   conditions in.*
11e40 2a 20 6f 72 64 65 72 20 74 6f 20 76 65 72 69 66  * order to verif
11e50 79 20 74 68 61 74 20 53 51 4c 69 74 65 20 72 65  y that SQLite re
11e60 63 6f 76 65 72 73 20 67 72 61 63 65 66 75 6c 6c  covers gracefull
11e70 79 20 66 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63  y from such.** c
11e80 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  onditions..**.**
11e90 20 54 68 65 20 78 4d 61 6c 6c 6f 63 2c 20 78 52   The xMalloc, xR
11ea0 65 61 6c 6c 6f 63 2c 20 61 6e 64 20 78 46 72 65  ealloc, and xFre
11eb0 65 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 77  e methods must w
11ec0 6f 72 6b 20 6c 69 6b 65 20 74 68 65 0a 2a 2a 20  ork like the.** 
11ed0 6d 61 6c 6c 6f 63 28 29 2c 20 72 65 61 6c 6c 6f  malloc(), reallo
11ee0 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 66  c() and free() f
11ef0 75 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68  unctions from th
11f00 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62  e standard C lib
11f10 72 61 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  rary..** ^SQLite
11f20 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74   guarantees that
11f30 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
11f40 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78 52 65 61 6c  ment to.** xReal
11f50 6c 6f 63 20 69 73 20 61 6c 77 61 79 73 20 61 20  loc is always a 
11f60 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
11f70 79 20 61 20 70 72 69 6f 72 20 63 61 6c 6c 20 74  y a prior call t
11f80 6f 20 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a 0a 2a  o xRoundup..**.*
11f90 2a 20 78 53 69 7a 65 20 73 68 6f 75 6c 64 20 72  * xSize should r
11fa0 65 74 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61  eturn the alloca
11fb0 74 65 64 20 73 69 7a 65 20 6f 66 20 61 20 6d 65  ted size of a me
11fc0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a  mory allocation.
11fd0 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62  ** previously ob
11fe0 74 61 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c  tained from xMal
11ff0 6c 6f 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e  loc or xRealloc.
12000 20 20 54 68 65 20 61 6c 6c 6f 63 61 74 65 64 20    The allocated 
12010 73 69 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79  size.** is alway
12020 73 20 61 74 20 6c 65 61 73 74 20 61 73 20 62 69  s at least as bi
12030 67 20 61 73 20 74 68 65 20 72 65 71 75 65 73 74  g as the request
12040 65 64 20 73 69 7a 65 20 62 75 74 20 6d 61 79 20  ed size but may 
12050 62 65 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a  be larger..**.**
12060 20 54 68 65 20 78 52 6f 75 6e 64 75 70 20 6d 65   The xRoundup me
12070 74 68 6f 64 20 72 65 74 75 72 6e 73 20 77 68 61  thod returns wha
12080 74 20 77 6f 75 6c 64 20 62 65 20 74 68 65 20 61  t would be the a
12090 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66  llocated size of
120a0 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c  .** a memory all
120b0 6f 63 61 74 69 6f 6e 20 67 69 76 65 6e 20 61 20  ocation given a 
120c0 70 61 72 74 69 63 75 6c 61 72 20 72 65 71 75 65  particular reque
120d0 73 74 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74  sted size.  Most
120e0 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63   memory.** alloc
120f0 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 6d  ators round up m
12100 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
12110 73 20 61 74 20 6c 65 61 73 74 20 74 6f 20 74 68  s at least to th
12120 65 20 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a  e next multiple.
12130 2a 2a 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61  ** of 8.  Some a
12140 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20  llocators round 
12150 75 70 20 74 6f 20 61 20 6c 61 72 67 65 72 20 6d  up to a larger m
12160 75 6c 74 69 70 6c 65 20 6f 72 20 74 6f 20 61 20  ultiple or to a 
12170 70 6f 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 45  power of 2..** E
12180 76 65 72 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  very memory allo
12190 63 61 74 69 6f 6e 20 72 65 71 75 65 73 74 20 63  cation request c
121a0 6f 6d 69 6e 67 20 69 6e 20 74 68 72 6f 75 67 68  oming in through
121b0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
121c0 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74  ()].** or [sqlit
121d0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 66 69  e3_realloc()] fi
121e0 72 73 74 20 63 61 6c 6c 73 20 78 52 6f 75 6e 64  rst calls xRound
121f0 75 70 2e 20 20 49 66 20 78 52 6f 75 6e 64 75 70  up.  If xRoundup
12200 20 72 65 74 75 72 6e 73 20 30 2c 20 0a 2a 2a 20   returns 0, .** 
12210 74 68 61 74 20 63 61 75 73 65 73 20 74 68 65 20  that causes the 
12220 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6d 65  corresponding me
12230 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
12240 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54  to fail..**.** T
12250 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20  he xInit method 
12260 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 20  initializes the 
12270 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
12280 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a  .  For example,.
12290 2a 2a 20 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f  ** it might allo
122a0 63 61 74 65 20 61 6e 79 20 72 65 71 75 69 72 65  cate any require
122b0 20 6d 75 74 65 78 65 73 20 6f 72 20 69 6e 69 74   mutexes or init
122c0 69 61 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20  ialize internal 
122d0 64 61 74 61 0a 2a 2a 20 73 74 72 75 63 74 75 72  data.** structur
122e0 65 73 2e 20 20 54 68 65 20 78 53 68 75 74 64 6f  es.  The xShutdo
122f0 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76  wn method is inv
12300 6f 6b 65 64 20 28 69 6e 64 69 72 65 63 74 6c 79  oked (indirectly
12310 29 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ) by.** [sqlite3
12320 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64  _shutdown()] and
12330 20 73 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61   should dealloca
12340 74 65 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73  te any resources
12350 20 61 63 71 75 69 72 65 64 0a 2a 2a 20 62 79 20   acquired.** by 
12360 78 49 6e 69 74 2e 20 20 54 68 65 20 70 41 70 70  xInit.  The pApp
12370 44 61 74 61 20 70 6f 69 6e 74 65 72 20 69 73 20  Data pointer is 
12380 75 73 65 64 20 61 73 20 74 68 65 20 6f 6e 6c 79  used as the only
12390 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
123a0 20 78 49 6e 69 74 20 61 6e 64 20 78 53 68 75 74   xInit and xShut
123b0 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  down..**.** SQLi
123c0 74 65 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51  te holds the [SQ
123d0 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49  LITE_MUTEX_STATI
123e0 43 5f 4d 41 53 54 45 52 5d 20 6d 75 74 65 78 20  C_MASTER] mutex 
123f0 77 68 65 6e 20 69 74 20 69 6e 76 6f 6b 65 73 0a  when it invokes.
12400 2a 2a 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74  ** the xInit met
12410 68 6f 64 2c 20 73 6f 20 74 68 65 20 78 49 6e 69  hod, so the xIni
12420 74 20 6d 65 74 68 6f 64 20 6e 65 65 64 20 6e 6f  t method need no
12430 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65 2e  t be threadsafe.
12440 20 20 54 68 65 0a 2a 2a 20 78 53 68 75 74 64 6f    The.** xShutdo
12450 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 6f 6e 6c  wn method is onl
12460 79 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 5b 73  y called from [s
12470 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
12480 29 5d 20 73 6f 20 69 74 20 64 6f 65 73 0a 2a 2a  )] so it does.**
12490 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20   not need to be 
124a0 74 68 72 65 61 64 73 61 66 65 20 65 69 74 68 65  threadsafe eithe
124b0 72 2e 20 20 46 6f 72 20 61 6c 6c 20 6f 74 68 65  r.  For all othe
124c0 72 20 6d 65 74 68 6f 64 73 2c 20 53 51 4c 69 74  r methods, SQLit
124d0 65 0a 2a 2a 20 68 6f 6c 64 73 20 74 68 65 20 5b  e.** holds the [
124e0 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41  SQLITE_MUTEX_STA
124f0 54 49 43 5f 4d 45 4d 5d 20 6d 75 74 65 78 20 61  TIC_MEM] mutex a
12500 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 0a 2a 2a  s long as the.**
12510 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
12520 4d 45 4d 53 54 41 54 55 53 5d 20 63 6f 6e 66 69  MEMSTATUS] confi
12530 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
12540 69 73 20 74 75 72 6e 65 64 20 6f 6e 20 28 77 68  is turned on (wh
12550 69 63 68 0a 2a 2a 20 69 74 20 69 73 20 62 79 20  ich.** it is by 
12560 64 65 66 61 75 6c 74 29 20 61 6e 64 20 73 6f 20  default) and so 
12570 74 68 65 20 6d 65 74 68 6f 64 73 20 61 72 65 20  the methods are 
12580 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 73 65  automatically se
12590 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77  rialized..** How
125a0 65 76 65 72 2c 20 69 66 20 5b 53 51 4c 49 54 45  ever, if [SQLITE
125b0 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55  _CONFIG_MEMSTATU
125c0 53 5d 20 69 73 20 64 69 73 61 62 6c 65 64 2c 20  S] is disabled, 
125d0 74 68 65 6e 20 74 68 65 20 6f 74 68 65 72 0a 2a  then the other.*
125e0 2a 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 62  * methods must b
125f0 65 20 74 68 72 65 61 64 73 61 66 65 20 6f 72 20  e threadsafe or 
12600 65 6c 73 65 20 6d 61 6b 65 20 74 68 65 69 72 20  else make their 
12610 6f 77 6e 20 61 72 72 61 6e 67 65 6d 65 6e 74 73  own arrangements
12620 20 66 6f 72 0a 2a 2a 20 73 65 72 69 61 6c 69 7a   for.** serializ
12630 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c  ation..**.** SQL
12640 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 69  ite will never i
12650 6e 76 6f 6b 65 20 78 49 6e 69 74 28 29 20 6d 6f  nvoke xInit() mo
12660 72 65 20 74 68 61 6e 20 6f 6e 63 65 20 77 69 74  re than once wit
12670 68 6f 75 74 20 61 6e 20 69 6e 74 65 72 76 65 6e  hout an interven
12680 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 78  ing.** call to x
12690 53 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74  Shutdown()..*/.t
126a0 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
126b0 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
126c0 73 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  s sqlite3_mem_me
126d0 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71  thods;.struct sq
126e0 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
126f0 73 20 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d  s {.  void *(*xM
12700 61 6c 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20 20  alloc)(int);    
12710 20 20 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61       /* Memory a
12720 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74 69  llocation functi
12730 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78  on */.  void (*x
12740 46 72 65 65 29 28 76 6f 69 64 2a 29 3b 20 20 20  Free)(void*);   
12750 20 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20 61         /* Free a
12760 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f   prior allocatio
12770 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78  n */.  void *(*x
12780 52 65 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69  Realloc)(void*,i
12790 6e 74 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20  nt);  /* Resize 
127a0 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f  an allocation */
127b0 0a 20 20 69 6e 74 20 28 2a 78 53 69 7a 65 29 28  .  int (*xSize)(
127c0 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20  void*);         
127d0 20 20 2f 2a 20 52 65 74 75 72 6e 20 74 68 65 20    /* Return the 
127e0 73 69 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63  size of an alloc
127f0 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28  ation */.  int (
12800 2a 78 52 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b  *xRoundup)(int);
12810 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 6f 75            /* Rou
12820 6e 64 20 75 70 20 72 65 71 75 65 73 74 20 73 69  nd up request si
12830 7a 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e  ze to allocation
12840 20 73 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28   size */.  int (
12850 2a 78 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20  *xInit)(void*); 
12860 20 20 20 20 20 20 20 20 20 20 2f 2a 20 49 6e 69            /* Ini
12870 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f  tialize the memo
12880 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a  ry allocator */.
12890 20 20 76 6f 69 64 20 28 2a 78 53 68 75 74 64 6f    void (*xShutdo
128a0 77 6e 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20  wn)(void*);     
128b0 20 2f 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a 65   /* Deinitialize
128c0 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
128d0 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20  cator */.  void 
128e0 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20 20  *pAppData;      
128f0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 72 67            /* Arg
12900 75 6d 65 6e 74 20 74 6f 20 78 49 6e 69 74 28 29  ument to xInit()
12910 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 28 29   and xShutdown()
12920 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.};../*.** CA
12930 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72  PI3REF: Configur
12940 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a  ation Options.**
12950 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6e 66   KEYWORDS: {conf
12960 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
12970 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  }.**.** These co
12980 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65 20  nstants are the 
12990 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65  available intege
129a0 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  r configuration 
129b0 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20  options that.** 
129c0 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61 73  can be passed as
129d0 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
129e0 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ent to the [sqli
129f0 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e  te3_config()] in
12a00 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e  terface..**.** N
12a10 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ew configuration
12a20 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20   options may be 
12a30 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
12a40 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69  releases of SQLi
12a50 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20  te..** Existing 
12a60 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
12a70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64  tions might be d
12a80 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70  iscontinued.  Ap
12a90 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68  plications.** sh
12aa0 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72  ould check the r
12ab0 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20  eturn code from 
12ac0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
12ad0 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20  )] to make sure 
12ae0 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c  that.** the call
12af0 20 77 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b 73   worked.  The [s
12b00 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
12b10 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20   interface will 
12b20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d  return a.** non-
12b30 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65  zero [error code
12b40 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e  ] if a discontin
12b50 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74  ued or unsupport
12b60 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ed configuration
12b70 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e   option.** is in
12b80 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c  voked..**.** <dl
12b90 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  >.** [[SQLITE_CO
12ba0 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
12bb0 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  D]] <dt>SQLITE_C
12bc0 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
12bd0 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  AD</dt>.** <dd>T
12be0 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75  here are no argu
12bf0 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70  ments to this op
12c00 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74  tion.  ^This opt
12c10 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20  ion sets the.** 
12c20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
12c30 20 74 6f 20 53 69 6e 67 6c 65 2d 74 68 72 65 61   to Single-threa
12c40 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  d.  In other wor
12c50 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a  ds, it disables.
12c60 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20  ** all mutexing 
12c70 61 6e 64 20 70 75 74 73 20 53 51 4c 69 74 65 20  and puts SQLite 
12c80 69 6e 74 6f 20 61 20 6d 6f 64 65 20 77 68 65 72  into a mode wher
12c90 65 20 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65  e it can only be
12ca0 20 75 73 65 64 0a 2a 2a 20 62 79 20 61 20 73 69   used.** by a si
12cb0 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20 20 5e  ngle thread.   ^
12cc0 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
12cd0 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  piled with.** th
12ce0 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
12cf0 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48  SAFE | SQLITE_TH
12d00 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70  READSAFE=0] comp
12d10 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
12d20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f  then.** it is no
12d30 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 63 68  t possible to ch
12d40 61 6e 67 65 20 74 68 65 20 5b 74 68 72 65 61 64  ange the [thread
12d50 69 6e 67 20 6d 6f 64 65 5d 20 66 72 6f 6d 20 69  ing mode] from i
12d60 74 73 20 64 65 66 61 75 6c 74 0a 2a 2a 20 76 61  ts default.** va
12d70 6c 75 65 20 6f 66 20 53 69 6e 67 6c 65 2d 74 68  lue of Single-th
12d80 72 65 61 64 20 61 6e 64 20 73 6f 20 5b 73 71 6c  read and so [sql
12d90 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
12da0 69 6c 6c 20 72 65 74 75 72 6e 20 0a 2a 2a 20 5b  ill return .** [
12db0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66  SQLITE_ERROR] if
12dc0 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65   called with the
12dd0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
12de0 49 4e 47 4c 45 54 48 52 45 41 44 0a 2a 2a 20 63  INGLETHREAD.** c
12df0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
12e00 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ion.</dd>.**.** 
12e10 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
12e20 4d 55 4c 54 49 54 48 52 45 41 44 5d 5d 20 3c 64  MULTITHREAD]] <d
12e30 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
12e40 4d 55 4c 54 49 54 48 52 45 41 44 3c 2f 64 74 3e  MULTITHREAD</dt>
12e50 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72  .** <dd>There ar
12e60 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74  e no arguments t
12e70 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20  o this option.  
12e80 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74  ^This option set
12e90 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64  s the.** [thread
12ea0 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c  ing mode] to Mul
12eb0 74 69 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f  ti-thread.  In o
12ec0 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64  ther words, it d
12ed0 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78  isables.** mutex
12ee0 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62 61 73 65  ing on [database
12ef0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64   connection] and
12f00 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
12f10 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  ment] objects..*
12f20 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
12f30 6e 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65  n is responsible
12f40 20 66 6f 72 20 73 65 72 69 61 6c 69 7a 69 6e 67   for serializing
12f50 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64   access to.** [d
12f60 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
12f70 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72  ons] and [prepar
12f80 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20  ed statements]. 
12f90 20 42 75 74 20 6f 74 68 65 72 20 6d 75 74 65 78   But other mutex
12fa0 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65  es.** are enable
12fb0 64 20 73 6f 20 74 68 61 74 20 53 51 4c 69 74 65  d so that SQLite
12fc0 20 77 69 6c 6c 20 62 65 20 73 61 66 65 20 74 6f   will be safe to
12fd0 20 75 73 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d   use in a multi-
12fe0 74 68 72 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69  threaded.** envi
12ff0 72 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 20  ronment as long 
13000 61 73 20 6e 6f 20 74 77 6f 20 74 68 72 65 61 64  as no two thread
13010 73 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65  s attempt to use
13020 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 61   the same.** [da
13030 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
13040 6e 5d 20 61 74 20 74 68 65 20 73 61 6d 65 20 74  n] at the same t
13050 69 6d 65 2e 20 20 5e 49 66 20 53 51 4c 69 74 65  ime.  ^If SQLite
13060 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
13070 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  h.** the [SQLITE
13080 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51  _THREADSAFE | SQ
13090 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
130a0 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  0] compile-time 
130b0 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69  option then.** i
130c0 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c  t is not possibl
130d0 65 20 74 6f 20 73 65 74 20 74 68 65 20 4d 75 6c  e to set the Mul
130e0 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61  ti-thread [threa
130f0 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a  ding mode] and.*
13100 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
13110 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  g()] will return
13120 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
13130 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74  if called with t
13140 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e  he.** SQLITE_CON
13150 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20  FIG_MULTITHREAD 
13160 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
13170 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  tion.</dd>.**.**
13180 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
13190 5f 53 45 52 49 41 4c 49 5a 45 44 5d 5d 20 3c 64  _SERIALIZED]] <d
131a0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
131b0 53 45 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a  SERIALIZED</dt>.
131c0 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65  ** <dd>There are
131d0 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f   no arguments to
131e0 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e   this option.  ^
131f0 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73  This option sets
13200 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69   the.** [threadi
13210 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 65 72 69  ng mode] to Seri
13220 61 6c 69 7a 65 64 2e 20 49 6e 20 6f 74 68 65 72  alized. In other
13230 20 77 6f 72 64 73 2c 20 74 68 69 73 20 6f 70 74   words, this opt
13240 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61  ion enables.** a
13250 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e 63 6c 75  ll mutexes inclu
13260 64 69 6e 67 20 74 68 65 20 72 65 63 75 72 73 69  ding the recursi
13270 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73 20 6f 6e  ve.** mutexes on
13280 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
13290 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70  ction] and [prep
132a0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
132b0 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 74  objects..** In t
132c0 68 69 73 20 6d 6f 64 65 20 28 77 68 69 63 68 20  his mode (which 
132d0 69 73 20 74 68 65 20 64 65 66 61 75 6c 74 20 77  is the default w
132e0 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f  hen SQLite is co
132f0 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 5b  mpiled with.** [
13300 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
13310 45 3d 31 5d 29 20 74 68 65 20 53 51 4c 69 74 65  E=1]) the SQLite
13320 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 69 74   library will it
13330 73 65 6c 66 20 73 65 72 69 61 6c 69 7a 65 20 61  self serialize a
13340 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 74  ccess.** to [dat
13350 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
13360 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64  s] and [prepared
13370 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f 20   statements] so 
13380 74 68 61 74 20 74 68 65 0a 2a 2a 20 61 70 70 6c  that the.** appl
13390 69 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65 20  ication is free 
133a0 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 20  to use the same 
133b0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
133c0 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a 20  tion] or the.** 
133d0 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73  same [prepared s
133e0 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69 66  tatement] in dif
133f0 66 65 72 65 6e 74 20 74 68 72 65 61 64 73 20 61  ferent threads a
13400 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e  t the same time.
13410 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65 20 69  .** ^If SQLite i
13420 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
13430 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** the [SQLITE_T
13440 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49  HREADSAFE | SQLI
13450 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
13460 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
13470 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20  tion then.** it 
13480 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20  is not possible 
13490 74 6f 20 73 65 74 20 74 68 65 20 53 65 72 69 61  to set the Seria
134a0 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67  lized [threading
134b0 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73   mode] and.** [s
134c0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
134d0 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51   will return [SQ
134e0 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63  LITE_ERROR] if c
134f0 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a  alled with the.*
13500 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  * SQLITE_CONFIG_
13510 53 45 52 49 41 4c 49 5a 45 44 20 63 6f 6e 66 69  SERIALIZED confi
13520 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e  guration option.
13530 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
13540 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
13550 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  OC]] <dt>SQLITE_
13560 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64  CONFIG_MALLOC</d
13570 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69  t>.** <dd> ^(Thi
13580 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  s option takes a
13590 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
135a0 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e   which is a poin
135b0 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73  ter to an.** ins
135c0 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71  tance of the [sq
135d0 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
135e0 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54  s] structure.  T
135f0 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63  he argument spec
13600 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61  ifies.** alterna
13610 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d  tive low-level m
13620 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
13630 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20   routines to be 
13640 75 73 65 64 20 69 6e 20 70 6c 61 63 65 20 6f 66  used in place of
13650 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  .** the memory a
13660 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e  llocation routin
13670 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51  es built into SQ
13680 4c 69 74 65 2e 29 5e 20 5e 53 51 4c 69 74 65 20  Lite.)^ ^SQLite 
13690 6d 61 6b 65 73 0a 2a 2a 20 69 74 73 20 6f 77 6e  makes.** its own
136a0 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66   private copy of
136b0 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
136c0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  the [sqlite3_mem
136d0 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
136e0 75 72 65 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68  ure.** before th
136f0 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  e [sqlite3_confi
13700 67 28 29 5d 20 63 61 6c 6c 20 72 65 74 75 72 6e  g()] call return
13710 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  s.</dd>.**.** [[
13720 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
13730 54 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51  TMALLOC]] <dt>SQ
13740 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
13750 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ALLOC</dt>.** <d
13760 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e  d> ^(This option
13770 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
13780 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
13790 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
137a0 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66  n.** instance of
137b0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65   the [sqlite3_me
137c0 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  m_methods] struc
137d0 74 75 72 65 2e 20 20 54 68 65 20 5b 73 71 6c 69  ture.  The [sqli
137e0 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d  te3_mem_methods]
137f0 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69 73  .** structure is
13800 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65   filled with the
13810 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e   currently defin
13820 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ed memory alloca
13830 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 29 5e  tion routines.)^
13840 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20  .** This option 
13850 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f  can be used to o
13860 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61  verload the defa
13870 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ult memory alloc
13880 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65  ation.** routine
13890 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65 72  s with a wrapper
138a0 20 74 68 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e   that simulation
138b0 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  s memory allocat
138c0 69 6f 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a  ion failure or.*
138d0 2a 20 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20  * tracks memory 
138e0 75 73 61 67 65 2c 20 66 6f 72 20 65 78 61 6d 70  usage, for examp
138f0 6c 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  le. </dd>.**.** 
13900 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
13910 4d 45 4d 53 54 41 54 55 53 5d 5d 20 3c 64 74 3e  MEMSTATUS]] <dt>
13920 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
13930 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20  MSTATUS</dt>.** 
13940 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
13950 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c 65 20 61  n takes single a
13960 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20  rgument of type 
13970 69 6e 74 2c 20 69 6e 74 65 72 70 72 65 74 65 64  int, interpreted
13980 20 61 73 20 61 20 0a 2a 2a 20 62 6f 6f 6c 65 61   as a .** boolea
13990 6e 2c 20 77 68 69 63 68 20 65 6e 61 62 6c 65 73  n, which enables
139a0 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65   or disables the
139b0 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 20 6d   collection of m
139c0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
139d0 20 0a 2a 2a 20 73 74 61 74 69 73 74 69 63 73 2e   .** statistics.
139e0 20 5e 28 57 68 65 6e 20 6d 65 6d 6f 72 79 20 61   ^(When memory a
139f0 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73  llocation statis
13a00 74 69 63 73 20 61 72 65 20 64 69 73 61 62 6c 65  tics are disable
13a10 64 2c 20 74 68 65 20 0a 2a 2a 20 66 6f 6c 6c 6f  d, the .** follo
13a20 77 69 6e 67 20 53 51 4c 69 74 65 20 69 6e 74 65  wing SQLite inte
13a30 72 66 61 63 65 73 20 62 65 63 6f 6d 65 20 6e 6f  rfaces become no
13a40 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a  n-operational:.*
13a50 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c  *   <ul>.**   <l
13a60 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  i> [sqlite3_memo
13a70 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20  ry_used()].**   
13a80 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65  <li> [sqlite3_me
13a90 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29  mory_highwater()
13aa0 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c  ].**   <li> [sql
13ab0 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c  ite3_soft_heap_l
13ac0 69 6d 69 74 36 34 28 29 5d 0a 2a 2a 20 20 20 3c  imit64()].**   <
13ad0 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 74 61  li> [sqlite3_sta
13ae0 74 75 73 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c  tus()].**   </ul
13af0 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 20 61  >)^.** ^Memory a
13b00 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73  llocation statis
13b10 74 69 63 73 20 61 72 65 20 65 6e 61 62 6c 65 64  tics are enabled
13b20 20 62 79 20 64 65 66 61 75 6c 74 20 75 6e 6c 65   by default unle
13b30 73 73 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20  ss SQLite is.** 
13b40 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53  compiled with [S
13b50 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45  QLITE_DEFAULT_ME
13b60 4d 53 54 41 54 55 53 5d 3d 30 20 69 6e 20 77 68  MSTATUS]=0 in wh
13b70 69 63 68 20 63 61 73 65 20 6d 65 6d 6f 72 79 0a  ich case memory.
13b80 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74  ** allocation st
13b90 61 74 69 73 74 69 63 73 20 61 72 65 20 64 69 73  atistics are dis
13ba0 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74  abled by default
13bb0 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ..** </dd>.**.**
13bc0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
13bd0 5f 53 43 52 41 54 43 48 5d 5d 20 3c 64 74 3e 53  _SCRATCH]] <dt>S
13be0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
13bf0 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ATCH</dt>.** <dd
13c00 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73  > ^This option s
13c10 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69  pecifies a stati
13c20 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20  c memory buffer 
13c30 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20  that SQLite can 
13c40 75 73 65 20 66 6f 72 0a 2a 2a 20 73 63 72 61 74  use for.** scrat
13c50 63 68 20 6d 65 6d 6f 72 79 2e 20 20 54 68 65 72  ch memory.  Ther
13c60 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75  e are three argu
13c70 6d 65 6e 74 73 3a 20 20 41 20 70 6f 69 6e 74 65  ments:  A pointe
13c80 72 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61  r an 8-byte.** a
13c90 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20 62 75  ligned memory bu
13ca0 66 66 65 72 20 66 72 6f 6d 20 77 68 69 63 68 20  ffer from which 
13cb0 74 68 65 20 73 63 72 61 74 63 68 20 61 6c 6c 6f  the scratch allo
13cc0 63 61 74 69 6f 6e 73 20 77 69 6c 6c 20 62 65 0a  cations will be.
13cd0 2a 2a 20 64 72 61 77 6e 2c 20 74 68 65 20 73 69  ** drawn, the si
13ce0 7a 65 20 6f 66 20 65 61 63 68 20 73 63 72 61 74  ze of each scrat
13cf0 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 28 73  ch allocation (s
13d00 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6d  z),.** and the m
13d10 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
13d20 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74   scratch allocat
13d30 69 6f 6e 73 20 28 4e 29 2e 20 20 54 68 65 20 73  ions (N).  The s
13d40 7a 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6d 75  z.** argument mu
13d50 73 74 20 62 65 20 61 20 6d 75 6c 74 69 70 6c 65  st be a multiple
13d60 20 6f 66 20 31 36 2e 0a 2a 2a 20 54 68 65 20 66   of 16..** The f
13d70 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75  irst argument mu
13d80 73 74 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20  st be a pointer 
13d90 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 61 6c 69  to an 8-byte ali
13da0 67 6e 65 64 20 62 75 66 66 65 72 0a 2a 2a 20 6f  gned buffer.** o
13db0 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20  f at least sz*N 
13dc0 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e  bytes of memory.
13dd0 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c  .** ^SQLite will
13de0 20 75 73 65 20 6e 6f 20 6d 6f 72 65 20 74 68 61   use no more tha
13df0 6e 20 74 77 6f 20 73 63 72 61 74 63 68 20 62 75  n two scratch bu
13e00 66 66 65 72 73 20 70 65 72 20 74 68 72 65 61 64  ffers per thread
13e10 2e 20 20 53 6f 0a 2a 2a 20 4e 20 73 68 6f 75 6c  .  So.** N shoul
13e20 64 20 62 65 20 73 65 74 20 74 6f 20 74 77 69 63  d be set to twic
13e30 65 20 74 68 65 20 65 78 70 65 63 74 65 64 20 6d  e the expected m
13e40 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
13e50 20 74 68 72 65 61 64 73 2e 0a 2a 2a 20 5e 53 51   threads..** ^SQ
13e60 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20  Lite will never 
13e70 72 65 71 75 69 72 65 20 61 20 73 63 72 61 74 63  require a scratc
13e80 68 20 62 75 66 66 65 72 20 74 68 61 74 20 69 73  h buffer that is
13e90 20 6d 6f 72 65 20 74 68 61 6e 20 36 0a 2a 2a 20   more than 6.** 
13ea0 74 69 6d 65 73 20 74 68 65 20 64 61 74 61 62 61  times the databa
13eb0 73 65 20 70 61 67 65 20 73 69 7a 65 2e 20 5e 49  se page size. ^I
13ec0 66 20 53 51 4c 69 74 65 20 6e 65 65 64 73 20 6e  f SQLite needs n
13ed0 65 65 64 73 20 61 64 64 69 74 69 6f 6e 61 6c 0a  eeds additional.
13ee0 2a 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72  ** scratch memor
13ef0 79 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73  y beyond what is
13f00 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 69   provided by thi
13f10 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  s configuration 
13f20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 0a 2a 2a  option, then .**
13f30 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
13f40 28 29 5d 20 77 69 6c 6c 20 62 65 20 75 73 65 64  ()] will be used
13f50 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6d   to obtain the m
13f60 65 6d 6f 72 79 20 6e 65 65 64 65 64 2e 3c 2f 64  emory needed.</d
13f70 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
13f80 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
13f90 48 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  HE]] <dt>SQLITE_
13fa0 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
13fb0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
13fc0 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69  his option speci
13fd0 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65  fies a static me
13fe0 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68 61 74  mory buffer that
13ff0 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20   SQLite can use 
14000 66 6f 72 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  for.** the datab
14010 61 73 65 20 70 61 67 65 20 63 61 63 68 65 20 77  ase page cache w
14020 69 74 68 20 74 68 65 20 64 65 66 61 75 6c 74 20  ith the default 
14030 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65  page cache imple
14040 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20  mentation.  .** 
14050 54 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69  This configurati
14060 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65  on should not be
14070 20 75 73 65 64 20 69 66 20 61 6e 20 61 70 70 6c   used if an appl
14080 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 20 70  ication-define p
14090 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70  age.** cache imp
140a0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6c  lementation is l
140b0 6f 61 64 65 64 20 75 73 69 6e 67 20 74 68 65 20  oaded using the 
140c0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
140d0 41 43 48 45 32 20 6f 70 74 69 6f 6e 2e 0a 2a 2a  ACHE2 option..**
140e0 20 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65   There are three
140f0 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68   arguments to th
14100 69 73 20 6f 70 74 69 6f 6e 3a 20 41 20 70 6f 69  is option: A poi
14110 6e 74 65 72 20 74 6f 20 38 2d 62 79 74 65 20 61  nter to 8-byte a
14120 6c 69 67 6e 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79  ligned.** memory
14130 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61  , the size of ea
14140 63 68 20 70 61 67 65 20 62 75 66 66 65 72 20 28  ch page buffer (
14150 73 7a 29 2c 20 61 6e 64 20 74 68 65 20 6e 75 6d  sz), and the num
14160 62 65 72 20 6f 66 20 70 61 67 65 73 20 28 4e 29  ber of pages (N)
14170 2e 0a 2a 2a 20 54 68 65 20 73 7a 20 61 72 67 75  ..** The sz argu
14180 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 74  ment should be t
14190 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6c  he size of the l
141a0 61 72 67 65 73 74 20 64 61 74 61 62 61 73 65 20  argest database 
141b0 70 61 67 65 0a 2a 2a 20 28 61 20 70 6f 77 65 72  page.** (a power
141c0 20 6f 66 20 74 77 6f 20 62 65 74 77 65 65 6e 20   of two between 
141d0 35 31 32 20 61 6e 64 20 33 32 37 36 38 29 20 70  512 and 32768) p
141e0 6c 75 73 20 61 20 6c 69 74 74 6c 65 20 65 78 74  lus a little ext
141f0 72 61 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70  ra for each.** p
14200 61 67 65 20 68 65 61 64 65 72 2e 20 20 5e 54 68  age header.  ^Th
14210 65 20 70 61 67 65 20 68 65 61 64 65 72 20 73 69  e page header si
14220 7a 65 20 69 73 20 32 30 20 74 6f 20 34 30 20 62  ze is 20 to 40 b
14230 79 74 65 73 20 64 65 70 65 6e 64 69 6e 67 20 6f  ytes depending o
14240 6e 0a 2a 2a 20 74 68 65 20 68 6f 73 74 20 61 72  n.** the host ar
14250 63 68 69 74 65 63 74 75 72 65 2e 20 20 5e 49 74  chitecture.  ^It
14260 20 69 73 20 68 61 72 6d 6c 65 73 73 2c 20 61 70   is harmless, ap
14270 61 72 74 20 66 72 6f 6d 20 74 68 65 20 77 61 73  art from the was
14280 74 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74  ted memory,.** t
14290 6f 20 6d 61 6b 65 20 73 7a 20 61 20 6c 69 74 74  o make sz a litt
142a0 6c 65 20 74 6f 6f 20 6c 61 72 67 65 2e 20 20 54  le too large.  T
142b0 68 65 20 66 69 72 73 74 0a 2a 2a 20 61 72 67 75  he first.** argu
142c0 6d 65 6e 74 20 73 68 6f 75 6c 64 20 70 6f 69 6e  ment should poin
142d0 74 20 74 6f 20 61 6e 20 61 6c 6c 6f 63 61 74 69  t to an allocati
142e0 6f 6e 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73  on of at least s
142f0 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d  z*N bytes of mem
14300 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ory..** ^SQLite 
14310 77 69 6c 6c 20 75 73 65 20 74 68 65 20 6d 65 6d  will use the mem
14320 6f 72 79 20 70 72 6f 76 69 64 65 64 20 62 79 20  ory provided by 
14330 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
14340 6e 74 20 74 6f 20 73 61 74 69 73 66 79 20 69 74  nt to satisfy it
14350 73 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6e 65 65 64  s.** memory need
14360 73 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20  s for the first 
14370 4e 20 70 61 67 65 73 20 74 68 61 74 20 69 74 20  N pages that it 
14380 61 64 64 73 20 74 6f 20 63 61 63 68 65 2e 20 20  adds to cache.  
14390 5e 49 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  ^If additional.*
143a0 2a 20 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d  * page cache mem
143b0 6f 72 79 20 69 73 20 6e 65 65 64 65 64 20 62 65  ory is needed be
143c0 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f  yond what is pro
143d0 76 69 64 65 64 20 62 79 20 74 68 69 73 20 6f 70  vided by this op
143e0 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20 53 51  tion, then.** SQ
143f0 4c 69 74 65 20 67 6f 65 73 20 74 6f 20 5b 73 71  Lite goes to [sq
14400 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
14410 66 6f 72 20 74 68 65 20 61 64 64 69 74 69 6f 6e  for the addition
14420 61 6c 20 73 74 6f 72 61 67 65 20 73 70 61 63 65  al storage space
14430 2e 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72  ..** The pointer
14440 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
14450 67 75 6d 65 6e 74 20 6d 75 73 74 0a 2a 2a 20 62  gument must.** b
14460 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20  e aligned to an 
14470 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 79 20  8-byte boundary 
14480 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20 62 65  or subsequent be
14490 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65  havior of SQLite
144a0 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 75 6e 64 65  .** will be unde
144b0 66 69 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  fined.</dd>.**.*
144c0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
144d0 47 5f 48 45 41 50 5d 5d 20 3c 64 74 3e 53 51 4c  G_HEAP]] <dt>SQL
144e0 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c  ITE_CONFIG_HEAP<
144f0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
14500 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66  is option specif
14510 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d  ies a static mem
14520 6f 72 79 20 62 75 66 66 65 72 20 74 68 61 74 20  ory buffer that 
14530 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a  SQLite will use.
14540 2a 2a 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74  ** for all of it
14550 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79  s dynamic memory
14560 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64   allocation need
14570 73 20 62 65 79 6f 6e 64 20 74 68 6f 73 65 20 70  s beyond those p
14580 72 6f 76 69 64 65 64 0a 2a 2a 20 66 6f 72 20 62  rovided.** for b
14590 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  y [SQLITE_CONFIG
145a0 5f 53 43 52 41 54 43 48 5d 20 61 6e 64 20 5b 53  _SCRATCH] and [S
145b0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47  QLITE_CONFIG_PAG
145c0 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 54 68 65 72  ECACHE]..** Ther
145d0 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75  e are three argu
145e0 6d 65 6e 74 73 3a 20 41 6e 20 38 2d 62 79 74 65  ments: An 8-byte
145f0 20 61 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65 72   aligned pointer
14600 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 0a   to the memory,.
14610 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
14620 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 6d 65   bytes in the me
14630 6d 6f 72 79 20 62 75 66 66 65 72 2c 20 61 6e 64  mory buffer, and
14640 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c   the minimum all
14650 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a  ocation size..**
14660 20 5e 49 66 20 74 68 65 20 66 69 72 73 74 20 70   ^If the first p
14670 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f  ointer (the memo
14680 72 79 20 70 6f 69 6e 74 65 72 29 20 69 73 20 4e  ry pointer) is N
14690 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  ULL, then SQLite
146a0 20 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75   reverts.** to u
146b0 73 69 6e 67 20 69 74 73 20 64 65 66 61 75 6c 74  sing its default
146c0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
146d0 72 20 28 74 68 65 20 73 79 73 74 65 6d 20 6d 61  r (the system ma
146e0 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74  lloc() implement
146f0 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69  ation),.** undoi
14700 6e 67 20 61 6e 79 20 70 72 69 6f 72 20 69 6e 76  ng any prior inv
14710 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49  ocation of [SQLI
14720 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
14730 5d 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 6d  ].  ^If the.** m
14740 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20 69 73  emory pointer is
14750 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 65 69   not NULL and ei
14760 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41  ther [SQLITE_ENA
14770 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20 6f 72 0a  BLE_MEMSYS3] or.
14780 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  ** [SQLITE_ENABL
14790 45 5f 4d 45 4d 53 59 53 35 5d 20 61 72 65 20 64  E_MEMSYS5] are d
147a0 65 66 69 6e 65 64 2c 20 74 68 65 6e 20 74 68 65  efined, then the
147b0 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6d 65 6d   alternative mem
147c0 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72  ory.** allocator
147d0 20 69 73 20 65 6e 67 61 67 65 64 20 74 6f 20 68   is engaged to h
147e0 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53 51 4c  andle all of SQL
147f0 69 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ites memory allo
14800 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a  cation needs..**
14810 20 54 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74   The first point
14820 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70  er (the memory p
14830 6f 69 6e 74 65 72 29 20 6d 75 73 74 20 62 65 20  ointer) must be 
14840 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d  aligned to an 8-
14850 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64 61 72 79  byte.** boundary
14860 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20 62   or subsequent b
14870 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74  ehavior of SQLit
14880 65 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66 69  e will be undefi
14890 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 6d 69 6e 69  ned..** The mini
148a0 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  mum allocation s
148b0 69 7a 65 20 69 73 20 63 61 70 70 65 64 20 61 74  ize is capped at
148c0 20 32 2a 2a 31 32 2e 20 52 65 61 73 6f 6e 61 62   2**12. Reasonab
148d0 6c 65 20 76 61 6c 75 65 73 0a 2a 2a 20 66 6f 72  le values.** for
148e0 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c   the minimum all
148f0 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 61 72 65  ocation size are
14900 20 32 2a 2a 35 20 74 68 72 6f 75 67 68 20 32 2a   2**5 through 2*
14910 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  *8.</dd>.**.** [
14920 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
14930 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  UTEX]] <dt>SQLIT
14940 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 3c 2f  E_CONFIG_MUTEX</
14950 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
14960 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
14970 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
14980 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69  t which is a poi
14990 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e  nter to an.** in
149a0 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73  stance of the [s
149b0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
149c0 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e  hods] structure.
149d0 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73    The argument s
149e0 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65  pecifies.** alte
149f0 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65  rnative low-leve
14a00 6c 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73  l mutex routines
14a10 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70   to be used in p
14a20 6c 61 63 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65  lace.** the mute
14a30 78 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74  x routines built
14a40 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20   into SQLite.)^ 
14a50 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61   ^SQLite makes a
14a60 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20   copy of the.** 
14a70 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b  content of the [
14a80 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
14a90 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
14aa0 20 62 65 66 6f 72 65 20 74 68 65 20 63 61 6c 6c   before the call
14ab0 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
14ac0 63 6f 6e 66 69 67 28 29 5d 20 72 65 74 75 72 6e  config()] return
14ad0 73 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73  s. ^If SQLite is
14ae0 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
14af0 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  * the [SQLITE_TH
14b00 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54  READSAFE | SQLIT
14b10 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
14b20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
14b30 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20  ion then.** the 
14b40 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20  entire mutexing 
14b50 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69  subsystem is omi
14b60 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75  tted from the bu
14b70 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61  ild and hence ca
14b80 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  lls to.** [sqlit
14b90 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74  e3_config()] wit
14ba0 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  h the SQLITE_CON
14bb0 46 49 47 5f 4d 55 54 45 58 20 63 6f 6e 66 69 67  FIG_MUTEX config
14bc0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77  uration option w
14bd0 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53  ill.** return [S
14be0 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64  QLITE_ERROR].</d
14bf0 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
14c00 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45  E_CONFIG_GETMUTE
14c10 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  X]] <dt>SQLITE_C
14c20 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 3c 2f  ONFIG_GETMUTEX</
14c30 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
14c40 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
14c50 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
14c60 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69  t which is a poi
14c70 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e  nter to an.** in
14c80 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73  stance of the [s
14c90 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
14ca0 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e  hods] structure.
14cb0 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65    The.** [sqlite
14cc0 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d  3_mutex_methods]
14cd0 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69 73  .** structure is
14ce0 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65   filled with the
14cf0 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e   currently defin
14d00 65 64 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65  ed mutex routine
14d10 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74  s.)^.** This opt
14d20 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20  ion can be used 
14d30 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20  to overload the 
14d40 64 65 66 61 75 6c 74 20 6d 75 74 65 78 20 61 6c  default mutex al
14d50 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74  location.** rout
14d60 69 6e 65 73 20 77 69 74 68 20 61 20 77 72 61 70  ines with a wrap
14d70 70 65 72 20 75 73 65 64 20 74 6f 20 74 72 61 63  per used to trac
14d80 6b 20 6d 75 74 65 78 20 75 73 61 67 65 20 66 6f  k mutex usage fo
14d90 72 20 70 65 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a  r performance.**
14da0 20 70 72 6f 66 69 6c 69 6e 67 20 6f 72 20 74 65   profiling or te
14db0 73 74 69 6e 67 2c 20 66 6f 72 20 65 78 61 6d 70  sting, for examp
14dc0 6c 65 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65  le.   ^If SQLite
14dd0 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
14de0 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  h.** the [SQLITE
14df0 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51  _THREADSAFE | SQ
14e00 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
14e10 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  0] compile-time 
14e20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74  option then.** t
14e30 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69  he entire mutexi
14e40 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69 73 20  ng subsystem is 
14e50 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65  omitted from the
14e60 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65   build and hence
14e70 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71   calls to.** [sq
14e80 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
14e90 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f  with the SQLITE_
14ea0 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20  CONFIG_GETMUTEX 
14eb0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
14ec0 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74  tion will.** ret
14ed0 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  urn [SQLITE_ERRO
14ee0 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  R].</dd>.**.** [
14ef0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c  [SQLITE_CONFIG_L
14f00 4f 4f 4b 41 53 49 44 45 5d 5d 20 3c 64 74 3e 53  OOKASIDE]] <dt>S
14f10 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f  QLITE_CONFIG_LOO
14f20 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c  KASIDE</dt>.** <
14f30 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f  dd> ^(This optio
14f40 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75  n takes two argu
14f50 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72  ments that deter
14f60 6d 69 6e 65 20 74 68 65 20 64 65 66 61 75 6c 74  mine the default
14f70 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  .** memory alloc
14f80 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 6c 6f  ation for the lo
14f90 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61  okaside memory a
14fa0 6c 6c 6f 63 61 74 6f 72 20 6f 6e 20 65 61 63 68  llocator on each
14fb0 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
14fc0 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20  nnection].  The 
14fd0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69  first argument i
14fe0 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66  s the.** size of
14ff0 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20   each lookaside 
15000 62 75 66 66 65 72 20 73 6c 6f 74 20 61 6e 64 20  buffer slot and 
15010 74 68 65 20 73 65 63 6f 6e 64 20 69 73 20 74 68  the second is th
15020 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73  e number of.** s
15030 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 65 64 20 74  lots allocated t
15040 6f 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20  o each database 
15050 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e 20 20 5e  connection.)^  ^
15060 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74  (This option set
15070 73 20 74 68 65 0a 2a 2a 20 3c 69 3e 64 65 66 61  s the.** <i>defa
15080 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64  ult</i> lookasid
15090 65 20 73 69 7a 65 2e 20 54 68 65 20 5b 53 51 4c  e size. The [SQL
150a0 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
150b0 4b 41 53 49 44 45 5d 0a 2a 2a 20 76 65 72 62 20  KASIDE].** verb 
150c0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63  to [sqlite3_db_c
150d0 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20 62 65 20  onfig()] can be 
150e0 75 73 65 64 20 74 6f 20 63 68 61 6e 67 65 20 74  used to change t
150f0 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20  he lookaside.** 
15100 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 6e  configuration on
15110 20 69 6e 64 69 76 69 64 75 61 6c 20 63 6f 6e 6e   individual conn
15120 65 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64 3e  ections.)^ </dd>
15130 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
15140 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 5d 5d  CONFIG_PCACHE2]]
15150 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
15160 49 47 5f 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a  IG_PCACHE2</dt>.
15170 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f  ** <dd> ^(This o
15180 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
15190 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
151a0 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ich is a pointer
151b0 20 74 6f 0a 2a 2a 20 61 6e 20 5b 73 71 6c 69 74   to.** an [sqlit
151c0 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64  e3_pcache_method
151d0 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 69  s2] object.  Thi
151e0 73 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69  s object specifi
151f0 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
15200 0a 2a 2a 20 74 6f 20 61 20 63 75 73 74 6f 6d 20  .** to a custom 
15210 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65  page cache imple
15220 6d 65 6e 74 61 74 69 6f 6e 2e 29 5e 20 20 5e 53  mentation.)^  ^S
15230 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f  QLite makes a co
15240 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 62 6a  py of the.** obj
15250 65 63 74 20 61 6e 64 20 75 73 65 73 20 69 74 20  ect and uses it 
15260 66 6f 72 20 70 61 67 65 20 63 61 63 68 65 20 6d  for page cache m
15270 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
15280 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  s.</dd>.**.** [[
15290 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
152a0 54 50 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53  TPCACHE2]] <dt>S
152b0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
152c0 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20  PCACHE2</dt>.** 
152d0 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69  <dd> ^(This opti
152e0 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
152f0 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
15300 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
15310 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   an.** [sqlite3_
15320 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d  pcache_methods2]
15330 20 6f 62 6a 65 63 74 2e 20 20 53 51 4c 69 74 65   object.  SQLite
15340 20 63 6f 70 69 65 73 20 6f 66 20 74 68 65 20 63   copies of the c
15350 75 72 72 65 6e 74 0a 2a 2a 20 70 61 67 65 20 63  urrent.** page c
15360 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ache implementat
15370 69 6f 6e 20 69 6e 74 6f 20 74 68 61 74 20 6f 62  ion into that ob
15380 6a 65 63 74 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a  ject.)^ </dd>.**
15390 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
153a0 46 49 47 5f 4c 4f 47 5d 5d 20 3c 64 74 3e 53 51  FIG_LOG]] <dt>SQ
153b0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 3c  LITE_CONFIG_LOG<
153c0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 54 68 65  /dt>.** <dd> The
153d0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c   SQLITE_CONFIG_L
153e0 4f 47 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65  OG option is use
153f0 64 20 74 6f 20 63 6f 6e 66 69 67 75 72 65 20 74  d to configure t
15400 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20 67 6c 6f  he SQLite.** glo
15410 62 61 6c 20 5b 65 72 72 6f 72 20 6c 6f 67 5d 2e  bal [error log].
15420 0a 2a 2a 20 28 5e 54 68 65 20 53 51 4c 49 54 45  .** (^The SQLITE
15430 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69  _CONFIG_LOG opti
15440 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67  on takes two arg
15450 75 6d 65 6e 74 73 3a 20 61 20 70 6f 69 6e 74 65  uments: a pointe
15460 72 20 74 6f 20 61 0a 2a 2a 20 66 75 6e 63 74 69  r to a.** functi
15470 6f 6e 20 77 69 74 68 20 61 20 63 61 6c 6c 20 73  on with a call s
15480 69 67 6e 61 74 75 72 65 20 6f 66 20 76 6f 69 64  ignature of void
15490 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  (*)(void*,int,co
154a0 6e 73 74 20 63 68 61 72 2a 29 2c 20 0a 2a 2a 20  nst char*), .** 
154b0 61 6e 64 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  and a pointer to
154c0 20 76 6f 69 64 2e 20 5e 49 66 20 74 68 65 20 66   void. ^If the f
154d0 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20  unction pointer 
154e0 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 69 74 20  is not NULL, it 
154f0 69 73 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 62 79  is.** invoked by
15500 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d   [sqlite3_log()]
15510 20 74 6f 20 70 72 6f 63 65 73 73 20 65 61 63 68   to process each
15520 20 6c 6f 67 67 69 6e 67 20 65 76 65 6e 74 2e 20   logging event. 
15530 20 5e 49 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63   ^If the.** func
15540 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20  tion pointer is 
15550 4e 55 4c 4c 2c 20 74 68 65 20 5b 73 71 6c 69 74  NULL, the [sqlit
15560 65 33 5f 6c 6f 67 28 29 5d 20 69 6e 74 65 72 66  e3_log()] interf
15570 61 63 65 20 62 65 63 6f 6d 65 73 20 61 20 6e 6f  ace becomes a no
15580 2d 6f 70 2e 0a 2a 2a 20 5e 54 68 65 20 76 6f 69  -op..** ^The voi
15590 64 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69  d pointer that i
155a0 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  s the second arg
155b0 75 6d 65 6e 74 20 74 6f 20 53 51 4c 49 54 45 5f  ument to SQLITE_
155c0 43 4f 4e 46 49 47 5f 4c 4f 47 20 69 73 0a 2a 2a  CONFIG_LOG is.**
155d0 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 20   passed through 
155e0 61 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72  as the first par
155f0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 70  ameter to the ap
15600 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
15610 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63  d logger.** func
15620 74 69 6f 6e 20 77 68 65 6e 65 76 65 72 20 74 68  tion whenever th
15630 61 74 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 69  at function is i
15640 6e 76 6f 6b 65 64 2e 20 20 5e 54 68 65 20 73 65  nvoked.  ^The se
15650 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74  cond parameter t
15660 6f 0a 2a 2a 20 74 68 65 20 6c 6f 67 67 65 72 20  o.** the logger 
15670 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 20 63 6f  function is a co
15680 70 79 20 6f 66 20 74 68 65 20 66 69 72 73 74 20  py of the first 
15690 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
156a0 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a   corresponding.*
156b0 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29  * [sqlite3_log()
156c0 5d 20 63 61 6c 6c 20 61 6e 64 20 69 73 20 69 6e  ] call and is in
156d0 74 65 6e 64 65 64 20 74 6f 20 62 65 20 61 20 5b  tended to be a [
156e0 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20  result code] or 
156f0 61 6e 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  an.** [extended 
15700 72 65 73 75 6c 74 20 63 6f 64 65 5d 2e 20 20 5e  result code].  ^
15710 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  The third parame
15720 74 65 72 20 70 61 73 73 65 64 20 74 6f 20 74 68  ter passed to th
15730 65 20 6c 6f 67 67 65 72 20 69 73 0a 2a 2a 20 6c  e logger is.** l
15740 6f 67 20 6d 65 73 73 61 67 65 20 61 66 74 65 72  og message after
15750 20 66 6f 72 6d 61 74 74 69 6e 67 20 76 69 61 20   formatting via 
15760 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  [sqlite3_snprint
15770 66 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 53 51 4c  f()]..** The SQL
15780 69 74 65 20 6c 6f 67 67 69 6e 67 20 69 6e 74 65  ite logging inte
15790 72 66 61 63 65 20 69 73 20 6e 6f 74 20 72 65 65  rface is not ree
157a0 6e 74 72 61 6e 74 3b 20 74 68 65 20 6c 6f 67 67  ntrant; the logg
157b0 65 72 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73  er function.** s
157c0 75 70 70 6c 69 65 64 20 62 79 20 74 68 65 20 61  upplied by the a
157d0 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
157e0 6e 6f 74 20 69 6e 76 6f 6b 65 20 61 6e 79 20 53  not invoke any S
157f0 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e  QLite interface.
15800 0a 2a 2a 20 49 6e 20 61 20 6d 75 6c 74 69 2d 74  .** In a multi-t
15810 68 72 65 61 64 65 64 20 61 70 70 6c 69 63 61 74  hreaded applicat
15820 69 6f 6e 2c 20 74 68 65 20 61 70 70 6c 69 63 61  ion, the applica
15830 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67  tion-defined log
15840 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ger.** function 
15850 6d 75 73 74 20 62 65 20 74 68 72 65 61 64 73 61  must be threadsa
15860 66 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  fe. </dd>.**.** 
15870 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
15880 55 52 49 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  URI]] <dt>SQLITE
15890 5f 43 4f 4e 46 49 47 5f 55 52 49 0a 2a 2a 20 3c  _CONFIG_URI.** <
158a0 64 64 3e 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e  dd>^(This option
158b0 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
158c0 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65  argument of type
158d0 20 69 6e 74 2e 20 49 66 20 6e 6f 6e 2d 7a 65 72   int. If non-zer
158e0 6f 2c 20 74 68 65 6e 0a 2a 2a 20 55 52 49 20 68  o, then.** URI h
158f0 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61  andling is globa
15900 6c 6c 79 20 65 6e 61 62 6c 65 64 2e 20 49 66 20  lly enabled. If 
15910 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73  the parameter is
15920 20 7a 65 72 6f 2c 20 74 68 65 6e 20 55 52 49 20   zero, then URI 
15930 68 61 6e 64 6c 69 6e 67 0a 2a 2a 20 69 73 20 67  handling.** is g
15940 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c 65 64  lobally disabled
15950 2e 29 5e 20 5e 49 66 20 55 52 49 20 68 61 6e 64  .)^ ^If URI hand
15960 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79  ling is globally
15970 20 65 6e 61 62 6c 65 64 2c 20 61 6c 6c 20 66 69   enabled, all fi
15980 6c 65 6e 61 6d 65 73 0a 2a 2a 20 70 61 73 73 65  lenames.** passe
15990 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70  d to [sqlite3_op
159a0 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  en()], [sqlite3_
159b0 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 5b 73 71 6c  open_v2()], [sql
159c0 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 6f  ite3_open16()] o
159d0 72 0a 2a 2a 20 73 70 65 63 69 66 69 65 64 20 61  r.** specified a
159e0 73 20 70 61 72 74 20 6f 66 20 5b 41 54 54 41 43  s part of [ATTAC
159f0 48 5d 20 63 6f 6d 6d 61 6e 64 73 20 61 72 65 20  H] commands are 
15a00 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55  interpreted as U
15a10 52 49 73 2c 20 72 65 67 61 72 64 6c 65 73 73 0a  RIs, regardless.
15a20 2a 2a 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72  ** of whether or
15a30 20 6e 6f 74 20 74 68 65 20 5b 53 51 4c 49 54 45   not the [SQLITE
15a40 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20  _OPEN_URI] flag 
15a50 69 73 20 73 65 74 20 77 68 65 6e 20 74 68 65 20  is set when the 
15a60 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
15a70 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64  ection is opened
15a80 2e 20 5e 49 66 20 69 74 20 69 73 20 67 6c 6f 62  . ^If it is glob
15a90 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2c 20 66  ally disabled, f
15aa0 69 6c 65 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20  ilenames are.** 
15ab0 6f 6e 6c 79 20 69 6e 74 65 72 70 72 65 74 65 64  only interpreted
15ac0 20 61 73 20 55 52 49 73 20 69 66 20 74 68 65 20   as URIs if the 
15ad0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20  SQLITE_OPEN_URI 
15ae0 66 6c 61 67 20 69 73 20 73 65 74 20 77 68 65 6e  flag is set when
15af0 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
15b00 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f   connection is o
15b10 70 65 6e 65 64 2e 20 5e 28 42 79 20 64 65 66 61  pened. ^(By defa
15b20 75 6c 74 2c 20 55 52 49 20 68 61 6e 64 6c 69 6e  ult, URI handlin
15b30 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a  g is globally.**
15b40 20 64 69 73 61 62 6c 65 64 2e 20 54 68 65 20 64   disabled. The d
15b50 65 66 61 75 6c 74 20 76 61 6c 75 65 20 6d 61 79  efault value may
15b60 20 62 65 20 63 68 61 6e 67 65 64 20 62 79 20 63   be changed by c
15b70 6f 6d 70 69 6c 69 6e 67 20 77 69 74 68 20 74 68  ompiling with th
15b80 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 53 45  e.** [SQLITE_USE
15b90 5f 55 52 49 5d 20 73 79 6d 62 6f 6c 20 64 65 66  _URI] symbol def
15ba0 69 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  ined.)^.**.** [[
15bb0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f  SQLITE_CONFIG_CO
15bc0 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41  VERING_INDEX_SCA
15bd0 4e 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  N]] <dt>SQLITE_C
15be0 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49  ONFIG_COVERING_I
15bf0 4e 44 45 58 5f 53 43 41 4e 0a 2a 2a 20 3c 64 64  NDEX_SCAN.** <dd
15c00 3e 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61  >^This option ta
15c10 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 69 6e 74  kes a single int
15c20 65 67 65 72 20 61 72 67 75 6d 65 6e 74 20 77 68  eger argument wh
15c30 69 63 68 20 69 73 20 69 6e 74 65 72 70 72 65 74  ich is interpret
15c40 65 64 20 61 73 0a 2a 2a 20 61 20 62 6f 6f 6c 65  ed as.** a boole
15c50 61 6e 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 65  an in order to e
15c60 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65  nable or disable
15c70 20 74 68 65 20 75 73 65 20 6f 66 20 63 6f 76 65   the use of cove
15c80 72 69 6e 67 20 69 6e 64 69 63 65 73 20 66 6f 72  ring indices for
15c90 0a 2a 2a 20 66 75 6c 6c 20 74 61 62 6c 65 20 73  .** full table s
15ca0 63 61 6e 73 20 69 6e 20 74 68 65 20 71 75 65 72  cans in the quer
15cb0 79 20 6f 70 74 69 6d 69 7a 65 72 2e 20 20 5e 54  y optimizer.  ^T
15cc0 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 74 69  he default setti
15cd0 6e 67 20 69 73 20 64 65 74 65 72 6d 69 6e 65 64  ng is determined
15ce0 0a 2a 2a 20 62 79 20 74 68 65 20 5b 53 51 4c 49  .** by the [SQLI
15cf0 54 45 5f 41 4c 4c 4f 57 5f 43 4f 56 45 52 49 4e  TE_ALLOW_COVERIN
15d00 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 20 63 6f  G_INDEX_SCAN] co
15d10 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
15d20 6e 2c 20 6f 72 20 69 73 20 22 6f 6e 22 0a 2a 2a  n, or is "on".**
15d30 20 69 66 20 74 68 61 74 20 63 6f 6d 70 69 6c 65   if that compile
15d40 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20  -time option is 
15d50 6f 6d 69 74 74 65 64 2e 0a 2a 2a 20 54 68 65 20  omitted..** The 
15d60 61 62 69 6c 69 74 79 20 74 6f 20 64 69 73 61 62  ability to disab
15d70 6c 65 20 74 68 65 20 75 73 65 20 6f 66 20 63 6f  le the use of co
15d80 76 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20 66  vering indices f
15d90 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 63  or full table sc
15da0 61 6e 73 0a 2a 2a 20 69 73 20 62 65 63 61 75 73  ans.** is becaus
15db0 65 20 73 6f 6d 65 20 69 6e 63 6f 72 72 65 63 74  e some incorrect
15dc0 6c 79 20 63 6f 64 65 64 20 6c 65 67 61 63 79 20  ly coded legacy 
15dd0 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 69 67  applications mig
15de0 68 74 20 6d 61 6c 66 75 6e 63 74 69 6f 6e 0a 2a  ht malfunction.*
15df0 2a 20 77 68 65 6e 20 74 68 65 20 6f 70 74 69 6d  * when the optim
15e00 69 7a 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c  ization is enabl
15e10 65 64 2e 20 20 50 72 6f 76 69 64 69 6e 67 20 74  ed.  Providing t
15e20 68 65 20 61 62 69 6c 69 74 79 20 74 6f 0a 2a 2a  he ability to.**
15e30 20 64 69 73 61 62 6c 65 20 74 68 65 20 6f 70 74   disable the opt
15e40 69 6d 69 7a 61 74 69 6f 6e 20 61 6c 6c 6f 77 73  imization allows
15e50 20 74 68 65 20 6f 6c 64 65 72 2c 20 62 75 67 67   the older, bugg
15e60 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f  y application co
15e70 64 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69  de to work.** wi
15e80 74 68 6f 75 74 20 63 68 61 6e 67 65 20 65 76 65  thout change eve
15e90 6e 20 77 69 74 68 20 6e 65 77 65 72 20 76 65 72  n with newer ver
15ea0 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e  sions of SQLite.
15eb0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
15ec0 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5d 5d 20  CONFIG_PCACHE]] 
15ed0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
15ee0 47 45 54 50 43 41 43 48 45 5d 5d 0a 2a 2a 20 3c  GETPCACHE]].** <
15ef0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
15f00 5f 50 43 41 43 48 45 20 61 6e 64 20 53 51 4c 49  _PCACHE and SQLI
15f10 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41  TE_CONFIG_GETPCA
15f20 43 48 45 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 73  CHE.** <dd> Thes
15f30 65 20 6f 70 74 69 6f 6e 73 20 61 72 65 20 6f 62  e options are ob
15f40 73 6f 6c 65 74 65 20 61 6e 64 20 73 68 6f 75 6c  solete and shoul
15f50 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20 62 79  d not be used by
15f60 20 6e 65 77 20 63 6f 64 65 2e 0a 2a 2a 20 54 68   new code..** Th
15f70 65 79 20 61 72 65 20 72 65 74 61 69 6e 65 64 20  ey are retained 
15f80 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f  for backwards co
15f90 6d 70 61 74 69 62 69 6c 69 74 79 20 62 75 74 20  mpatibility but 
15fa0 61 72 65 20 6e 6f 77 20 6e 6f 2d 6f 70 73 2e 0a  are now no-ops..
15fb0 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  ** </dd>.**.** [
15fc0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
15fd0 51 4c 4c 4f 47 5d 5d 0a 2a 2a 20 3c 64 74 3e 53  QLLOG]].** <dt>S
15fe0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c  QLITE_CONFIG_SQL
15ff0 4c 4f 47 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20  LOG.** <dd>This 
16000 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61  option is only a
16010 76 61 69 6c 61 62 6c 65 20 69 66 20 73 71 6c 69  vailable if sqli
16020 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
16030 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ith the.** [SQLI
16040 54 45 5f 45 4e 41 42 4c 45 5f 53 51 4c 4c 4f 47  TE_ENABLE_SQLLOG
16050 5d 20 70 72 65 2d 70 72 6f 63 65 73 73 6f 72 20  ] pre-processor 
16060 6d 61 63 72 6f 20 64 65 66 69 6e 65 64 2e 20 54  macro defined. T
16070 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
16080 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 62 65 20 61  t should.** be a
16090 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 66 75   pointer to a fu
160a0 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70 65 20 76  nction of type v
160b0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c  oid(*)(void*,sql
160c0 69 74 65 33 2a 2c 63 6f 6e 73 74 20 63 68 61 72  ite3*,const char
160d0 2a 2c 20 69 6e 74 29 2e 0a 2a 2a 20 54 68 65 20  *, int)..** The 
160e0 73 65 63 6f 6e 64 20 73 68 6f 75 6c 64 20 62 65  second should be
160f0 20 6f 66 20 74 79 70 65 20 28 76 6f 69 64 2a 29   of type (void*)
16100 2e 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  . The callback i
16110 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 74 68 65  s invoked by the
16120 20 6c 69 62 72 61 72 79 0a 2a 2a 20 69 6e 20 74   library.** in t
16130 68 72 65 65 20 73 65 70 61 72 61 74 65 20 63 69  hree separate ci
16140 72 63 75 6d 73 74 61 6e 63 65 73 2c 20 69 64 65  rcumstances, ide
16150 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20 76  ntified by the v
16160 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 74  alue passed as t
16170 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61 72  he.** fourth par
16180 61 6d 65 74 65 72 2e 20 49 66 20 74 68 65 20 66  ameter. If the f
16190 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
161a0 69 73 20 30 2c 20 74 68 65 6e 20 74 68 65 20 64  is 0, then the d
161b0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
161c0 6f 6e 0a 2a 2a 20 70 61 73 73 65 64 20 61 73 20  on.** passed as 
161d0 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
161e0 65 6e 74 20 68 61 73 20 6a 75 73 74 20 62 65 65  ent has just bee
161f0 6e 20 6f 70 65 6e 65 64 2e 20 54 68 65 20 74 68  n opened. The th
16200 69 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  ird argument.** 
16210 70 6f 69 6e 74 73 20 74 6f 20 61 20 62 75 66 66  points to a buff
16220 65 72 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  er containing th
16230 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6d 61  e name of the ma
16240 69 6e 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  in database file
16250 2e 20 49 66 20 74 68 65 0a 2a 2a 20 66 6f 75 72  . If the.** four
16260 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
16270 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20  1, then the SQL 
16280 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 74  statement that t
16290 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
162a0 65 72 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20  er.** points to 
162b0 68 61 73 20 6a 75 73 74 20 62 65 65 6e 20 65 78  has just been ex
162c0 65 63 75 74 65 64 2e 20 4f 72 2c 20 69 66 20 74  ecuted. Or, if t
162d0 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
162e0 74 65 72 20 69 73 20 32 2c 20 74 68 65 6e 0a 2a  ter is 2, then.*
162f0 2a 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  * the connection
16300 20 62 65 69 6e 67 20 70 61 73 73 65 64 20 61 73   being passed as
16310 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
16320 6d 65 74 65 72 20 69 73 20 62 65 69 6e 67 20 63  meter is being c
16330 6c 6f 73 65 64 2e 20 54 68 65 0a 2a 2a 20 74 68  losed. The.** th
16340 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ird parameter is
16350 20 70 61 73 73 65 64 20 4e 55 4c 4c 20 49 6e 20   passed NULL In 
16360 74 68 69 73 20 63 61 73 65 2e 20 20 41 6e 20 65  this case.  An e
16370 78 61 6d 70 6c 65 20 6f 66 20 75 73 69 6e 67 20  xample of using 
16380 74 68 69 73 0a 2a 2a 20 63 6f 6e 66 69 67 75 72  this.** configur
16390 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 63 61 6e  ation option can
163a0 20 62 65 20 73 65 65 6e 20 69 6e 20 74 68 65 20   be seen in the 
163b0 22 74 65 73 74 5f 73 71 6c 6c 6f 67 2e 63 22 20  "test_sqllog.c" 
163c0 73 6f 75 72 63 65 20 66 69 6c 65 20 69 6e 0a 2a  source file in.*
163d0 2a 20 74 68 65 20 63 61 6e 6f 6e 69 63 61 6c 20  * the canonical 
163e0 53 51 4c 69 74 65 20 73 6f 75 72 63 65 20 74 72  SQLite source tr
163f0 65 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  ee.</dd>.**.** [
16400 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
16410 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64  MAP_SIZE]].** <d
16420 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
16430 4d 4d 41 50 5f 53 49 5a 45 0a 2a 2a 20 3c 64 64  MMAP_SIZE.** <dd
16440 3e 5e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  >^SQLITE_CONFIG_
16450 4d 4d 41 50 5f 53 49 5a 45 20 74 61 6b 65 73 20  MMAP_SIZE takes 
16460 74 77 6f 20 36 34 2d 62 69 74 20 69 6e 74 65 67  two 64-bit integ
16470 65 72 20 28 73 71 6c 69 74 65 33 5f 69 6e 74 36  er (sqlite3_int6
16480 34 29 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61  4) values.** tha
16490 74 20 61 72 65 20 74 68 65 20 64 65 66 61 75 6c  t are the defaul
164a0 74 20 6d 6d 61 70 20 73 69 7a 65 20 6c 69 6d 69  t mmap size limi
164b0 74 20 28 74 68 65 20 64 65 66 61 75 6c 74 20 73  t (the default s
164c0 65 74 74 69 6e 67 20 66 6f 72 0a 2a 2a 20 5b 50  etting for.** [P
164d0 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d  RAGMA mmap_size]
164e0 29 20 61 6e 64 20 74 68 65 20 6d 61 78 69 6d 75  ) and the maximu
164f0 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73  m allowed mmap s
16500 69 7a 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 54  ize limit..** ^T
16510 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 74 69  he default setti
16520 6e 67 20 63 61 6e 20 62 65 20 6f 76 65 72 72 69  ng can be overri
16530 64 64 65 6e 20 62 79 20 65 61 63 68 20 64 61 74  dden by each dat
16540 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
16550 20 75 73 69 6e 67 0a 2a 2a 20 65 69 74 68 65 72   using.** either
16560 20 74 68 65 20 5b 50 52 41 47 4d 41 20 6d 6d 61   the [PRAGMA mma
16570 70 5f 73 69 7a 65 5d 20 63 6f 6d 6d 61 6e 64 2c  p_size] command,
16580 20 6f 72 20 62 79 20 75 73 69 6e 67 20 74 68 65   or by using the
16590 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  .** [SQLITE_FCNT
165a0 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69 6c  L_MMAP_SIZE] fil
165b0 65 20 63 6f 6e 74 72 6f 6c 2e 20 20 5e 28 54 68  e control.  ^(Th
165c0 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65  e maximum allowe
165d0 64 20 6d 6d 61 70 20 73 69 7a 65 0a 2a 2a 20 63  d mmap size.** c
165e0 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 64  annot be changed
165f0 20 61 74 20 72 75 6e 2d 74 69 6d 65 2e 20 20 4e   at run-time.  N
16600 6f 72 20 6d 61 79 20 74 68 65 20 6d 61 78 69 6d  or may the maxim
16610 75 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20  um allowed mmap 
16620 73 69 7a 65 0a 2a 2a 20 65 78 63 65 65 64 20 74  size.** exceed t
16630 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  he compile-time 
16640 6d 61 78 69 6d 75 6d 20 6d 6d 61 70 20 73 69 7a  maximum mmap siz
16650 65 20 73 65 74 20 62 79 20 74 68 65 0a 2a 2a 20  e set by the.** 
16660 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 4d 4d 41 50  [SQLITE_MAX_MMAP
16670 5f 53 49 5a 45 5d 20 63 6f 6d 70 69 6c 65 2d 74  _SIZE] compile-t
16680 69 6d 65 20 6f 70 74 69 6f 6e 2e 29 5e 0a 2a 2a  ime option.)^.**
16690 20 5e 49 66 20 65 69 74 68 65 72 20 61 72 67 75   ^If either argu
166a0 6d 65 6e 74 20 74 6f 20 74 68 69 73 20 6f 70 74  ment to this opt
166b0 69 6f 6e 20 69 73 20 6e 65 67 61 74 69 76 65 2c  ion is negative,
166c0 20 74 68 65 6e 20 74 68 61 74 20 61 72 67 75 6d   then that argum
166d0 65 6e 74 20 69 73 0a 2a 2a 20 63 68 61 6e 67 65  ent is.** change
166e0 64 20 74 6f 20 69 74 73 20 63 6f 6d 70 69 6c 65  d to its compile
166f0 2d 74 69 6d 65 20 64 65 66 61 75 6c 74 2e 0a 2a  -time default..*
16700 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
16710 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53  NFIG_WIN32_HEAPS
16720 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c  IZE]].** <dt>SQL
16730 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32  ITE_CONFIG_WIN32
16740 5f 48 45 41 50 53 49 5a 45 0a 2a 2a 20 3c 64 64  _HEAPSIZE.** <dd
16750 3e 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73  >^This option is
16760 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20   only available 
16770 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  if SQLite is com
16780 70 69 6c 65 64 20 66 6f 72 20 57 69 6e 64 6f 77  piled for Window
16790 73 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 53  s.** with the [S
167a0 51 4c 49 54 45 5f 57 49 4e 33 32 5f 4d 41 4c 4c  QLITE_WIN32_MALL
167b0 4f 43 5d 20 70 72 65 2d 70 72 6f 63 65 73 73 6f  OC] pre-processo
167c0 72 20 6d 61 63 72 6f 20 64 65 66 69 6e 65 64 2e  r macro defined.
167d0 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  .** SQLITE_CONFI
167e0 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45  G_WIN32_HEAPSIZE
167f0 20 74 61 6b 65 73 20 61 20 33 32 2d 62 69 74 20   takes a 32-bit 
16800 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  unsigned integer
16810 20 76 61 6c 75 65 0a 2a 2a 20 74 68 61 74 20 73   value.** that s
16820 70 65 63 69 66 69 65 73 20 74 68 65 20 6d 61 78  pecifies the max
16830 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 74 68 65  imum size of the
16840 20 63 72 65 61 74 65 64 20 68 65 61 70 2e 0a 2a   created heap..*
16850 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69  * </dl>.*/.#defi
16860 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
16870 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20 20 31  _SINGLETHREAD  1
16880 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66    /* nil */.#def
16890 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
168a0 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 20 20  G_MULTITHREAD   
168b0 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65  2  /* nil */.#de
168c0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
168d0 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 20 20  IG_SERIALIZED   
168e0 20 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64   3  /* nil */.#d
168f0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
16900 46 49 47 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20  FIG_MALLOC      
16910 20 20 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f    4  /* sqlite3_
16920 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a  mem_methods* */.
16930 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
16940 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20  ONFIG_GETMALLOC 
16950 20 20 20 20 35 20 20 2f 2a 20 73 71 6c 69 74 65      5  /* sqlite
16960 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a  3_mem_methods* *
16970 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
16980 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20  _CONFIG_SCRATCH 
16990 20 20 20 20 20 20 36 20 20 2f 2a 20 76 6f 69 64        6  /* void
169a0 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e  *, int sz, int N
169b0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
169c0 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41  TE_CONFIG_PAGECA
169d0 43 48 45 20 20 20 20 20 37 20 20 2f 2a 20 76 6f  CHE     7  /* vo
169e0 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74  id*, int sz, int
169f0 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51   N */.#define SQ
16a00 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50  LITE_CONFIG_HEAP
16a10 20 20 20 20 20 20 20 20 20 20 38 20 20 2f 2a 20            8  /* 
16a20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 42 79 74 65  void*, int nByte
16a30 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 65  , int min */.#de
16a40 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
16a50 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 20 20 20  IG_MEMSTATUS    
16a60 20 39 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a   9  /* boolean *
16a70 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
16a80 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 20 20  _CONFIG_MUTEX   
16a90 20 20 20 20 20 31 30 20 20 2f 2a 20 73 71 6c 69       10  /* sqli
16aa0 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
16ab0 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  s* */.#define SQ
16ac0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
16ad0 55 54 45 58 20 20 20 20 20 31 31 20 20 2f 2a 20  UTEX     11  /* 
16ae0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
16af0 74 68 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65  thods* */./* pre
16b00 76 69 6f 75 73 6c 79 20 53 51 4c 49 54 45 5f 43  viously SQLITE_C
16b10 4f 4e 46 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43  ONFIG_CHUNKALLOC
16b20 20 31 32 20 77 68 69 63 68 20 69 73 20 6e 6f 77   12 which is now
16b30 20 75 6e 75 73 65 64 2e 20 2a 2f 20 0a 23 64 65   unused. */ .#de
16b40 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
16b50 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20  IG_LOOKASIDE    
16b60 31 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74 20 2a  13  /* int int *
16b70 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
16b80 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 20  _CONFIG_PCACHE  
16b90 20 20 20 20 20 31 34 20 20 2f 2a 20 6e 6f 2d 6f       14  /* no-o
16ba0 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  p */.#define SQL
16bb0 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
16bc0 41 43 48 45 20 20 20 20 31 35 20 20 2f 2a 20 6e  ACHE    15  /* n
16bd0 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20  o-op */.#define 
16be0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
16bf0 47 20 20 20 20 20 20 20 20 20 20 31 36 20 20 2f  G          16  /
16c00 2a 20 78 46 75 6e 63 2c 20 76 6f 69 64 2a 20 2a  * xFunc, void* *
16c10 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
16c20 5f 43 4f 4e 46 49 47 5f 55 52 49 20 20 20 20 20  _CONFIG_URI     
16c30 20 20 20 20 20 31 37 20 20 2f 2a 20 69 6e 74 20       17  /* int 
16c40 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
16c50 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32  E_CONFIG_PCACHE2
16c60 20 20 20 20 20 20 31 38 20 20 2f 2a 20 73 71 6c        18  /* sql
16c70 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68  ite3_pcache_meth
16c80 6f 64 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  ods2* */.#define
16c90 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
16ca0 45 54 50 43 41 43 48 45 32 20 20 20 31 39 20 20  ETPCACHE2   19  
16cb0 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68  /* sqlite3_pcach
16cc0 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23  e_methods2* */.#
16cd0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
16ce0 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e  NFIG_COVERING_IN
16cf0 44 45 58 5f 53 43 41 4e 20 32 30 20 20 2f 2a 20  DEX_SCAN 20  /* 
16d00 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  int */.#define S
16d10 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c  QLITE_CONFIG_SQL
16d20 4c 4f 47 20 20 20 20 20 20 20 32 31 20 20 2f 2a  LOG       21  /*
16d30 20 78 53 71 6c 6c 6f 67 2c 20 76 6f 69 64 2a 20   xSqllog, void* 
16d40 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
16d50 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49  E_CONFIG_MMAP_SI
16d60 5a 45 20 20 20 20 32 32 20 20 2f 2a 20 73 71 6c  ZE    22  /* sql
16d70 69 74 65 33 5f 69 6e 74 36 34 2c 20 73 71 6c 69  ite3_int64, sqli
16d80 74 65 33 5f 69 6e 74 36 34 20 2a 2f 0a 23 64 65  te3_int64 */.#de
16d90 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
16da0 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a  IG_WIN32_HEAPSIZ
16db0 45 20 20 20 20 20 20 32 33 20 20 2f 2a 20 69 6e  E      23  /* in
16dc0 74 20 6e 42 79 74 65 20 2a 2f 0a 0a 2f 2a 0a 2a  t nByte */../*.*
16dd0 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61  * CAPI3REF: Data
16de0 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20  base Connection 
16df0 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70  Configuration Op
16e00 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tions.**.** Thes
16e10 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20  e constants are 
16e20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e  the available in
16e30 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74  teger configurat
16e40 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74  ion options that
16e50 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65  .** can be passe
16e60 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  d as the second 
16e70 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
16e80 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
16e90 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  ig()] interface.
16ea0 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69  .**.** New confi
16eb0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
16ec0 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
16ed0 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
16ee0 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45   of SQLite..** E
16ef0 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72  xisting configur
16f00 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69  ation options mi
16f10 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e  ght be discontin
16f20 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  ued.  Applicatio
16f30 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65  ns.** should che
16f40 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f  ck the return co
16f50 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  de from [sqlite3
16f60 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f  _db_config()] to
16f70 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a   make sure that.
16f80 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b  ** the call work
16f90 65 64 2e 20 20 5e 54 68 65 20 5b 73 71 6c 69 74  ed.  ^The [sqlit
16fa0 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
16fb0 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72  interface will r
16fc0 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a  eturn a.** non-z
16fd0 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ero [error code]
16fe0 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75   if a discontinu
16ff0 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65  ed or unsupporte
17000 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  d configuration 
17010 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76  option.** is inv
17020 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e  oked..**.** <dl>
17030 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44  .** <dt>SQLITE_D
17040 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
17050 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  E</dt>.** <dd> ^
17060 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
17070 73 20 74 68 72 65 65 20 61 64 64 69 74 69 6f 6e  s three addition
17080 61 6c 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61  al arguments tha
17090 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20  t determine the 
170a0 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d  .** [lookaside m
170b0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d  emory allocator]
170c0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66   configuration f
170d0 6f 72 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  or the [database
170e0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a   connection]..**
170f0 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75   ^The first argu
17100 6d 65 6e 74 20 28 74 68 65 20 74 68 69 72 64 20  ment (the third 
17110 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
17120 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
17130 29 5d 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74  )] is a.** point
17140 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 62  er to a memory b
17150 75 66 66 65 72 20 74 6f 20 75 73 65 20 66 6f 72  uffer to use for
17160 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72   lookaside memor
17170 79 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  y..** ^The first
17180 20 61 72 67 75 6d 65 6e 74 20 61 66 74 65 72 20   argument after 
17190 74 68 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  the SQLITE_DBCON
171a0 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 76 65  FIG_LOOKASIDE ve
171b0 72 62 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c  rb.** may be NUL
171c0 4c 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20  L in which case 
171d0 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 6c 6f  SQLite will allo
171e0 63 61 74 65 20 74 68 65 0a 2a 2a 20 6c 6f 6f 6b  cate the.** look
171f0 61 73 69 64 65 20 62 75 66 66 65 72 20 69 74 73  aside buffer its
17200 65 6c 66 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  elf using [sqlit
17210 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 5e 54  e3_malloc()]. ^T
17220 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
17230 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a  nt is the.** siz
17240 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73  e of each lookas
17250 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 2e  ide buffer slot.
17260 20 20 5e 54 68 65 20 74 68 69 72 64 20 61 72 67    ^The third arg
17270 75 6d 65 6e 74 20 69 73 20 74 68 65 20 6e 75 6d  ument is the num
17280 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e  ber of.** slots.
17290 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68    The size of th
172a0 65 20 62 75 66 66 65 72 20 69 6e 20 74 68 65 20  e buffer in the 
172b0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d  first argument m
172c0 75 73 74 20 62 65 20 67 72 65 61 74 65 72 20 74  ust be greater t
172d0 68 61 6e 0a 2a 2a 20 6f 72 20 65 71 75 61 6c 20  han.** or equal 
172e0 74 6f 20 74 68 65 20 70 72 6f 64 75 63 74 20 6f  to the product o
172f0 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64  f the second and
17300 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 73   third arguments
17310 2e 20 20 54 68 65 20 62 75 66 66 65 72 0a 2a 2a  .  The buffer.**
17320 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64   must be aligned
17330 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f   to an 8-byte bo
17340 75 6e 64 61 72 79 2e 20 20 5e 49 66 20 74 68 65  undary.  ^If the
17350 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
17360 20 74 6f 0a 2a 2a 20 53 51 4c 49 54 45 5f 44 42   to.** SQLITE_DB
17370 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
17380 20 69 73 20 6e 6f 74 20 61 20 6d 75 6c 74 69 70   is not a multip
17390 6c 65 20 6f 66 20 38 2c 20 69 74 20 69 73 20 69  le of 8, it is i
173a0 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 72 6f 75  nternally.** rou
173b0 6e 64 65 64 20 64 6f 77 6e 20 74 6f 20 74 68 65  nded down to the
173c0 20 6e 65 78 74 20 73 6d 61 6c 6c 65 72 20 6d 75   next smaller mu
173d0 6c 74 69 70 6c 65 20 6f 66 20 38 2e 20 20 5e 28  ltiple of 8.  ^(
173e0 54 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65  The lookaside me
173f0 6d 6f 72 79 0a 2a 2a 20 63 6f 6e 66 69 67 75 72  mory.** configur
17400 61 74 69 6f 6e 20 66 6f 72 20 61 20 64 61 74 61  ation for a data
17410 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
17420 63 61 6e 20 6f 6e 6c 79 20 62 65 20 63 68 61 6e  can only be chan
17430 67 65 64 20 77 68 65 6e 20 74 68 61 74 0a 2a 2a  ged when that.**
17440 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6e   connection is n
17450 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 75 73 69  ot currently usi
17460 6e 67 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  ng lookaside mem
17470 6f 72 79 2c 20 6f 72 20 69 6e 20 6f 74 68 65 72  ory, or in other
17480 20 77 6f 72 64 73 0a 2a 2a 20 77 68 65 6e 20 74   words.** when t
17490 68 65 20 22 63 75 72 72 65 6e 74 20 76 61 6c 75  he "current valu
174a0 65 22 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  e" returned by.*
174b0 2a 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 73 74  * [sqlite3_db_st
174c0 61 74 75 73 5d 28 44 2c 5b 53 51 4c 49 54 45 5f  atus](D,[SQLITE_
174d0 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
174e0 5d 2c 2e 2e 2e 29 20 69 73 20 7a 65 72 6f 2e 0a  ],...) is zero..
174f0 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74  ** Any attempt t
17500 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f  o change the loo
17510 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 63 6f  kaside memory co
17520 6e 66 69 67 75 72 61 74 69 6f 6e 20 77 68 65 6e  nfiguration when
17530 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 6d 65   lookaside.** me
17540 6d 6f 72 79 20 69 73 20 69 6e 20 75 73 65 20 6c  mory is in use l
17550 65 61 76 65 73 20 74 68 65 20 63 6f 6e 66 69 67  eaves the config
17560 75 72 61 74 69 6f 6e 20 75 6e 63 68 61 6e 67 65  uration unchange
17570 64 20 61 6e 64 20 72 65 74 75 72 6e 73 20 0a 2a  d and returns .*
17580 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e  * [SQLITE_BUSY].
17590 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  )^</dd>.**.** <d
175a0 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  t>SQLITE_DBCONFI
175b0 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 3c 2f 64  G_ENABLE_FKEY</d
175c0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
175d0 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20   option is used 
175e0 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73  to enable or dis
175f0 61 62 6c 65 20 74 68 65 20 65 6e 66 6f 72 63 65  able the enforce
17600 6d 65 6e 74 20 6f 66 0a 2a 2a 20 5b 66 6f 72 65  ment of.** [fore
17610 69 67 6e 20 6b 65 79 20 63 6f 6e 73 74 72 61 69  ign key constrai
17620 6e 74 73 5d 2e 20 20 54 68 65 72 65 20 73 68 6f  nts].  There sho
17630 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74  uld be two addit
17640 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e  ional arguments.
17650 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
17660 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74  gument is an int
17670 65 67 65 72 20 77 68 69 63 68 20 69 73 20 30 20  eger which is 0 
17680 74 6f 20 64 69 73 61 62 6c 65 20 46 4b 20 65 6e  to disable FK en
17690 66 6f 72 63 65 6d 65 6e 74 2c 0a 2a 2a 20 70 6f  forcement,.** po
176a0 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65  sitive to enable
176b0 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20   FK enforcement 
176c0 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c  or negative to l
176d0 65 61 76 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d  eave FK enforcem
176e0 65 6e 74 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 64  ent.** unchanged
176f0 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  .  The second pa
17700 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69  rameter is a poi
17710 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67  nter to an integ
17720 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a  er into which.**
17730 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72   is written 0 or
17740 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77   1 to indicate w
17750 68 65 74 68 65 72 20 46 4b 20 65 6e 66 6f 72 63  hether FK enforc
17760 65 6d 65 6e 74 20 69 73 20 6f 66 66 20 6f 72 20  ement is off or 
17770 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  on.** following 
17780 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20  this call.  The 
17790 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
177a0 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70   may be a NULL p
177b0 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68  ointer, in.** wh
177c0 69 63 68 20 63 61 73 65 20 74 68 65 20 46 4b 20  ich case the FK 
177d0 65 6e 66 6f 72 63 65 6d 65 6e 74 20 73 65 74 74  enforcement sett
177e0 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72  ing is not repor
177f0 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a  ted back. </dd>.
17800 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
17810 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
17820 5f 54 52 49 47 47 45 52 3c 2f 64 74 3e 0a 2a 2a  _TRIGGER</dt>.**
17830 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69   <dd> ^This opti
17840 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e  on is used to en
17850 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20  able or disable 
17860 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20  [CREATE TRIGGER 
17870 7c 20 74 72 69 67 67 65 72 73 5d 2e 0a 2a 2a 20  | triggers]..** 
17880 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20  There should be 
17890 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61  two additional a
178a0 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65  rguments..** The
178b0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
178c0 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68  is an integer wh
178d0 69 63 68 20 69 73 20 30 20 74 6f 20 64 69 73 61  ich is 0 to disa
178e0 62 6c 65 20 74 72 69 67 67 65 72 73 2c 0a 2a 2a  ble triggers,.**
178f0 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61   positive to ena
17900 62 6c 65 20 74 72 69 67 67 65 72 73 20 6f 72 20  ble triggers or 
17910 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76  negative to leav
17920 65 20 74 68 65 20 73 65 74 74 69 6e 67 20 75 6e  e the setting un
17930 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 54 68 65 20  changed..** The 
17940 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
17950 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
17960 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f   an integer into
17970 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69   which.** is wri
17980 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69  tten 0 or 1 to i
17990 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20  ndicate whether 
179a0 74 72 69 67 67 65 72 73 20 61 72 65 20 64 69 73  triggers are dis
179b0 61 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 64  abled or enabled
179c0 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68  .** following th
179d0 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65  is call.  The se
179e0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d  cond parameter m
179f0 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69  ay be a NULL poi
17a00 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63  nter, in.** whic
17a10 68 20 63 61 73 65 20 74 68 65 20 74 72 69 67 67  h case the trigg
17a20 65 72 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f  er setting is no
17a30 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e  t reported back.
17a40 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64   </dd>.**.** </d
17a50 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  l>.*/.#define SQ
17a60 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
17a70 4f 4b 41 53 49 44 45 20 20 20 20 20 20 20 31 30  OKASIDE       10
17a80 30 31 20 20 2f 2a 20 76 6f 69 64 2a 20 69 6e 74  01  /* void* int
17a90 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20   int */.#define 
17aa0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
17ab0 45 4e 41 42 4c 45 5f 46 4b 45 59 20 20 20 20 20  ENABLE_FKEY     
17ac0 31 30 30 32 20 20 2f 2a 20 69 6e 74 20 69 6e 74  1002  /* int int
17ad0 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
17ae0 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41  ITE_DBCONFIG_ENA
17af0 42 4c 45 5f 54 52 49 47 47 45 52 20 20 31 30 30  BLE_TRIGGER  100
17b00 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a  3  /* int int* *
17b10 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  /.../*.** CAPI3R
17b20 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69  EF: Enable Or Di
17b30 73 61 62 6c 65 20 45 78 74 65 6e 64 65 64 20 52  sable Extended R
17b40 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 0a 2a  esult Codes.**.*
17b50 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65  * ^The sqlite3_e
17b60 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63  xtended_result_c
17b70 6f 64 65 73 28 29 20 72 6f 75 74 69 6e 65 20 65  odes() routine e
17b80 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c  nables or disabl
17b90 65 73 20 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e  es the.** [exten
17ba0 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
17bb0 5d 20 66 65 61 74 75 72 65 20 6f 66 20 53 51 4c  ] feature of SQL
17bc0 69 74 65 2e 20 5e 54 68 65 20 65 78 74 65 6e 64  ite. ^The extend
17bd0 65 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64  ed result.** cod
17be0 65 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20  es are disabled 
17bf0 62 79 20 64 65 66 61 75 6c 74 20 66 6f 72 20 68  by default for h
17c00 69 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74  istorical compat
17c10 69 62 69 6c 69 74 79 2e 0a 2a 2f 0a 53 51 4c 49  ibility..*/.SQLI
17c20 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
17c30 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75  e3_extended_resu
17c40 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69 74 65 33  lt_codes(sqlite3
17c50 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a  *, int onoff);..
17c60 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
17c70 4c 61 73 74 20 49 6e 73 65 72 74 20 52 6f 77 69  Last Insert Rowi
17c80 64 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20 65 6e  d.**.** ^Each en
17c90 74 72 79 20 69 6e 20 6d 6f 73 74 20 53 51 4c 69  try in most SQLi
17ca0 74 65 20 74 61 62 6c 65 73 20 28 65 78 63 65 70  te tables (excep
17cb0 74 20 66 6f 72 20 5b 57 49 54 48 4f 55 54 20 52  t for [WITHOUT R
17cc0 4f 57 49 44 5d 20 74 61 62 6c 65 73 29 0a 2a 2a  OWID] tables).**
17cd0 20 68 61 73 20 61 20 75 6e 69 71 75 65 20 36 34   has a unique 64
17ce0 2d 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20 69  -bit signed.** i
17cf0 6e 74 65 67 65 72 20 6b 65 79 20 63 61 6c 6c 65  nteger key calle
17d00 64 20 74 68 65 20 5b 52 4f 57 49 44 20 7c 20 22  d the [ROWID | "
17d10 72 6f 77 69 64 22 5d 2e 20 5e 54 68 65 20 72 6f  rowid"]. ^The ro
17d20 77 69 64 20 69 73 20 61 6c 77 61 79 73 20 61 76  wid is always av
17d30 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61 6e  ailable.** as an
17d40 20 75 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c 75   undeclared colu
17d50 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c 20  mn named ROWID, 
17d60 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f 20  OID, or _ROWID_ 
17d70 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73 65  as long as those
17d80 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e 6f  .** names are no
17d90 74 20 61 6c 73 6f 20 75 73 65 64 20 62 79 20 65  t also used by e
17da0 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72  xplicitly declar
17db0 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66 0a  ed columns. ^If.
17dc0 2a 2a 20 74 68 65 20 74 61 62 6c 65 20 68 61 73  ** the table has
17dd0 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 70   a column of typ
17de0 65 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41  e [INTEGER PRIMA
17df0 52 59 20 4b 45 59 5d 20 74 68 65 6e 20 74 68 61  RY KEY] then tha
17e00 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61  t column.** is a
17e10 6e 6f 74 68 65 72 20 61 6c 69 61 73 20 66 6f 72  nother alias for
17e20 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a   the rowid..**.*
17e30 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6c  * ^The sqlite3_l
17e40 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
17e50 28 44 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  (D) interface re
17e60 74 75 72 6e 73 20 74 68 65 20 5b 72 6f 77 69 64  turns the [rowid
17e70 5d 20 6f 66 20 74 68 65 20 0a 2a 2a 20 6d 6f 73  ] of the .** mos
17e80 74 20 72 65 63 65 6e 74 20 73 75 63 63 65 73 73  t recent success
17e90 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 69 6e 74  ful [INSERT] int
17ea0 6f 20 61 20 72 6f 77 69 64 20 74 61 62 6c 65 20  o a rowid table 
17eb0 6f 72 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c  or [virtual tabl
17ec0 65 5d 0a 2a 2a 20 6f 6e 20 64 61 74 61 62 61 73  e].** on databas
17ed0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 0a  e connection D..
17ee0 2a 2a 20 5e 49 6e 73 65 72 74 73 20 69 6e 74 6f  ** ^Inserts into
17ef0 20 5b 57 49 54 48 4f 55 54 20 52 4f 57 49 44 5d   [WITHOUT ROWID]
17f00 20 74 61 62 6c 65 73 20 61 72 65 20 6e 6f 74 20   tables are not 
17f10 72 65 63 6f 72 64 65 64 2e 0a 2a 2a 20 5e 49 66  recorded..** ^If
17f20 20 6e 6f 20 73 75 63 63 65 73 73 66 75 6c 20 5b   no successful [
17f30 49 4e 53 45 52 54 5d 73 20 69 6e 74 6f 20 72 6f  INSERT]s into ro
17f40 77 69 64 20 74 61 62 6c 65 73 0a 2a 2a 20 68 61  wid tables.** ha
17f50 76 65 20 65 76 65 72 20 6f 63 63 75 72 72 65 64  ve ever occurred
17f60 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65   on the database
17f70 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2c 20 0a   connection D, .
17f80 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  ** then sqlite3_
17f90 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
17fa0 64 28 44 29 20 72 65 74 75 72 6e 73 20 7a 65 72  d(D) returns zer
17fb0 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 6e  o..**.** ^(If an
17fc0 20 5b 49 4e 53 45 52 54 5d 20 6f 63 63 75 72 73   [INSERT] occurs
17fd0 20 77 69 74 68 69 6e 20 61 20 74 72 69 67 67 65   within a trigge
17fe0 72 20 6f 72 20 77 69 74 68 69 6e 20 61 20 5b 76  r or within a [v
17ff0 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a  irtual table].**
18000 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e 20 74 68   method, then th
18010 69 73 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20  is routine will 
18020 72 65 74 75 72 6e 20 74 68 65 20 5b 72 6f 77 69  return the [rowi
18030 64 5d 20 6f 66 20 74 68 65 20 69 6e 73 65 72 74  d] of the insert
18040 65 64 0a 2a 2a 20 72 6f 77 20 61 73 20 6c 6f 6e  ed.** row as lon
18050 67 20 61 73 20 74 68 65 20 74 72 69 67 67 65 72  g as the trigger
18060 20 6f 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c   or virtual tabl
18070 65 20 6d 65 74 68 6f 64 20 69 73 20 72 75 6e 6e  e method is runn
18080 69 6e 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e 63 65  ing..** But once
18090 20 74 68 65 20 74 72 69 67 67 65 72 20 6f 72 20   the trigger or 
180a0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 65  virtual table me
180b0 74 68 6f 64 20 65 6e 64 73 2c 20 74 68 65 20 76  thod ends, the v
180c0 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 0a 2a  alue returned .*
180d0 2a 20 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e  * by this routin
180e0 65 20 72 65 76 65 72 74 73 20 74 6f 20 77 68 61  e reverts to wha
180f0 74 20 69 74 20 77 61 73 20 62 65 66 6f 72 65 20  t it was before 
18100 74 68 65 20 74 72 69 67 67 65 72 20 6f 72 20 76  the trigger or v
18110 69 72 74 75 61 6c 0a 2a 2a 20 74 61 62 6c 65 20  irtual.** table 
18120 6d 65 74 68 6f 64 20 62 65 67 61 6e 2e 29 5e 0a  method began.)^.
18130 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45 52  **.** ^An [INSER
18140 54 5d 20 74 68 61 74 20 66 61 69 6c 73 20 64 75  T] that fails du
18150 65 20 74 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e  e to a constrain
18160 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e  t violation is n
18170 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65 73 73 66  ot a.** successf
18180 75 6c 20 5b 49 4e 53 45 52 54 5d 20 61 6e 64 20  ul [INSERT] and 
18190 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20  does not change 
181a0 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
181b0 65 64 20 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f  ed by this.** ro
181c0 75 74 69 6e 65 2e 20 20 5e 54 68 75 73 20 49 4e  utine.  ^Thus IN
181d0 53 45 52 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e  SERT OR FAIL, IN
181e0 53 45 52 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20  SERT OR IGNORE, 
181f0 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41  INSERT OR ROLLBA
18200 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52  CK,.** and INSER
18210 54 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b 65 20  T OR ABORT make 
18220 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68  no changes to th
18230 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f  e return value o
18240 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e  f this.** routin
18250 65 20 77 68 65 6e 20 74 68 65 69 72 20 69 6e 73  e when their ins
18260 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 5e  ertion fails.  ^
18270 28 57 68 65 6e 20 49 4e 53 45 52 54 20 4f 52 20  (When INSERT OR 
18280 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75  REPLACE.** encou
18290 6e 74 65 72 73 20 61 20 63 6f 6e 73 74 72 61 69  nters a constrai
182a0 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74  nt violation, it
182b0 20 64 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20   does not fail. 
182c0 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63   The.** INSERT c
182d0 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70  ontinues to comp
182e0 6c 65 74 69 6f 6e 20 61 66 74 65 72 20 64 65 6c  letion after del
182f0 65 74 69 6e 67 20 72 6f 77 73 20 74 68 61 74 20  eting rows that 
18300 63 61 75 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f  caused.** the co
18310 6e 73 74 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d  nstraint problem
18320 20 73 6f 20 49 4e 53 45 52 54 20 4f 52 20 52 45   so INSERT OR RE
18330 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c 77 61 79  PLACE will alway
18340 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20  s change.** the 
18350 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
18360 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e 29  this interface.)
18370 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65  ^.**.** ^For the
18380 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69   purposes of thi
18390 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49  s routine, an [I
183a0 4e 53 45 52 54 5d 20 69 73 20 63 6f 6e 73 69 64  NSERT] is consid
183b0 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75  ered to.** be su
183c0 63 63 65 73 73 66 75 6c 20 65 76 65 6e 20 69 66  ccessful even if
183d0 20 69 74 20 69 73 20 73 75 62 73 65 71 75 65 6e   it is subsequen
183e0 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e  tly rolled back.
183f0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63  .**.** This func
18400 74 69 6f 6e 20 69 73 20 61 63 63 65 73 73 69 62  tion is accessib
18410 6c 65 20 74 6f 20 53 51 4c 20 73 74 61 74 65 6d  le to SQL statem
18420 65 6e 74 73 20 76 69 61 20 74 68 65 0a 2a 2a 20  ents via the.** 
18430 5b 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  [last_insert_row
18440 69 64 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f  id() SQL functio
18450 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73  n]..**.** If a s
18460 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20 70  eparate thread p
18470 65 72 66 6f 72 6d 73 20 61 20 6e 65 77 20 5b 49  erforms a new [I
18480 4e 53 45 52 54 5d 20 6f 6e 20 74 68 65 20 73 61  NSERT] on the sa
18490 6d 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  me.** database c
184a0 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20  onnection while 
184b0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73  the [sqlite3_las
184c0 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29  t_insert_rowid()
184d0 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73  ].** function is
184e0 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75   running and thu
184f0 73 20 63 68 61 6e 67 65 73 20 74 68 65 20 6c 61  s changes the la
18500 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64  st insert [rowid
18510 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 76  ],.** then the v
18520 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
18530 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69   [sqlite3_last_i
18540 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 69  nsert_rowid()] i
18550 73 0a 2a 2a 20 75 6e 70 72 65 64 69 63 74 61 62  s.** unpredictab
18560 6c 65 20 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74  le and might not
18570 20 65 71 75 61 6c 20 65 69 74 68 65 72 20 74 68   equal either th
18580 65 20 6f 6c 64 20 6f 72 20 74 68 65 20 6e 65 77  e old or the new
18590 0a 2a 2a 20 6c 61 73 74 20 69 6e 73 65 72 74 20  .** last insert 
185a0 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 53 51 4c 49  [rowid]..*/.SQLI
185b0 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69  TE_API sqlite3_i
185c0 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6c 61 73  nt64 sqlite3_las
185d0 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 73  t_insert_rowid(s
185e0 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
185f0 20 43 41 50 49 33 52 45 46 3a 20 43 6f 75 6e 74   CAPI3REF: Count
18600 20 54 68 65 20 4e 75 6d 62 65 72 20 4f 66 20 52   The Number Of R
18610 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a  ows Modified.**.
18620 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f  ** ^This functio
18630 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  n returns the nu
18640 6d 62 65 72 20 6f 66 20 64 61 74 61 62 61 73 65  mber of database
18650 20 72 6f 77 73 20 74 68 61 74 20 77 65 72 65 20   rows that were 
18660 63 68 61 6e 67 65 64 0a 2a 2a 20 6f 72 20 69 6e  changed.** or in
18670 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65  serted or delete
18680 64 20 62 79 20 74 68 65 20 6d 6f 73 74 20 72 65  d by the most re
18690 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64  cently completed
186a0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a   SQL statement.*
186b0 2a 20 6f 6e 20 74 68 65 20 5b 64 61 74 61 62 61  * on the [databa
186c0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73  se connection] s
186d0 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
186e0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e  first parameter.
186f0 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 63 68 61 6e 67  .** ^(Only chang
18700 65 73 20 74 68 61 74 20 61 72 65 20 64 69 72 65  es that are dire
18710 63 74 6c 79 20 73 70 65 63 69 66 69 65 64 20 62  ctly specified b
18720 79 20 74 68 65 20 5b 49 4e 53 45 52 54 5d 2c 20  y the [INSERT], 
18730 5b 55 50 44 41 54 45 5d 2c 0a 2a 2a 20 6f 72 20  [UPDATE],.** or 
18740 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d 65  [DELETE] stateme
18750 6e 74 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 20  nt are counted. 
18760 20 41 75 78 69 6c 69 61 72 79 20 63 68 61 6e 67   Auxiliary chang
18770 65 73 20 63 61 75 73 65 64 20 62 79 0a 2a 2a 20  es caused by.** 
18780 74 72 69 67 67 65 72 73 20 6f 72 20 5b 66 6f 72  triggers or [for
18790 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73  eign key actions
187a0 5d 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65  ] are not counte
187b0 64 2e 29 5e 20 55 73 65 20 74 68 65 0a 2a 2a 20  d.)^ Use the.** 
187c0 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63  [sqlite3_total_c
187d0 68 61 6e 67 65 73 28 29 5d 20 66 75 6e 63 74 69  hanges()] functi
187e0 6f 6e 20 74 6f 20 66 69 6e 64 20 74 68 65 20 74  on to find the t
187f0 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 63  otal number of c
18800 68 61 6e 67 65 73 0a 2a 2a 20 69 6e 63 6c 75 64  hanges.** includ
18810 69 6e 67 20 63 68 61 6e 67 65 73 20 63 61 75 73  ing changes caus
18820 65 64 20 62 79 20 74 72 69 67 67 65 72 73 20 61  ed by triggers a
18830 6e 64 20 66 6f 72 65 69 67 6e 20 6b 65 79 20 61  nd foreign key a
18840 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 43  ctions..**.** ^C
18850 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65 77  hanges to a view
18860 20 74 68 61 74 20 61 72 65 20 73 69 6d 75 6c 61   that are simula
18870 74 65 64 20 62 79 20 61 6e 20 5b 49 4e 53 54 45  ted by an [INSTE
18880 41 44 20 4f 46 20 74 72 69 67 67 65 72 5d 0a 2a  AD OF trigger].*
18890 2a 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65  * are not counte
188a0 64 2e 20 20 4f 6e 6c 79 20 72 65 61 6c 20 74 61  d.  Only real ta
188b0 62 6c 65 20 63 68 61 6e 67 65 73 20 61 72 65 20  ble changes are 
188c0 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  counted..**.** ^
188d0 28 41 20 22 72 6f 77 20 63 68 61 6e 67 65 22 20  (A "row change" 
188e0 69 73 20 61 20 63 68 61 6e 67 65 20 74 6f 20 61  is a change to a
188f0 20 73 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20 61   single row of a
18900 20 73 69 6e 67 6c 65 20 74 61 62 6c 65 0a 2a 2a   single table.**
18910 20 63 61 75 73 65 64 20 62 79 20 61 6e 20 49 4e   caused by an IN
18920 53 45 52 54 2c 20 44 45 4c 45 54 45 2c 20 6f 72  SERT, DELETE, or
18930 20 55 50 44 41 54 45 20 73 74 61 74 65 6d 65 6e   UPDATE statemen
18940 74 2e 20 20 52 6f 77 73 20 74 68 61 74 0a 2a 2a  t.  Rows that.**
18950 20 61 72 65 20 63 68 61 6e 67 65 64 20 61 73 20   are changed as 
18960 73 69 64 65 20 65 66 66 65 63 74 73 20 6f 66 20  side effects of 
18970 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72  [REPLACE] constr
18980 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 2c  aint resolution,
18990 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b 2c 20 41 42  .** rollback, AB
189a0 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67 2c 20  ORT processing, 
189b0 5b 44 52 4f 50 20 54 41 42 4c 45 5d 2c 20 6f 72  [DROP TABLE], or
189c0 20 62 79 20 61 6e 79 20 6f 74 68 65 72 0a 2a 2a   by any other.**
189d0 20 6d 65 63 68 61 6e 69 73 6d 73 20 64 6f 20 6e   mechanisms do n
189e0 6f 74 20 63 6f 75 6e 74 20 61 73 20 64 69 72 65  ot count as dire
189f0 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73 2e 29  ct row changes.)
18a00 5e 0a 2a 2a 0a 2a 2a 20 41 20 22 74 72 69 67 67  ^.**.** A "trigg
18a10 65 72 20 63 6f 6e 74 65 78 74 22 20 69 73 20 61  er context" is a
18a20 20 73 63 6f 70 65 20 6f 66 20 65 78 65 63 75 74   scope of execut
18a30 69 6f 6e 20 74 68 61 74 20 62 65 67 69 6e 73 20  ion that begins 
18a40 61 6e 64 0a 2a 2a 20 65 6e 64 73 20 77 69 74 68  and.** ends with
18a50 20 74 68 65 20 73 63 72 69 70 74 20 6f 66 20 61   the script of a
18a60 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52   [CREATE TRIGGER
18a70 20 7c 20 74 72 69 67 67 65 72 5d 2e 20 0a 2a 2a   | trigger]. .**
18a80 20 4d 6f 73 74 20 53 51 4c 20 73 74 61 74 65 6d   Most SQL statem
18a90 65 6e 74 73 20 61 72 65 0a 2a 2a 20 65 76 61 6c  ents are.** eval
18aa0 75 61 74 65 64 20 6f 75 74 73 69 64 65 20 6f 66  uated outside of
18ab0 20 61 6e 79 20 74 72 69 67 67 65 72 2e 20 20 54   any trigger.  T
18ac0 68 69 73 20 69 73 20 74 68 65 20 22 74 6f 70 20  his is the "top 
18ad0 6c 65 76 65 6c 22 0a 2a 2a 20 74 72 69 67 67 65  level".** trigge
18ae0 72 20 63 6f 6e 74 65 78 74 2e 20 20 49 66 20 61  r context.  If a
18af0 20 74 72 69 67 67 65 72 20 66 69 72 65 73 20 66   trigger fires f
18b00 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65  rom the top leve
18b10 6c 2c 20 61 0a 2a 2a 20 6e 65 77 20 74 72 69 67  l, a.** new trig
18b20 67 65 72 20 63 6f 6e 74 65 78 74 20 69 73 20 65  ger context is e
18b30 6e 74 65 72 65 64 20 66 6f 72 20 74 68 65 20 64  ntered for the d
18b40 75 72 61 74 69 6f 6e 20 6f 66 20 74 68 61 74 20  uration of that 
18b50 6f 6e 65 0a 2a 2a 20 74 72 69 67 67 65 72 2e 20  one.** trigger. 
18b60 20 53 75 62 74 72 69 67 67 65 72 73 20 63 72 65   Subtriggers cre
18b70 61 74 65 20 73 75 62 63 6f 6e 74 65 78 74 73 20  ate subcontexts 
18b80 66 6f 72 20 74 68 65 69 72 20 64 75 72 61 74 69  for their durati
18b90 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69  on..**.** ^Calli
18ba0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  ng [sqlite3_exec
18bb0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
18bc0 73 74 65 70 28 29 5d 20 72 65 63 75 72 73 69 76  step()] recursiv
18bd0 65 6c 79 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20  ely does.** not 
18be0 63 72 65 61 74 65 20 61 20 6e 65 77 20 74 72 69  create a new tri
18bf0 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a  gger context..**
18c00 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69  .** ^This functi
18c10 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  on returns the n
18c20 75 6d 62 65 72 20 6f 66 20 64 69 72 65 63 74 20  umber of direct 
18c30 72 6f 77 20 63 68 61 6e 67 65 73 20 69 6e 20 74  row changes in t
18c40 68 65 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65 6e  he.** most recen
18c50 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  t INSERT, UPDATE
18c60 2c 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74  , or DELETE stat
18c70 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65  ement within the
18c80 20 73 61 6d 65 0a 2a 2a 20 74 72 69 67 67 65 72   same.** trigger
18c90 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20   context..**.** 
18ca0 5e 54 68 75 73 2c 20 77 68 65 6e 20 63 61 6c 6c  ^Thus, when call
18cb0 65 64 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 20  ed from the top 
18cc0 6c 65 76 65 6c 2c 20 74 68 69 73 20 66 75 6e 63  level, this func
18cd0 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65  tion returns the
18ce0 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  .** number of ch
18cf0 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f 73  anges in the mos
18d00 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c  t recent INSERT,
18d10 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45   UPDATE, or DELE
18d20 54 45 0a 2a 2a 20 74 68 61 74 20 61 6c 73 6f 20  TE.** that also 
18d30 6f 63 63 75 72 72 65 64 20 61 74 20 74 68 65 20  occurred at the 
18d40 74 6f 70 20 6c 65 76 65 6c 2e 20 20 5e 28 57 69  top level.  ^(Wi
18d50 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66  thin the body of
18d60 20 61 20 74 72 69 67 67 65 72 2c 0a 2a 2a 20 74   a trigger,.** t
18d70 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  he sqlite3_chang
18d80 65 73 28 29 20 69 6e 74 65 72 66 61 63 65 20 63  es() interface c
18d90 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 74 6f 20  an be called to 
18da0 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20  find the number 
18db0 6f 66 0a 2a 2a 20 63 68 61 6e 67 65 73 20 69 6e  of.** changes in
18dc0 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
18dd0 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53  ly completed INS
18de0 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20  ERT, UPDATE, or 
18df0 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d  DELETE.** statem
18e00 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20 62  ent within the b
18e10 6f 64 79 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ody of the same 
18e20 74 72 69 67 67 65 72 2e 0a 2a 2a 20 48 6f 77 65  trigger..** Howe
18e30 76 65 72 2c 20 74 68 65 20 6e 75 6d 62 65 72 20  ver, the number 
18e40 72 65 74 75 72 6e 65 64 20 64 6f 65 73 20 6e 6f  returned does no
18e50 74 20 69 6e 63 6c 75 64 65 20 63 68 61 6e 67 65  t include change
18e60 73 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20 73  s.** caused by s
18e70 75 62 74 72 69 67 67 65 72 73 20 73 69 6e 63 65  ubtriggers since
18e80 20 74 68 6f 73 65 20 68 61 76 65 20 74 68 65 69   those have thei
18e90 72 20 6f 77 6e 20 63 6f 6e 74 65 78 74 2e 29 5e  r own context.)^
18ea0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20  .**.** See also 
18eb0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74  the [sqlite3_tot
18ec0 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e  al_changes()] in
18ed0 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20  terface, the.** 
18ee0 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70  [count_changes p
18ef0 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20  ragma], and the 
18f00 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66  [changes() SQL f
18f10 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20  unction]..**.** 
18f20 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68  If a separate th
18f30 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67  read makes chang
18f40 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64  es on the same d
18f50 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
18f60 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c  on.** while [sql
18f70 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20  ite3_changes()] 
18f80 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20  is running then 
18f90 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
18fa0 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65 64 69  ed.** is unpredi
18fb0 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d  ctable and not m
18fc0 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 53 51  eaningful..*/.SQ
18fd0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
18fe0 69 74 65 33 5f 63 68 61 6e 67 65 73 28 73 71 6c  ite3_changes(sql
18ff0 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
19000 41 50 49 33 52 45 46 3a 20 54 6f 74 61 6c 20 4e  API3REF: Total N
19010 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f  umber Of Rows Mo
19020 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68  dified.**.** ^Th
19030 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  is function retu
19040 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
19050 66 20 72 6f 77 20 63 68 61 6e 67 65 73 20 63 61  f row changes ca
19060 75 73 65 64 20 62 79 20 5b 49 4e 53 45 52 54 5d  used by [INSERT]
19070 2c 0a 2a 2a 20 5b 55 50 44 41 54 45 5d 20 6f 72  ,.** [UPDATE] or
19080 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d   [DELETE] statem
19090 65 6e 74 73 20 73 69 6e 63 65 20 74 68 65 20 5b  ents since the [
190a0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
190b0 69 6f 6e 5d 20 77 61 73 20 6f 70 65 6e 65 64 2e  ion] was opened.
190c0 0a 2a 2a 20 5e 28 54 68 65 20 63 6f 75 6e 74 20  .** ^(The count 
190d0 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
190e0 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
190f0 73 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c  s() includes all
19100 20 63 68 61 6e 67 65 73 0a 2a 2a 20 66 72 6f 6d   changes.** from
19110 20 61 6c 6c 20 5b 43 52 45 41 54 45 20 54 52 49   all [CREATE TRI
19120 47 47 45 52 20 7c 20 74 72 69 67 67 65 72 5d 20  GGER | trigger] 
19130 63 6f 6e 74 65 78 74 73 20 61 6e 64 20 63 68 61  contexts and cha
19140 6e 67 65 73 20 6d 61 64 65 20 62 79 0a 2a 2a 20  nges made by.** 
19150 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74  [foreign key act
19160 69 6f 6e 73 5d 2e 20 48 6f 77 65 76 65 72 2c 0a  ions]. However,.
19170 2a 2a 20 74 68 65 20 63 6f 75 6e 74 20 64 6f 65  ** the count doe
19180 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63 68  s not include ch
19190 61 6e 67 65 73 20 75 73 65 64 20 74 6f 20 69 6d  anges used to im
191a0 70 6c 65 6d 65 6e 74 20 5b 52 45 50 4c 41 43 45  plement [REPLACE
191b0 5d 20 63 6f 6e 73 74 72 61 69 6e 74 73 2c 0a 2a  ] constraints,.*
191c0 2a 20 64 6f 20 72 6f 6c 6c 62 61 63 6b 73 20 6f  * do rollbacks o
191d0 72 20 41 42 4f 52 54 20 70 72 6f 63 65 73 73 69  r ABORT processi
191e0 6e 67 2c 20 6f 72 20 5b 44 52 4f 50 20 54 41 42  ng, or [DROP TAB
191f0 4c 45 5d 20 70 72 6f 63 65 73 73 69 6e 67 2e 20  LE] processing. 
19200 20 54 68 65 0a 2a 2a 20 63 6f 75 6e 74 20 64 6f   The.** count do
19210 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 72  es not include r
19220 6f 77 73 20 6f 66 20 76 69 65 77 73 20 74 68 61  ows of views tha
19230 74 20 66 69 72 65 20 61 6e 20 5b 49 4e 53 54 45  t fire an [INSTE
19240 41 44 20 4f 46 20 74 72 69 67 67 65 72 5d 2c 0a  AD OF trigger],.
19250 2a 2a 20 74 68 6f 75 67 68 20 69 66 20 74 68 65  ** though if the
19260 20 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67   INSTEAD OF trig
19270 67 65 72 20 6d 61 6b 65 73 20 63 68 61 6e 67 65  ger makes change
19280 73 20 6f 66 20 69 74 73 20 6f 77 6e 2c 20 74 68  s of its own, th
19290 6f 73 65 20 63 68 61 6e 67 65 73 20 0a 2a 2a 20  ose changes .** 
192a0 61 72 65 20 63 6f 75 6e 74 65 64 2e 29 5e 0a 2a  are counted.)^.*
192b0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74  * ^The sqlite3_t
192c0 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 66  otal_changes() f
192d0 75 6e 63 74 69 6f 6e 20 63 6f 75 6e 74 73 20 74  unction counts t
192e0 68 65 20 63 68 61 6e 67 65 73 20 61 73 20 73 6f  he changes as so
192f0 6f 6e 20 61 73 0a 2a 2a 20 74 68 65 20 73 74 61  on as.** the sta
19300 74 65 6d 65 6e 74 20 74 68 61 74 20 6d 61 6b 65  tement that make
19310 73 20 74 68 65 6d 20 69 73 20 63 6f 6d 70 6c 65  s them is comple
19320 74 65 64 20 28 77 68 65 6e 20 74 68 65 20 73 74  ted (when the st
19330 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 0a 2a  atement handle.*
19340 2a 20 69 73 20 70 61 73 73 65 64 20 74 6f 20 5b  * is passed to [
19350 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
19360 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e   or [sqlite3_fin
19370 61 6c 69 7a 65 28 29 5d 29 2e 0a 2a 2a 0a 2a 2a  alize()])..**.**
19380 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73   See also the [s
19390 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
193a0 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65  ] interface, the
193b0 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67  .** [count_chang
193c0 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20  es pragma], and 
193d0 74 68 65 20 5b 74 6f 74 61 6c 5f 63 68 61 6e 67  the [total_chang
193e0 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f  es() SQL functio
193f0 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73  n]..**.** If a s
19400 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20 6d  eparate thread m
19410 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20  akes changes on 
19420 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
19430 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
19440 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 74  while [sqlite3_t
19450 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20  otal_changes()] 
19460 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20  is running then 
19470 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74  the value.** ret
19480 75 72 6e 65 64 20 69 73 20 75 6e 70 72 65 64 69  urned is unpredi
19490 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d  ctable and not m
194a0 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 53 51  eaningful..*/.SQ
194b0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
194c0 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
194d0 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  es(sqlite3*);../
194e0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49  *.** CAPI3REF: I
194f0 6e 74 65 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d  nterrupt A Long-
19500 52 75 6e 6e 69 6e 67 20 51 75 65 72 79 0a 2a 2a  Running Query.**
19510 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69  .** ^This functi
19520 6f 6e 20 63 61 75 73 65 73 20 61 6e 79 20 70 65  on causes any pe
19530 6e 64 69 6e 67 20 64 61 74 61 62 61 73 65 20 6f  nding database o
19540 70 65 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72  peration to abor
19550 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20  t and.** return 
19560 61 74 20 69 74 73 20 65 61 72 6c 69 65 73 74 20  at its earliest 
19570 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20 54 68 69  opportunity. Thi
19580 73 20 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70  s routine is typ
19590 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64  ically.** called
195a0 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20   in response to 
195b0 61 20 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75  a user action su
195c0 63 68 20 61 73 20 70 72 65 73 73 69 6e 67 20 22  ch as pressing "
195d0 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74  Cancel".** or Ct
195e0 72 6c 2d 43 20 77 68 65 72 65 20 74 68 65 20 75  rl-C where the u
195f0 73 65 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67  ser wants a long
19600 20 71 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e   query operation
19610 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65   to halt.** imme
19620 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e  diately..**.** ^
19630 49 74 20 69 73 20 73 61 66 65 20 74 6f 20 63 61  It is safe to ca
19640 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  ll this routine 
19650 66 72 6f 6d 20 61 20 74 68 72 65 61 64 20 64 69  from a thread di
19660 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 65  fferent from the
19670 0a 2a 2a 20 74 68 72 65 61 64 20 74 68 61 74 20  .** thread that 
19680 69 73 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e  is currently run
19690 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 73  ning the databas
196a0 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42 75  e operation.  Bu
196b0 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73  t it.** is not s
196c0 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73  afe to call this
196d0 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 20   routine with a 
196e0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
196f0 74 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73  tion] that.** is
19700 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68 74   closed or might
19710 20 63 6c 6f 73 65 20 62 65 66 6f 72 65 20 73 71   close before sq
19720 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
19730 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a  ) returns..**.**
19740 20 5e 49 66 20 61 6e 20 53 51 4c 20 6f 70 65 72   ^If an SQL oper
19750 61 74 69 6f 6e 20 69 73 20 76 65 72 79 20 6e 65  ation is very ne
19760 61 72 6c 79 20 66 69 6e 69 73 68 65 64 20 61 74  arly finished at
19770 20 74 68 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a   the time when.*
19780 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  * sqlite3_interr
19790 75 70 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2c  upt() is called,
197a0 20 74 68 65 6e 20 69 74 20 6d 69 67 68 74 20 6e   then it might n
197b0 6f 74 20 68 61 76 65 20 61 6e 20 6f 70 70 6f 72  ot have an oppor
197c0 74 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20  tunity.** to be 
197d0 69 6e 74 65 72 72 75 70 74 65 64 20 61 6e 64 20  interrupted and 
197e0 6d 69 67 68 74 20 63 6f 6e 74 69 6e 75 65 20 74  might continue t
197f0 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a  o completion..**
19800 0a 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f 70 65 72  .** ^An SQL oper
19810 61 74 69 6f 6e 20 74 68 61 74 20 69 73 20 69 6e  ation that is in
19820 74 65 72 72 75 70 74 65 64 20 77 69 6c 6c 20 72  terrupted will r
19830 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e  eturn [SQLITE_IN
19840 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66  TERRUPT]..** ^If
19850 20 74 68 65 20 69 6e 74 65 72 72 75 70 74 65 64   the interrupted
19860 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69   SQL operation i
19870 73 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44  s an INSERT, UPD
19880 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a  ATE, or DELETE.*
19890 2a 20 74 68 61 74 20 69 73 20 69 6e 73 69 64 65  * that is inside
198a0 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61   an explicit tra
198b0 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74  nsaction, then t
198c0 68 65 20 65 6e 74 69 72 65 20 74 72 61 6e 73 61  he entire transa
198d0 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65  ction.** will be
198e0 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74   rolled back aut
198f0 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a  omatically..**.*
19900 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69  * ^The sqlite3_i
19910 6e 74 65 72 72 75 70 74 28 44 29 20 63 61 6c 6c  nterrupt(D) call
19920 20 69 73 20 69 6e 20 65 66 66 65 63 74 20 75 6e   is in effect un
19930 74 69 6c 20 61 6c 6c 20 63 75 72 72 65 6e 74 6c  til all currentl
19940 79 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c  y running.** SQL
19950 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20 5b   statements on [
19960 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
19970 69 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65 74 65 2e  ion] D complete.
19980 20 20 5e 41 6e 79 20 6e 65 77 20 53 51 4c 20 73    ^Any new SQL s
19990 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61  tatements.** tha
199a0 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66  t are started af
199b0 74 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ter the sqlite3_
199c0 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c  interrupt() call
199d0 20 61 6e 64 20 62 65 66 6f 72 65 20 74 68 65 20   and before the 
199e0 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 73 74 61 74  .** running stat
199f0 65 6d 65 6e 74 73 20 72 65 61 63 68 65 73 20 7a  ements reaches z
19a00 65 72 6f 20 61 72 65 20 69 6e 74 65 72 72 75 70  ero are interrup
19a10 74 65 64 20 61 73 20 69 66 20 74 68 65 79 20 68  ted as if they h
19a20 61 64 20 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69  ad been.** runni
19a30 6e 67 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20  ng prior to the 
19a40 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
19a50 74 28 29 20 63 61 6c 6c 2e 20 20 5e 4e 65 77 20  t() call.  ^New 
19a60 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  SQL statements.*
19a70 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74  * that are start
19a80 65 64 20 61 66 74 65 72 20 74 68 65 20 72 75 6e  ed after the run
19a90 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 63  ning statement c
19aa0 6f 75 6e 74 20 72 65 61 63 68 65 73 20 7a 65 72  ount reaches zer
19ab0 6f 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 65 66 66  o are.** not eff
19ac0 65 63 74 65 64 20 62 79 20 74 68 65 20 73 71 6c  ected by the sql
19ad0 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
19ae0 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20  ..** ^A call to 
19af0 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
19b00 74 28 44 29 20 74 68 61 74 20 6f 63 63 75 72 73  t(D) that occurs
19b10 20 77 68 65 6e 20 74 68 65 72 65 20 61 72 65 20   when there are 
19b20 6e 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51  no running.** SQ
19b30 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 73 20  L statements is 
19b40 61 20 6e 6f 2d 6f 70 20 61 6e 64 20 68 61 73 20  a no-op and has 
19b50 6e 6f 20 65 66 66 65 63 74 20 6f 6e 20 53 51 4c  no effect on SQL
19b60 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74   statements.** t
19b70 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20  hat are started 
19b80 61 66 74 65 72 20 74 68 65 20 73 71 6c 69 74 65  after the sqlite
19b90 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61  3_interrupt() ca
19ba0 6c 6c 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a  ll returns..**.*
19bb0 2a 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73  * If the databas
19bc0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f  e connection clo
19bd0 73 65 73 20 77 68 69 6c 65 20 5b 73 71 6c 69 74  ses while [sqlit
19be0 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 0a  e3_interrupt()].
19bf0 2a 2a 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68  ** is running th
19c00 65 6e 20 62 61 64 20 74 68 69 6e 67 73 20 77 69  en bad things wi
19c10 6c 6c 20 6c 69 6b 65 6c 79 20 68 61 70 70 65 6e  ll likely happen
19c20 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
19c30 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 69 6e 74  void sqlite3_int
19c40 65 72 72 75 70 74 28 73 71 6c 69 74 65 33 2a 29  errupt(sqlite3*)
19c50 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
19c60 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20  F: Determine If 
19c70 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  An SQL Statement
19c80 20 49 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a   Is Complete.**.
19c90 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
19ca0 73 20 61 72 65 20 75 73 65 66 75 6c 20 64 75 72  s are useful dur
19cb0 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65  ing command-line
19cc0 20 69 6e 70 75 74 20 74 6f 20 64 65 74 65 72 6d   input to determ
19cd0 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20 63 75  ine if the.** cu
19ce0 72 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20  rrently entered 
19cf0 74 65 78 74 20 73 65 65 6d 73 20 74 6f 20 66 6f  text seems to fo
19d00 72 6d 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51  rm a complete SQ
19d10 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a  L statement or.*
19d20 2a 20 69 66 20 61 64 64 69 74 69 6f 6e 61 6c 20  * if additional 
19d30 69 6e 70 75 74 20 69 73 20 6e 65 65 64 65 64 20  input is needed 
19d40 62 65 66 6f 72 65 20 73 65 6e 64 69 6e 67 20 74  before sending t
19d50 68 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20  he text into.** 
19d60 53 51 4c 69 74 65 20 66 6f 72 20 70 61 72 73 69  SQLite for parsi
19d70 6e 67 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74  ng.  ^These rout
19d80 69 6e 65 73 20 72 65 74 75 72 6e 20 31 20 69 66  ines return 1 if
19d90 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e   the input strin
19da0 67 0a 2a 2a 20 61 70 70 65 61 72 73 20 74 6f 20  g.** appears to 
19db0 62 65 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51  be a complete SQ
19dc0 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 41  L statement.  ^A
19dd0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6a 75   statement is ju
19de0 64 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f  dged to be.** co
19df0 6d 70 6c 65 74 65 20 69 66 20 69 74 20 65 6e 64  mplete if it end
19e00 73 20 77 69 74 68 20 61 20 73 65 6d 69 63 6f 6c  s with a semicol
19e10 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20  on token and is 
19e20 6e 6f 74 20 61 20 70 72 65 66 69 78 20 6f 66 20  not a prefix of 
19e30 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65 64  a.** well-formed
19e40 20 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20   CREATE TRIGGER 
19e50 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 53 65 6d  statement.  ^Sem
19e60 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 65  icolons that are
19e70 20 65 6d 62 65 64 64 65 64 20 77 69 74 68 69 6e   embedded within
19e80 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 72  .** string liter
19e90 61 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 69 64  als or quoted id
19ea0 65 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 20 6f  entifier names o
19eb0 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e  r comments are n
19ec0 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e  ot.** independen
19ed0 74 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 61  t tokens (they a
19ee0 72 65 20 70 61 72 74 20 6f 66 20 74 68 65 20 74  re part of the t
19ef0 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 74 68  oken in which th
19f00 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64  ey are.** embedd
19f10 65 64 29 20 61 6e 64 20 74 68 75 73 20 64 6f 20  ed) and thus do 
19f20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 20 73  not count as a s
19f30 74 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61  tatement termina
19f40 74 6f 72 2e 20 20 5e 57 68 69 74 65 73 70 61 63  tor.  ^Whitespac
19f50 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e 74  e.** and comment
19f60 73 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74 68  s that follow th
19f70 65 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f  e final semicolo
19f80 6e 20 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a  n are ignored..*
19f90 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
19fa0 69 6e 65 73 20 72 65 74 75 72 6e 20 30 20 69 66  ines return 0 if
19fb0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
19fc0 73 20 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 5e  s incomplete.  ^
19fd0 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  If a.** memory a
19fe0 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c  llocation fails,
19ff0 20 74 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d   then SQLITE_NOM
1a000 45 4d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  EM is returned..
1a010 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
1a020 74 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 72  tines do not par
1a030 73 65 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  se the SQL state
1a040 6d 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77 69  ments thus.** wi
1a050 6c 6c 20 6e 6f 74 20 64 65 74 65 63 74 20 73 79  ll not detect sy
1a060 6e 74 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f  ntactically inco
1a070 72 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a  rrect SQL..**.**
1a080 20 5e 28 49 66 20 53 51 4c 69 74 65 20 68 61 73   ^(If SQLite has
1a090 20 6e 6f 74 20 62 65 65 6e 20 69 6e 69 74 69 61   not been initia
1a0a0 6c 69 7a 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  lized using [sql
1a0b0 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
1a0c0 29 5d 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20  )] prior .** to 
1a0d0 69 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33  invoking sqlite3
1a0e0 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 74 68  _complete16() th
1a0f0 65 6e 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  en sqlite3_initi
1a100 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b  alize() is invok
1a110 65 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61  ed.** automatica
1a120 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 63  lly by sqlite3_c
1a130 6f 6d 70 6c 65 74 65 31 36 28 29 2e 20 20 49 66  omplete16().  If
1a140 20 74 68 61 74 20 69 6e 69 74 69 61 6c 69 7a 61   that initializa
1a150 74 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74  tion fails,.** t
1a160 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76  hen the return v
1a170 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65  alue from sqlite
1a180 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 77  3_complete16() w
1a190 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a  ill be non-zero.
1a1a0 2a 2a 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66  ** regardless of
1a1b0 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
1a1c0 74 68 65 20 69 6e 70 75 74 20 53 51 4c 20 69 73  the input SQL is
1a1d0 20 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a   complete.)^.**.
1a1e0 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20  ** The input to 
1a1f0 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74  [sqlite3_complet
1a200 65 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a  e()] must be a z
1a210 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  ero-terminated.*
1a220 2a 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a  * UTF-8 string..
1a230 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20  **.** The input 
1a240 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70  to [sqlite3_comp
1a250 6c 65 74 65 31 36 28 29 5d 20 6d 75 73 74 20 62  lete16()] must b
1a260 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  e a zero-termina
1a270 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74  ted.** UTF-16 st
1a280 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62  ring in native b
1a290 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 53 51  yte order..*/.SQ
1a2a0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
1a2b0 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f  ite3_complete(co
1a2c0 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a  nst char *sql);.
1a2d0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
1a2e0 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
1a2f0 36 28 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  6(const void *sq
1a300 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  l);../*.** CAPI3
1a310 52 45 46 3a 20 52 65 67 69 73 74 65 72 20 41 20  REF: Register A 
1a320 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64  Callback To Hand
1a330 6c 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 45  le SQLITE_BUSY E
1a340 72 72 6f 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  rrors.**.** ^The
1a350 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61   sqlite3_busy_ha
1a360 6e 64 6c 65 72 28 44 2c 58 2c 50 29 20 72 6f 75  ndler(D,X,P) rou
1a370 74 69 6e 65 20 73 65 74 73 20 61 20 63 61 6c 6c  tine sets a call
1a380 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58 0a  back function X.
1a390 2a 2a 20 74 68 61 74 20 6d 69 67 68 74 20 62 65  ** that might be
1a3a0 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 72   invoked with ar
1a3b0 67 75 6d 65 6e 74 20 50 20 77 68 65 6e 65 76 65  gument P wheneve
1a3c0 72 0a 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74 20  r.** an attempt 
1a3d0 69 73 20 6d 61 64 65 20 74 6f 20 61 63 63 65 73  is made to acces
1a3e0 73 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62  s a database tab
1a3f0 6c 65 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  le associated wi
1a400 74 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  th.** [database 
1a410 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 77 68  connection] D wh
1a420 65 6e 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61  en another threa
1a430 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 65 73 73 20  d.** or process 
1a440 68 61 73 20 74 68 65 20 74 61 62 6c 65 20 6c 6f  has the table lo
1a450 63 6b 65 64 2e 0a 2a 2a 20 54 68 65 20 73 71 6c  cked..** The sql
1a460 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
1a470 72 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  r() interface is
1a480 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65   used to impleme
1a490 6e 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  nt.** [sqlite3_b
1a4a0 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 61  usy_timeout()] a
1a4b0 6e 64 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f  nd [PRAGMA busy_
1a4c0 74 69 6d 65 6f 75 74 5d 2e 0a 2a 2a 0a 2a 2a 20  timeout]..**.** 
1a4d0 5e 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c  ^If the busy cal
1a4e0 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74  lback is NULL, t
1a4f0 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  hen [SQLITE_BUSY
1a500 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64  ].** is returned
1a510 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 75 70 6f   immediately upo
1a520 6e 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74  n encountering t
1a530 68 65 20 6c 6f 63 6b 2e 20 20 5e 49 66 20 74 68  he lock.  ^If th
1a540 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a  e busy callback.
1a550 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20  ** is not NULL, 
1a560 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63  then the callbac
1a570 6b 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b  k might be invok
1a580 65 64 20 77 69 74 68 20 74 77 6f 20 61 72 67 75  ed with two argu
1a590 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ments..**.** ^Th
1a5a0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
1a5b0 20 74 6f 20 74 68 65 20 62 75 73 79 20 68 61 6e   to the busy han
1a5c0 64 6c 65 72 20 69 73 20 61 20 63 6f 70 79 20 6f  dler is a copy o
1a5d0 66 20 74 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e  f the void* poin
1a5e0 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  ter which.** is 
1a5f0 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  the third argume
1a600 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 75  nt to sqlite3_bu
1a610 73 79 5f 68 61 6e 64 6c 65 72 28 29 2e 20 20 5e  sy_handler().  ^
1a620 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
1a630 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20 62 75  ent to.** the bu
1a640 73 79 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62  sy handler callb
1a650 61 63 6b 20 69 73 20 74 68 65 20 6e 75 6d 62 65  ack is the numbe
1a660 72 20 6f 66 20 74 69 6d 65 73 20 74 68 61 74 20  r of times that 
1a670 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
1a680 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76   has.** been inv
1a690 6f 6b 65 64 20 66 6f 72 20 74 68 65 20 73 61 6d  oked for the sam
1a6a0 65 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e  e locking event.
1a6b0 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 62 75 73    ^If the.** bus
1a6c0 79 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  y callback retur
1a6d0 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61 64  ns 0, then no ad
1a6e0 64 69 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70 74  ditional attempt
1a6f0 73 20 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a 2a  s are made to.**
1a700 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74 61   access the data
1a710 62 61 73 65 20 61 6e 64 20 5b 53 51 4c 49 54 45  base and [SQLITE
1a720 5f 42 55 53 59 5d 20 69 73 20 72 65 74 75 72 6e  _BUSY] is return
1a730 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20 61 70 70  ed.** to the app
1a740 6c 69 63 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 66  lication..** ^If
1a750 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
1a760 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  turns non-zero, 
1a770 74 68 65 6e 20 61 6e 6f 74 68 65 72 20 61 74 74  then another att
1a780 65 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65 20  empt.** is made 
1a790 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 64 61  to access the da
1a7a0 74 61 62 61 73 65 20 61 6e 64 20 74 68 65 20 63  tabase and the c
1a7b0 79 63 6c 65 20 72 65 70 65 61 74 73 2e 0a 2a 2a  ycle repeats..**
1a7c0 0a 2a 2a 20 54 68 65 20 70 72 65 73 65 6e 63 65  .** The presence
1a7d0 20 6f 66 20 61 20 62 75 73 79 20 68 61 6e 64 6c   of a busy handl
1a7e0 65 72 20 64 6f 65 73 20 6e 6f 74 20 67 75 61 72  er does not guar
1a7f0 61 6e 74 65 65 20 74 68 61 74 20 69 74 20 77 69  antee that it wi
1a800 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a  ll be invoked.**
1a810 20 77 68 65 6e 20 74 68 65 72 65 20 69 73 20 6c   when there is l
1a820 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20  ock contention. 
1a830 5e 49 66 20 53 51 4c 69 74 65 20 64 65 74 65 72  ^If SQLite deter
1a840 6d 69 6e 65 73 20 74 68 61 74 20 69 6e 76 6f 6b  mines that invok
1a850 69 6e 67 20 74 68 65 20 62 75 73 79 0a 2a 2a 20  ing the busy.** 
1a860 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20 72 65  handler could re
1a870 73 75 6c 74 20 69 6e 20 61 20 64 65 61 64 6c 6f  sult in a deadlo
1a880 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67 6f 20 61  ck, it will go a
1a890 68 65 61 64 20 61 6e 64 20 72 65 74 75 72 6e 20  head and return 
1a8a0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a  [SQLITE_BUSY].**
1a8b0 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74   to the applicat
1a8c0 69 6f 6e 20 69 6e 73 74 65 61 64 20 6f 66 20 69  ion instead of i
1a8d0 6e 76 6f 6b 69 6e 67 20 74 68 65 20 0a 2a 2a 20  nvoking the .** 
1a8e0 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a  busy handler..**
1a8f0 20 43 6f 6e 73 69 64 65 72 20 61 20 73 63 65 6e   Consider a scen
1a900 61 72 69 6f 20 77 68 65 72 65 20 6f 6e 65 20 70  ario where one p
1a910 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e  rocess is holdin
1a920 67 20 61 20 72 65 61 64 20 6c 6f 63 6b 20 74 68  g a read lock th
1a930 61 74 0a 2a 2a 20 69 74 20 69 73 20 74 72 79 69  at.** it is tryi
1a940 6e 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f  ng to promote to
1a950 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b   a reserved lock
1a960 20 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f 6e 64   and.** a second
1a970 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64   process is hold
1a980 69 6e 67 20 61 20 72 65 73 65 72 76 65 64 20 6c  ing a reserved l
1a990 6f 63 6b 20 74 68 61 74 20 69 74 20 69 73 20 74  ock that it is t
1a9a0 72 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d  rying.** to prom
1a9b0 6f 74 65 20 74 6f 20 61 6e 20 65 78 63 6c 75 73  ote to an exclus
1a9c0 69 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65 20 66  ive lock.  The f
1a9d0 69 72 73 74 20 70 72 6f 63 65 73 73 20 63 61 6e  irst process can
1a9e0 6e 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a 20 62  not proceed.** b
1a9f0 65 63 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f  ecause it is blo
1aa00 63 6b 65 64 20 62 79 20 74 68 65 20 73 65 63 6f  cked by the seco
1aa10 6e 64 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e  nd and the secon
1aa20 64 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74  d process cannot
1aa30 0a 2a 2a 20 70 72 6f 63 65 65 64 20 62 65 63 61  .** proceed beca
1aa40 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65  use it is blocke
1aa50 64 20 62 79 20 74 68 65 20 66 69 72 73 74 2e 20  d by the first. 
1aa60 20 49 66 20 62 6f 74 68 20 70 72 6f 63 65 73 73   If both process
1aa70 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65  es.** invoke the
1aa80 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2c 20   busy handlers, 
1aa90 6e 65 69 74 68 65 72 20 77 69 6c 6c 20 6d 61 6b  neither will mak
1aaa0 65 20 61 6e 79 20 70 72 6f 67 72 65 73 73 2e 20  e any progress. 
1aab0 20 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 53   Therefore,.** S
1aac0 51 4c 69 74 65 20 72 65 74 75 72 6e 73 20 5b 53  QLite returns [S
1aad0 51 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f 72 20  QLITE_BUSY] for 
1aae0 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73  the first proces
1aaf0 73 2c 20 68 6f 70 69 6e 67 20 74 68 61 74 20 74  s, hoping that t
1ab00 68 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 75  his.** will indu
1ab10 63 65 20 74 68 65 20 66 69 72 73 74 20 70 72 6f  ce the first pro
1ab20 63 65 73 73 20 74 6f 20 72 65 6c 65 61 73 65 20  cess to release 
1ab30 69 74 73 20 72 65 61 64 20 6c 6f 63 6b 20 61 6e  its read lock an
1ab40 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 73  d allow.** the s
1ab50 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 74 6f  econd process to
1ab60 20 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20   proceed..**.** 
1ab70 5e 54 68 65 20 64 65 66 61 75 6c 74 20 62 75 73  ^The default bus
1ab80 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55  y callback is NU
1ab90 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72  LL..**.** ^(Ther
1aba0 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20  e can only be a 
1abb0 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64  single busy hand
1abc0 6c 65 72 20 64 65 66 69 6e 65 64 20 66 6f 72 20  ler defined for 
1abd0 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73  each.** [databas
1abe0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20  e connection].  
1abf0 53 65 74 74 69 6e 67 20 61 20 6e 65 77 20 62 75  Setting a new bu
1ac00 73 79 20 68 61 6e 64 6c 65 72 20 63 6c 65 61 72  sy handler clear
1ac10 73 20 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f 75  s any.** previou
1ac20 73 6c 79 20 73 65 74 20 68 61 6e 64 6c 65 72 2e  sly set handler.
1ac30 29 5e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 63  )^  ^Note that c
1ac40 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
1ac50 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 0a  busy_timeout()].
1ac60 2a 2a 20 6f 72 20 65 76 61 6c 75 61 74 69 6e 67  ** or evaluating
1ac70 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f 74 69   [PRAGMA busy_ti
1ac80 6d 65 6f 75 74 3d 4e 5d 20 77 69 6c 6c 20 63 68  meout=N] will ch
1ac90 61 6e 67 65 20 74 68 65 0a 2a 2a 20 62 75 73 79  ange the.** busy
1aca0 20 68 61 6e 64 6c 65 72 20 61 6e 64 20 74 68 75   handler and thu
1acb0 73 20 63 6c 65 61 72 20 61 6e 79 20 70 72 65 76  s clear any prev
1acc0 69 6f 75 73 6c 79 20 73 65 74 20 62 75 73 79 20  iously set busy 
1acd0 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54  handler..**.** T
1ace0 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  he busy callback
1acf0 20 73 68 6f 75 6c 64 20 6e 6f 74 20 74 61 6b 65   should not take
1ad00 20 61 6e 79 20 61 63 74 69 6f 6e 73 20 77 68 69   any actions whi
1ad10 63 68 20 6d 6f 64 69 66 79 20 74 68 65 0a 2a 2a  ch modify the.**
1ad20 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1ad30 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65  tion that invoke
1ad40 64 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  d the busy handl
1ad50 65 72 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f  er.  In other wo
1ad60 72 64 73 2c 0a 2a 2a 20 74 68 65 20 62 75 73 79  rds,.** the busy
1ad70 20 68 61 6e 64 6c 65 72 20 69 73 20 6e 6f 74 20   handler is not 
1ad80 72 65 65 6e 74 72 61 6e 74 2e 20 20 41 6e 79 20  reentrant.  Any 
1ad90 73 75 63 68 20 61 63 74 69 6f 6e 73 0a 2a 2a 20  such actions.** 
1ada0 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69  result in undefi
1adb0 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a  ned behavior..**
1adc0 20 0a 2a 2a 20 41 20 62 75 73 79 20 68 61 6e 64   .** A busy hand
1add0 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f  ler must not clo
1ade0 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  se the database 
1adf0 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72  connection.** or
1ae00 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
1ae10 6d 65 6e 74 5d 20 74 68 61 74 20 69 6e 76 6f 6b  ment] that invok
1ae20 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ed the busy hand
1ae30 6c 65 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ler..*/.SQLITE_A
1ae40 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  PI int sqlite3_b
1ae50 75 73 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69  usy_handler(sqli
1ae60 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69  te3*, int(*)(voi
1ae70 64 2a 2c 69 6e 74 29 2c 20 76 6f 69 64 2a 29 3b  d*,int), void*);
1ae80 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1ae90 3a 20 53 65 74 20 41 20 42 75 73 79 20 54 69 6d  : Set A Busy Tim
1aea0 65 6f 75 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  eout.**.** ^This
1aeb0 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20   routine sets a 
1aec0 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61  [sqlite3_busy_ha
1aed0 6e 64 6c 65 72 20 7c 20 62 75 73 79 20 68 61 6e  ndler | busy han
1aee0 64 6c 65 72 5d 20 74 68 61 74 20 73 6c 65 65 70  dler] that sleep
1aef0 73 0a 2a 2a 20 66 6f 72 20 61 20 73 70 65 63 69  s.** for a speci
1af00 66 69 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74  fied amount of t
1af10 69 6d 65 20 77 68 65 6e 20 61 20 74 61 62 6c 65  ime when a table
1af20 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20 5e 54 68   is locked.  ^Th
1af30 65 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c  e handler.** wil
1af40 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65  l sleep multiple
1af50 20 74 69 6d 65 73 20 75 6e 74 69 6c 20 61 74 20   times until at 
1af60 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69  least "ms" milli
1af70 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70  seconds of sleep
1af80 69 6e 67 0a 2a 2a 20 68 61 76 65 20 61 63 63 75  ing.** have accu
1af90 6d 75 6c 61 74 65 64 2e 20 20 5e 41 66 74 65 72  mulated.  ^After
1afa0 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d   at least "ms" m
1afb0 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73  illiseconds of s
1afc0 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74 68 65 20  leeping,.** the 
1afd0 68 61 6e 64 6c 65 72 20 72 65 74 75 72 6e 73 20  handler returns 
1afe0 30 20 77 68 69 63 68 20 63 61 75 73 65 73 20 5b  0 which causes [
1aff0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
1b000 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51  to return.** [SQ
1b010 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 0a 2a  LITE_BUSY]..**.*
1b020 2a 20 5e 43 61 6c 6c 69 6e 67 20 74 68 69 73 20  * ^Calling this 
1b030 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 6e 20  routine with an 
1b040 61 72 67 75 6d 65 6e 74 20 6c 65 73 73 20 74 68  argument less th
1b050 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a  an or equal to z
1b060 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66  ero.** turns off
1b070 20 61 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c 65   all busy handle
1b080 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72  rs..**.** ^(Ther
1b090 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20  e can only be a 
1b0a0 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64  single busy hand
1b0b0 6c 65 72 20 66 6f 72 20 61 20 70 61 72 74 69 63  ler for a partic
1b0c0 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73  ular.** [databas
1b0d0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74  e connection] at
1b0e0 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f 6d 65 6e   any given momen
1b0f0 74 2e 20 20 49 66 20 61 6e 6f 74 68 65 72 20 62  t.  If another b
1b100 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77  usy handler.** w
1b110 61 73 20 64 65 66 69 6e 65 64 20 20 28 75 73 69  as defined  (usi
1b120 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79  ng [sqlite3_busy
1b130 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20 70 72 69  _handler()]) pri
1b140 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a  or to calling.**
1b150 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 74   this routine, t
1b160 68 61 74 20 6f 74 68 65 72 20 62 75 73 79 20 68  hat other busy h
1b170 61 6e 64 6c 65 72 20 69 73 20 63 6c 65 61 72 65  andler is cleare
1b180 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  d.)^.**.** See a
1b190 6c 73 6f 3a 20 20 5b 50 52 41 47 4d 41 20 62 75  lso:  [PRAGMA bu
1b1a0 73 79 5f 74 69 6d 65 6f 75 74 5d 0a 2a 2f 0a 53  sy_timeout].*/.S
1b1b0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
1b1c0 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f  lite3_busy_timeo
1b1d0 75 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  ut(sqlite3*, int
1b1e0 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50   ms);../*.** CAP
1b1f0 49 33 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65 6e  I3REF: Convenien
1b200 63 65 20 52 6f 75 74 69 6e 65 73 20 46 6f 72 20  ce Routines For 
1b210 52 75 6e 6e 69 6e 67 20 51 75 65 72 69 65 73 0a  Running Queries.
1b220 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 20  **.** This is a 
1b230 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65  legacy interface
1b240 20 74 68 61 74 20 69 73 20 70 72 65 73 65 72 76   that is preserv
1b250 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73  ed for backwards
1b260 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a   compatibility..
1b270 2a 2a 20 55 73 65 20 6f 66 20 74 68 69 73 20 69  ** Use of this i
1b280 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20  nterface is not 
1b290 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a  recommended..**.
1b2a0 2a 2a 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20 41  ** Definition: A
1b2b0 20 3c 62 3e 72 65 73 75 6c 74 20 74 61 62 6c 65   <b>result table
1b2c0 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20 64  </b> is memory d
1b2d0 61 74 61 20 73 74 72 75 63 74 75 72 65 20 63 72  ata structure cr
1b2e0 65 61 74 65 64 20 62 79 20 74 68 65 0a 2a 2a 20  eated by the.** 
1b2f0 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62  [sqlite3_get_tab
1b300 6c 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  le()] interface.
1b310 20 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65    A result table
1b320 20 72 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a 20   records the.** 
1b330 63 6f 6d 70 6c 65 74 65 20 71 75 65 72 79 20 72  complete query r
1b340 65 73 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65 20  esults from one 
1b350 6f 72 20 6d 6f 72 65 20 71 75 65 72 69 65 73 2e  or more queries.
1b360 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65  .**.** The table
1b370 20 63 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68 61   conceptually ha
1b380 73 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f  s a number of ro
1b390 77 73 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20  ws and columns. 
1b3a0 20 42 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e 75   But.** these nu
1b3b0 6d 62 65 72 73 20 61 72 65 20 6e 6f 74 20 70 61  mbers are not pa
1b3c0 72 74 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  rt of the result
1b3d0 20 74 61 62 6c 65 20 69 74 73 65 6c 66 2e 20 20   table itself.  
1b3e0 54 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72 73  These.** numbers
1b3f0 20 61 72 65 20 6f 62 74 61 69 6e 65 64 20 73 65   are obtained se
1b400 70 61 72 61 74 65 6c 79 2e 20 20 4c 65 74 20 4e  parately.  Let N
1b410 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   be the number o
1b420 66 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d 20  f rows.** and M 
1b430 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  be the number of
1b440 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20   columns..**.** 
1b450 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69  A result table i
1b460 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f  s an array of po
1b470 69 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74  inters to zero-t
1b480 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20  erminated UTF-8 
1b490 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 72  strings..** Ther
1b4a0 65 20 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65 6c  e are (N+1)*M el
1b4b0 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 61 72  ements in the ar
1b4c0 72 61 79 2e 20 20 54 68 65 20 66 69 72 73 74 20  ray.  The first 
1b4d0 4d 20 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e 74  M pointers point
1b4e0 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d  .** to zero-term
1b4f0 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74  inated strings t
1b500 68 61 74 20 20 63 6f 6e 74 61 69 6e 20 74 68 65  hat  contain the
1b510 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 20 63 6f   names of the co
1b520 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72 65  lumns..** The re
1b530 6d 61 69 6e 69 6e 67 20 65 6e 74 72 69 65 73 20  maining entries 
1b540 61 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75 65  all point to que
1b550 72 79 20 72 65 73 75 6c 74 73 2e 20 20 4e 55 4c  ry results.  NUL
1b560 4c 20 76 61 6c 75 65 73 20 72 65 73 75 6c 74 0a  L values result.
1b570 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74  ** in NULL point
1b580 65 72 73 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20  ers.  All other 
1b590 76 61 6c 75 65 73 20 61 72 65 20 69 6e 20 74 68  values are in th
1b5a0 65 69 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74  eir UTF-8 zero-t
1b5b0 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72  erminated.** str
1b5c0 69 6e 67 20 72 65 70 72 65 73 65 6e 74 61 74 69  ing representati
1b5d0 6f 6e 20 61 73 20 72 65 74 75 72 6e 65 64 20 62  on as returned b
1b5e0 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  y [sqlite3_colum
1b5f0 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a  n_text()]..**.**
1b600 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   A result table 
1b610 6d 69 67 68 74 20 63 6f 6e 73 69 73 74 20 6f 66  might consist of
1b620 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65 6d   one or more mem
1b630 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e  ory allocations.
1b640 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61  .** It is not sa
1b650 66 65 20 74 6f 20 70 61 73 73 20 61 20 72 65 73  fe to pass a res
1b660 75 6c 74 20 74 61 62 6c 65 20 64 69 72 65 63 74  ult table direct
1b670 6c 79 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66  ly to [sqlite3_f
1b680 72 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 73  ree()]..** A res
1b690 75 6c 74 20 74 61 62 6c 65 20 73 68 6f 75 6c 64  ult table should
1b6a0 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   be deallocated 
1b6b0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66  using [sqlite3_f
1b6c0 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a  ree_table()]..**
1b6d0 0a 2a 2a 20 5e 28 41 73 20 61 6e 20 65 78 61 6d  .** ^(As an exam
1b6e0 70 6c 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c  ple of the resul
1b6f0 74 20 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c 20  t table format, 
1b700 73 75 70 70 6f 73 65 20 61 20 71 75 65 72 79 20  suppose a query 
1b710 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73 20  result.** is as 
1b720 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c  follows:.**.** <
1b730 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
1b740 0a 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d 65 20  .**        Name 
1b750 20 20 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a 20         | Age.** 
1b760 20 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d         ---------
1b770 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a  --------------.*
1b780 2a 20 20 20 20 20 20 20 20 41 6c 69 63 65 20 20  *        Alice  
1b790 20 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20 20       | 43.**    
1b7a0 20 20 20 20 42 6f 62 20 20 20 20 20 20 20 20 20      Bob         
1b7b0 7c 20 32 38 0a 2a 2a 20 20 20 20 20 20 20 20 43  | 28.**        C
1b7c0 69 6e 64 79 20 20 20 20 20 20 20 7c 20 32 31 0a  indy       | 21.
1b7d0 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
1b7e0 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  quote>.**.** The
1b7f0 72 65 20 61 72 65 20 74 77 6f 20 63 6f 6c 75 6d  re are two colum
1b800 6e 20 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68 72  n (M==2) and thr
1b810 65 65 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e 20  ee rows (N==3). 
1b820 20 54 68 75 73 20 74 68 65 0a 2a 2a 20 72 65 73   Thus the.** res
1b830 75 6c 74 20 74 61 62 6c 65 20 68 61 73 20 38 20  ult table has 8 
1b840 65 6e 74 72 69 65 73 2e 20 20 53 75 70 70 6f 73  entries.  Suppos
1b850 65 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62  e the result tab
1b860 6c 65 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a 20  le is stored.** 
1b870 69 6e 20 61 6e 20 61 72 72 61 79 20 6e 61 6d 65  in an array name
1b880 73 20 61 7a 52 65 73 75 6c 74 2e 20 20 54 68 65  s azResult.  The
1b890 6e 20 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64 73  n azResult holds
1b8a0 20 74 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a   this content:.*
1b8b0 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
1b8c0 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20  ><pre>.**       
1b8d0 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 30 5d   azResult&#91;0]
1b8e0 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20   = "Name";.**   
1b8f0 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
1b900 31 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 2a  1;1] = "Age";.**
1b910 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
1b920 26 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63 65  &#91;2] = "Alice
1b930 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
1b940 65 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20 22  esult&#91;3] = "
1b950 34 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  43";.**        a
1b960 7a 52 65 73 75 6c 74 26 23 39 31 3b 34 5d 20 3d  zResult&#91;4] =
1b970 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 20   "Bob";.**      
1b980 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 35    azResult&#91;5
1b990 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20 20  ] = "28";.**    
1b9a0 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
1b9b0 3b 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a 2a  ;6] = "Cindy";.*
1b9c0 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
1b9d0 74 26 23 39 31 3b 37 5d 20 3d 20 22 32 31 22 3b  t&#91;7] = "21";
1b9e0 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
1b9f0 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20  kquote>)^.**.** 
1ba00 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74  ^The sqlite3_get
1ba10 5f 74 61 62 6c 65 28 29 20 66 75 6e 63 74 69 6f  _table() functio
1ba20 6e 20 65 76 61 6c 75 61 74 65 73 20 6f 6e 65 20  n evaluates one 
1ba30 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69 63  or more.** semic
1ba40 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64 20 53  olon-separated S
1ba50 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e  QL statements in
1ba60 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e   the zero-termin
1ba70 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73 74  ated UTF-8.** st
1ba80 72 69 6e 67 20 6f 66 20 69 74 73 20 32 6e 64 20  ring of its 2nd 
1ba90 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65  parameter and re
1baa0 74 75 72 6e 73 20 61 20 72 65 73 75 6c 74 20 74  turns a result t
1bab0 61 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20 70  able to the.** p
1bac0 6f 69 6e 74 65 72 20 67 69 76 65 6e 20 69 6e 20  ointer given in 
1bad0 69 74 73 20 33 72 64 20 70 61 72 61 6d 65 74 65  its 3rd paramete
1bae0 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 74  r..**.** After t
1baf0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 68  he application h
1bb00 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68  as finished with
1bb10 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d   the result from
1bb20 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
1bb30 6c 65 28 29 2c 0a 2a 2a 20 69 74 20 6d 75 73 74  le(),.** it must
1bb40 20 70 61 73 73 20 74 68 65 20 72 65 73 75 6c 74   pass the result
1bb50 20 74 61 62 6c 65 20 70 6f 69 6e 74 65 72 20 74   table pointer t
1bb60 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74  o sqlite3_free_t
1bb70 61 62 6c 65 28 29 20 69 6e 20 6f 72 64 65 72 20  able() in order 
1bb80 74 6f 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74 68  to.** release th
1bb90 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 77 61  e memory that wa
1bba0 73 20 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65 63  s malloced.  Bec
1bbb0 61 75 73 65 20 6f 66 20 74 68 65 20 77 61 79 20  ause of the way 
1bbc0 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
1bbd0 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e  malloc()] happen
1bbe0 73 20 77 69 74 68 69 6e 20 73 71 6c 69 74 65 33  s within sqlite3
1bbf0 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 20 74 68  _get_table(), th
1bc00 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e  e calling.** fun
1bc10 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 74  ction must not t
1bc20 72 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c 69  ry to call [sqli
1bc30 74 65 33 5f 66 72 65 65 28 29 5d 20 64 69 72 65  te3_free()] dire
1bc40 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b  ctly.  Only.** [
1bc50 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62  sqlite3_free_tab
1bc60 6c 65 28 29 5d 20 69 73 20 61 62 6c 65 20 74 6f  le()] is able to
1bc70 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d   release the mem
1bc80 6f 72 79 20 70 72 6f 70 65 72 6c 79 20 61 6e 64  ory properly and
1bc90 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54   safely..**.** T
1bca0 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  he sqlite3_get_t
1bcb0 61 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65  able() interface
1bcc0 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20   is implemented 
1bcd0 61 73 20 61 20 77 72 61 70 70 65 72 20 61 72 6f  as a wrapper aro
1bce0 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  und.** [sqlite3_
1bcf0 65 78 65 63 28 29 5d 2e 20 20 54 68 65 20 73 71  exec()].  The sq
1bd00 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
1bd10 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e  ) routine does n
1bd20 6f 74 20 68 61 76 65 20 61 63 63 65 73 73 0a 2a  ot have access.*
1bd30 2a 20 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e 61  * to any interna
1bd40 6c 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65  l data structure
1bd50 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 49 74  s of SQLite.  It
1bd60 20 75 73 65 73 20 6f 6e 6c 79 20 74 68 65 20 70   uses only the p
1bd70 75 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66 61  ublic.** interfa
1bd80 63 65 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e  ce defined here.
1bd90 20 20 41 73 20 61 20 63 6f 6e 73 65 71 75 65 6e    As a consequen
1bda0 63 65 2c 20 65 72 72 6f 72 73 20 74 68 61 74 20  ce, errors that 
1bdb0 6f 63 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a 20  occur in the.** 
1bdc0 77 72 61 70 70 65 72 20 6c 61 79 65 72 20 6f 75  wrapper layer ou
1bdd0 74 73 69 64 65 20 6f 66 20 74 68 65 20 69 6e 74  tside of the int
1bde0 65 72 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f 65  ernal [sqlite3_e
1bdf0 78 65 63 28 29 5d 20 63 61 6c 6c 20 61 72 65 20  xec()] call are 
1be00 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65 64  not.** reflected
1be10 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63   in subsequent c
1be20 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
1be30 5f 65 72 72 63 6f 64 65 28 29 5d 20 6f 72 0a 2a  _errcode()] or.*
1be40 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  * [sqlite3_errms
1be50 67 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  g()]..*/.SQLITE_
1be60 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
1be70 67 65 74 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c  get_table(.  sql
1be80 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
1be90 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61     /* An open da
1bea0 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73  tabase */.  cons
1beb0 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20  t char *zSql,   
1bec0 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65    /* SQL to be e
1bed0 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63 68  valuated */.  ch
1bee0 61 72 20 2a 2a 2a 70 61 7a 52 65 73 75 6c 74 2c  ar ***pazResult,
1bef0 20 20 20 20 2f 2a 20 52 65 73 75 6c 74 73 20 6f      /* Results o
1bf00 66 20 74 68 65 20 71 75 65 72 79 20 2a 2f 0a 20  f the query */. 
1bf10 20 69 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 20 20   int *pnRow,    
1bf20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72         /* Number
1bf30 20 6f 66 20 72 65 73 75 6c 74 20 72 6f 77 73 20   of result rows 
1bf40 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a  written here */.
1bf50 20 20 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c    int *pnColumn,
1bf60 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65          /* Numbe
1bf70 72 20 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c 75  r of result colu
1bf80 6d 6e 73 20 77 72 69 74 74 65 6e 20 68 65 72 65  mns written here
1bf90 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45   */.  char **pzE
1bfa0 72 72 6d 73 67 20 20 20 20 20 20 20 2f 2a 20 45  rrmsg       /* E
1bfb0 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e  rror msg written
1bfc0 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 53 51 4c 49   here */.);.SQLI
1bfd0 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69  TE_API void sqli
1bfe0 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 63  te3_free_table(c
1bff0 68 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a  har **result);..
1c000 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1c010 46 6f 72 6d 61 74 74 65 64 20 53 74 72 69 6e 67  Formatted String
1c020 20 50 72 69 6e 74 69 6e 67 20 46 75 6e 63 74 69   Printing Functi
1c030 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ons.**.** These 
1c040 72 6f 75 74 69 6e 65 73 20 61 72 65 20 77 6f 72  routines are wor
1c050 6b 2d 61 6c 69 6b 65 73 20 6f 66 20 74 68 65 20  k-alikes of the 
1c060 22 70 72 69 6e 74 66 28 29 22 20 66 61 6d 69 6c  "printf()" famil
1c070 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a  y of functions.*
1c080 2a 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64  * from the stand
1c090 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a  ard C library..*
1c0a0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1c0b0 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20  3_mprintf() and 
1c0c0 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66  sqlite3_vmprintf
1c0d0 28 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74  () routines writ
1c0e0 65 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c  e their.** resul
1c0f0 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f  ts into memory o
1c100 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
1c110 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e  lite3_malloc()].
1c120 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20  .** The strings 
1c130 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73  returned by thes
1c140 65 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73  e two routines s
1c150 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65  hould be.** rele
1c160 61 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  ased by [sqlite3
1c170 5f 66 72 65 65 28 29 5d 2e 20 20 5e 42 6f 74 68  _free()].  ^Both
1c180 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
1c190 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74   a.** NULL point
1c1a0 65 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d  er if [sqlite3_m
1c1b0 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61 62  alloc()] is unab
1c1c0 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65  le to allocate e
1c1d0 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20  nough.** memory 
1c1e0 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75  to hold the resu
1c1f0 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a  lting string..**
1c200 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65  .** ^(The sqlite
1c210 33 5f 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75  3_snprintf() rou
1c220 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20  tine is similar 
1c230 74 6f 20 22 73 6e 70 72 69 6e 74 66 28 29 22 20  to "snprintf()" 
1c240 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e  from.** the stan
1c250 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 20  dard C library. 
1c260 20 54 68 65 20 72 65 73 75 6c 74 20 69 73 20 77   The result is w
1c270 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a  ritten into the.
1c280 2a 2a 20 62 75 66 66 65 72 20 73 75 70 70 6c 69  ** buffer suppli
1c290 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
1c2a0 20 70 61 72 61 6d 65 74 65 72 20 77 68 6f 73 65   parameter whose
1c2b0 20 73 69 7a 65 20 69 73 20 67 69 76 65 6e 20 62   size is given b
1c2c0 79 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 70  y.** the first p
1c2d0 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74  arameter. Note t
1c2e0 68 61 74 20 74 68 65 20 6f 72 64 65 72 20 6f 66  hat the order of
1c2f0 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 77   the.** first tw
1c300 6f 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20  o parameters is 
1c310 72 65 76 65 72 73 65 64 20 66 72 6f 6d 20 73 6e  reversed from sn
1c320 70 72 69 6e 74 66 28 29 2e 29 5e 20 20 54 68 69  printf().)^  Thi
1c330 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f  s is an.** histo
1c340 72 69 63 61 6c 20 61 63 63 69 64 65 6e 74 20 74  rical accident t
1c350 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 66 69  hat cannot be fi
1c360 78 65 64 20 77 69 74 68 6f 75 74 20 62 72 65 61  xed without brea
1c370 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64  king.** backward
1c380 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  s compatibility.
1c390 20 20 5e 28 4e 6f 74 65 20 61 6c 73 6f 20 74 68    ^(Note also th
1c3a0 61 74 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  at sqlite3_snpri
1c3b0 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73  ntf().** returns
1c3c0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74   a pointer to it
1c3d0 73 20 62 75 66 66 65 72 20 69 6e 73 74 65 61 64  s buffer instead
1c3e0 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   of the number o
1c3f0 66 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20  f.** characters 
1c400 61 63 74 75 61 6c 6c 79 20 77 72 69 74 74 65 6e  actually written
1c410 20 69 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72   into the buffer
1c420 2e 29 5e 20 20 57 65 20 61 64 6d 69 74 20 74 68  .)^  We admit th
1c430 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  at.** the number
1c440 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 20 77   of characters w
1c450 72 69 74 74 65 6e 20 77 6f 75 6c 64 20 62 65 20  ritten would be 
1c460 61 20 6d 6f 72 65 20 75 73 65 66 75 6c 20 72 65  a more useful re
1c470 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75  turn.** value bu
1c480 74 20 77 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e  t we cannot chan
1c490 67 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74  ge the implement
1c4a0 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33  ation of sqlite3
1c4b0 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e  _snprintf().** n
1c4c0 6f 77 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b  ow without break
1c4d0 69 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  ing compatibilit
1c4e0 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e  y..**.** ^As lon
1c4f0 67 20 61 73 20 74 68 65 20 62 75 66 66 65 72 20  g as the buffer 
1c500 73 69 7a 65 20 69 73 20 67 72 65 61 74 65 72 20  size is greater 
1c510 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74  than zero, sqlit
1c520 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a  e3_snprintf().**
1c530 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74   guarantees that
1c540 20 74 68 65 20 62 75 66 66 65 72 20 69 73 20 61   the buffer is a
1c550 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69  lways zero-termi
1c560 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 66 69 72  nated.  ^The fir
1c570 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  st.** parameter 
1c580 22 6e 22 20 69 73 20 74 68 65 20 74 6f 74 61 6c  "n" is the total
1c590 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66   size of the buf
1c5a0 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73  fer, including s
1c5b0 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20  pace for.** the 
1c5c0 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e  zero terminator.
1c5d0 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74    So the longest
1c5e0 20 73 74 72 69 6e 67 20 74 68 61 74 20 63 61 6e   string that can
1c5f0 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a   be completely.*
1c600 2a 20 77 72 69 74 74 65 6e 20 77 69 6c 6c 20 62  * written will b
1c610 65 20 6e 2d 31 20 63 68 61 72 61 63 74 65 72 73  e n-1 characters
1c620 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
1c630 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 29  ite3_vsnprintf()
1c640 20 72 6f 75 74 69 6e 65 20 69 73 20 61 20 76 61   routine is a va
1c650 72 61 72 67 73 20 76 65 72 73 69 6f 6e 20 6f 66  rargs version of
1c660 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
1c670 66 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  f()..**.** These
1c680 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d   routines all im
1c690 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64  plement some add
1c6a0 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69  itional formatti
1c6b0 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68  ng.** options th
1c6c0 61 74 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f  at are useful fo
1c6d0 72 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 20 53  r constructing S
1c6e0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  QL statements..*
1c6f0 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 73 75  * All of the usu
1c700 61 6c 20 70 72 69 6e 74 66 28 29 20 66 6f 72 6d  al printf() form
1c710 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61  atting options a
1c720 70 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 69  pply.  In additi
1c730 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 20  on, there.** is 
1c740 61 72 65 20 22 25 71 22 2c 20 22 25 51 22 2c 20  are "%q", "%Q", 
1c750 61 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73  and "%z" options
1c760 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 71  ..**.** ^(The %q
1c770 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69   option works li
1c780 6b 65 20 25 73 20 69 6e 20 74 68 61 74 20 69 74  ke %s in that it
1c790 20 73 75 62 73 74 69 74 75 74 65 73 20 61 20 6e   substitutes a n
1c7a0 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ul-terminated.**
1c7b0 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 74 68 65   string from the
1c7c0 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20   argument list. 
1c7d0 20 42 75 74 20 25 71 20 61 6c 73 6f 20 64 6f 75   But %q also dou
1c7e0 62 6c 65 73 20 65 76 65 72 79 20 27 5c 27 27 20  bles every '\'' 
1c7f0 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71  character..** %q
1c800 20 69 73 20 64 65 73 69 67 6e 65 64 20 66 6f 72   is designed for
1c810 20 75 73 65 20 69 6e 73 69 64 65 20 61 20 73 74   use inside a st
1c820 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 29 5e 20  ring literal.)^ 
1c830 20 42 79 20 64 6f 75 62 6c 69 6e 67 20 65 61 63   By doubling eac
1c840 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61 72 61 63  h '\''.** charac
1c850 74 65 72 20 69 74 20 65 73 63 61 70 65 73 20 74  ter it escapes t
1c860 68 61 74 20 63 68 61 72 61 63 74 65 72 20 61 6e  hat character an
1c870 64 20 61 6c 6c 6f 77 73 20 69 74 20 74 6f 20 62  d allows it to b
1c880 65 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 0a  e inserted into.
1c890 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 2e 0a 2a  ** the string..*
1c8a0 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65  *.** For example
1c8b0 2c 20 61 73 73 75 6d 65 20 74 68 65 20 73 74 72  , assume the str
1c8c0 69 6e 67 20 76 61 72 69 61 62 6c 65 20 7a 54 65  ing variable zTe
1c8d0 78 74 20 63 6f 6e 74 61 69 6e 73 20 74 65 78 74  xt contains text
1c8e0 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a   as follows:.**.
1c8f0 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
1c900 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a  pre>.**  char *z
1c910 54 65 78 74 20 3d 20 22 49 74 27 73 20 61 20 68  Text = "It's a h
1c920 61 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c  appy day!";.** <
1c930 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1c940 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e  e>.**.** One can
1c950 20 75 73 65 20 74 68 69 73 20 74 65 78 74 20 69   use this text i
1c960 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  n an SQL stateme
1c970 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a  nt as follows:.*
1c980 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
1c990 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20  ><pre>.**  char 
1c9a0 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f  *zSQL = sqlite3_
1c9b0 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20  mprintf("INSERT 
1c9c0 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45  INTO table VALUE
1c9d0 53 28 27 25 71 27 29 22 2c 20 7a 54 65 78 74 29  S('%q')", zText)
1c9e0 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78  ;.**  sqlite3_ex
1c9f0 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20  ec(db, zSQL, 0, 
1ca00 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74  0, 0);.**  sqlit
1ca10 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a  e3_free(zSQL);.*
1ca20 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
1ca30 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61  uote>.**.** Beca
1ca40 75 73 65 20 74 68 65 20 25 71 20 66 6f 72 6d 61  use the %q forma
1ca50 74 20 73 74 72 69 6e 67 20 69 73 20 75 73 65 64  t string is used
1ca60 2c 20 74 68 65 20 27 5c 27 27 20 63 68 61 72 61  , the '\'' chara
1ca70 63 74 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a  cter in zText.**
1ca80 20 69 73 20 65 73 63 61 70 65 64 20 61 6e 64 20   is escaped and 
1ca90 74 68 65 20 53 51 4c 20 67 65 6e 65 72 61 74 65  the SQL generate
1caa0 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a  d is as follows:
1cab0 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
1cac0 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53  te><pre>.**  INS
1cad0 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20  ERT INTO table1 
1cae0 56 41 4c 55 45 53 28 27 49 74 27 27 73 20 61 20  VALUES('It''s a 
1caf0 68 61 70 70 79 20 64 61 79 21 27 29 0a 2a 2a 20  happy day!').** 
1cb00 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
1cb10 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69  te>.**.** This i
1cb20 73 20 63 6f 72 72 65 63 74 2e 20 20 48 61 64 20  s correct.  Had 
1cb30 77 65 20 75 73 65 64 20 25 73 20 69 6e 73 74 65  we used %s inste
1cb40 61 64 20 6f 66 20 25 71 2c 20 74 68 65 20 67 65  ad of %q, the ge
1cb50 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77  nerated SQL.** w
1cb60 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64  ould have looked
1cb70 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a   like this:.**.*
1cb80 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
1cb90 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49  re>.**  INSERT I
1cba0 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45  NTO table1 VALUE
1cbb0 53 28 27 49 74 27 73 20 61 20 68 61 70 70 79 20  S('It's a happy 
1cbc0 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65  day!');.** </pre
1cbd0 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
1cbe0 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e 64  *.** This second
1cbf0 20 65 78 61 6d 70 6c 65 20 69 73 20 61 6e 20 53   example is an S
1cc00 51 4c 20 73 79 6e 74 61 78 20 65 72 72 6f 72 2e  QL syntax error.
1cc10 20 20 41 73 20 61 20 67 65 6e 65 72 61 6c 20 72    As a general r
1cc20 75 6c 65 20 79 6f 75 20 73 68 6f 75 6c 64 0a 2a  ule you should.*
1cc30 2a 20 61 6c 77 61 79 73 20 75 73 65 20 25 71 20  * always use %q 
1cc40 69 6e 73 74 65 61 64 20 6f 66 20 25 73 20 77 68  instead of %s wh
1cc50 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 74 65 78  en inserting tex
1cc60 74 20 69 6e 74 6f 20 61 20 73 74 72 69 6e 67 20  t into a string 
1cc70 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e  literal..**.** ^
1cc80 28 54 68 65 20 25 51 20 6f 70 74 69 6f 6e 20 77  (The %Q option w
1cc90 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20 65 78 63  orks like %q exc
1cca0 65 70 74 20 69 74 20 61 6c 73 6f 20 61 64 64 73  ept it also adds
1ccb0 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 20 61   single quotes a
1ccc0 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f 75 74  round.** the out
1ccd0 73 69 64 65 20 6f 66 20 74 68 65 20 74 6f 74 61  side of the tota
1cce0 6c 20 73 74 72 69 6e 67 2e 20 20 41 64 64 69 74  l string.  Addit
1ccf0 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 74 68 65 20  ionally, if the 
1cd00 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65  parameter in the
1cd10 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6c 69 73  .** argument lis
1cd20 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  t is a NULL poin
1cd30 74 65 72 2c 20 25 51 20 73 75 62 73 74 69 74 75  ter, %Q substitu
1cd40 74 65 73 20 74 68 65 20 74 65 78 74 20 22 4e 55  tes the text "NU
1cd50 4c 4c 22 20 28 77 69 74 68 6f 75 74 0a 2a 2a 20  LL" (without.** 
1cd60 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 29 2e 29  single quotes).)
1cd70 5e 20 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70  ^  So, for examp
1cd80 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73 61  le, one could sa
1cd90 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  y:.**.** <blockq
1cda0 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63  uote><pre>.**  c
1cdb0 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69  har *zSQL = sqli
1cdc0 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53  te3_mprintf("INS
1cdd0 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56  ERT INTO table V
1cde0 41 4c 55 45 53 28 25 51 29 22 2c 20 7a 54 65 78  ALUES(%Q)", zTex
1cdf0 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f  t);.**  sqlite3_
1ce00 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30  exec(db, zSQL, 0
1ce10 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c  , 0, 0);.**  sql
1ce20 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b  ite3_free(zSQL);
1ce30 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
1ce40 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68  kquote>.**.** Th
1ce50 65 20 63 6f 64 65 20 61 62 6f 76 65 20 77 69 6c  e code above wil
1ce60 6c 20 72 65 6e 64 65 72 20 61 20 63 6f 72 72 65  l render a corre
1ce70 63 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ct SQL statement
1ce80 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a 20   in the zSQL.** 
1ce90 76 61 72 69 61 62 6c 65 20 65 76 65 6e 20 69 66  variable even if
1cea0 20 74 68 65 20 7a 54 65 78 74 20 76 61 72 69 61   the zText varia
1ceb0 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  ble is a NULL po
1cec0 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  inter..**.** ^(T
1ced0 68 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 74 69  he "%z" formatti
1cee0 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20  ng option works 
1cef0 6c 69 6b 65 20 22 25 73 22 20 62 75 74 20 77 69  like "%s" but wi
1cf00 74 68 20 74 68 65 0a 2a 2a 20 61 64 64 69 74 69  th the.** additi
1cf10 6f 6e 20 74 68 61 74 20 61 66 74 65 72 20 74 68  on that after th
1cf20 65 20 73 74 72 69 6e 67 20 68 61 73 20 62 65 65  e string has bee
1cf30 6e 20 72 65 61 64 20 61 6e 64 20 63 6f 70 69 65  n read and copie
1cf40 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65  d into.** the re
1cf50 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66  sult, [sqlite3_f
1cf60 72 65 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64  ree()] is called
1cf70 20 6f 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74   on the input st
1cf80 72 69 6e 67 2e 29 5e 0a 2a 2f 0a 53 51 4c 49 54  ring.)^.*/.SQLIT
1cf90 45 5f 41 50 49 20 63 68 61 72 20 2a 73 71 6c 69  E_API char *sqli
1cfa0 74 65 33 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73  te3_mprintf(cons
1cfb0 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 53 51  t char*,...);.SQ
1cfc0 4c 49 54 45 5f 41 50 49 20 63 68 61 72 20 2a 73  LITE_API char *s
1cfd0 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28  qlite3_vmprintf(
1cfe0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f  const char*, va_
1cff0 6c 69 73 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50  list);.SQLITE_AP
1d000 49 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  I char *sqlite3_
1d010 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61  snprintf(int,cha
1d020 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  r*,const char*, 
1d030 2e 2e 2e 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  ...);.SQLITE_API
1d040 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76   char *sqlite3_v
1d050 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61  snprintf(int,cha
1d060 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  r*,const char*, 
1d070 76 61 5f 6c 69 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a  va_list);../*.**
1d080 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72   CAPI3REF: Memor
1d090 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62  y Allocation Sub
1d0a0 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65  system.**.** The
1d0b0 20 53 51 4c 69 74 65 20 63 6f 72 65 20 75 73 65   SQLite core use
1d0c0 73 20 74 68 65 73 65 20 74 68 72 65 65 20 72 6f  s these three ro
1d0d0 75 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f  utines for all o
1d0e0 66 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74  f its own.** int
1d0f0 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c  ernal memory all
1d100 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20 22  ocation needs. "
1d110 43 6f 72 65 22 20 69 6e 20 74 68 65 20 70 72 65  Core" in the pre
1d120 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 0a 2a  vious sentence.*
1d130 2a 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75  * does not inclu
1d140 64 65 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73  de operating-sys
1d150 74 65 6d 20 73 70 65 63 69 66 69 63 20 56 46 53  tem specific VFS
1d160 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e   implementation.
1d170 20 20 54 68 65 0a 2a 2a 20 57 69 6e 64 6f 77 73    The.** Windows
1d180 20 56 46 53 20 75 73 65 73 20 6e 61 74 69 76 65   VFS uses native
1d190 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72   malloc() and fr
1d1a0 65 65 28 29 20 66 6f 72 20 73 6f 6d 65 20 6f 70  ee() for some op
1d1b0 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20  erations..**.** 
1d1c0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c  ^The sqlite3_mal
1d1d0 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65 20 72 65  loc() routine re
1d1e0 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
1d1f0 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66  to a block.** of
1d200 20 6d 65 6d 6f 72 79 20 61 74 20 6c 65 61 73 74   memory at least
1d210 20 4e 20 62 79 74 65 73 20 69 6e 20 6c 65 6e 67   N bytes in leng
1d220 74 68 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74  th, where N is t
1d230 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  he parameter..**
1d240 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c   ^If sqlite3_mal
1d250 6c 6f 63 28 29 20 69 73 20 75 6e 61 62 6c 65 20  loc() is unable 
1d260 74 6f 20 6f 62 74 61 69 6e 20 73 75 66 66 69 63  to obtain suffic
1d270 69 65 6e 74 20 66 72 65 65 0a 2a 2a 20 6d 65 6d  ient free.** mem
1d280 6f 72 79 2c 20 69 74 20 72 65 74 75 72 6e 73 20  ory, it returns 
1d290 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20  a NULL pointer. 
1d2a0 20 5e 49 66 20 74 68 65 20 70 61 72 61 6d 65 74   ^If the paramet
1d2b0 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  er N to.** sqlit
1d2c0 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 7a  e3_malloc() is z
1d2d0 65 72 6f 20 6f 72 20 6e 65 67 61 74 69 76 65 20  ero or negative 
1d2e0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d 61 6c  then sqlite3_mal
1d2f0 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a  loc() returns.**
1d300 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
1d310 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1d320 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 4e 29 20  te3_malloc64(N) 
1d330 72 6f 75 74 69 6e 65 20 77 6f 72 6b 73 20 6a 75  routine works ju
1d340 73 74 20 6c 69 6b 65 0a 2a 2a 20 73 71 6c 69 74  st like.** sqlit
1d350 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 65 78 63  e3_malloc(N) exc
1d360 65 70 74 20 74 68 61 74 20 4e 20 69 73 20 61 6e  ept that N is an
1d370 20 75 6e 73 69 67 6e 65 64 20 36 34 2d 62 69 74   unsigned 64-bit
1d380 20 69 6e 74 65 67 65 72 20 69 6e 73 74 65 61 64   integer instead
1d390 0a 2a 2a 20 6f 66 20 61 20 73 69 67 6e 65 64 20  .** of a signed 
1d3a0 33 32 2d 62 69 74 20 69 6e 74 65 67 65 72 2e 0a  32-bit integer..
1d3b0 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73  **.** ^Calling s
1d3c0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 77 69  qlite3_free() wi
1d3d0 74 68 20 61 20 70 6f 69 6e 74 65 72 20 70 72 65  th a pointer pre
1d3e0 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64  viously returned
1d3f0 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 6d  .** by sqlite3_m
1d400 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74  alloc() or sqlit
1d410 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c  e3_realloc() rel
1d420 65 61 73 65 73 20 74 68 61 74 20 6d 65 6d 6f 72  eases that memor
1d430 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20  y so.** that it 
1d440 6d 69 67 68 74 20 62 65 20 72 65 75 73 65 64 2e  might be reused.
1d450 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66    ^The sqlite3_f
1d460 72 65 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73  ree() routine is
1d470 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69  .** a no-op if i
1d480 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20  s called with a 
1d490 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50  NULL pointer.  P
1d4a0 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f  assing a NULL po
1d4b0 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69  inter.** to sqli
1d4c0 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 68 61  te3_free() is ha
1d4d0 72 6d 6c 65 73 73 2e 20 20 41 66 74 65 72 20 62  rmless.  After b
1d4e0 65 69 6e 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f  eing freed, memo
1d4f0 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69  ry.** should nei
1d500 74 68 65 72 20 62 65 20 72 65 61 64 20 6e 6f 72  ther be read nor
1d510 20 77 72 69 74 74 65 6e 2e 20 20 45 76 65 6e 20   written.  Even 
1d520 72 65 61 64 69 6e 67 20 70 72 65 76 69 6f 75 73  reading previous
1d530 6c 79 20 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f  ly freed.** memo
1d540 72 79 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20  ry might result 
1d550 69 6e 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f  in a segmentatio
1d560 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74 68 65 72  n fault or other
1d570 20 73 65 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a   severe error..*
1d580 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 72 75 70 74  * Memory corrupt
1d590 69 6f 6e 2c 20 61 20 73 65 67 6d 65 6e 74 61 74  ion, a segmentat
1d5a0 69 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74  ion fault, or ot
1d5b0 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72  her severe error
1d5c0 0a 2a 2a 20 6d 69 67 68 74 20 72 65 73 75 6c 74  .** might result
1d5d0 20 69 66 20 73 71 6c 69 74 65 33 5f 66 72 65 65   if sqlite3_free
1d5e0 28 29 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74  () is called wit
1d5f0 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69  h a non-NULL poi
1d600 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20 77 61 73  nter that.** was
1d610 20 6e 6f 74 20 6f 62 74 61 69 6e 65 64 20 66 72   not obtained fr
1d620 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  om sqlite3_mallo
1d630 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  c() or sqlite3_r
1d640 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20  ealloc()..**.** 
1d650 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 61  ^The sqlite3_rea
1d660 6c 6c 6f 63 28 58 2c 4e 29 20 69 6e 74 65 72 66  lloc(X,N) interf
1d670 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20  ace attempts to 
1d680 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f  resize a.** prio
1d690 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  r memory allocat
1d6a0 69 6f 6e 20 58 20 74 6f 20 62 65 20 61 74 20 6c  ion X to be at l
1d6b0 65 61 73 74 20 4e 20 62 79 74 65 73 2e 0a 2a 2a  east N bytes..**
1d6c0 20 5e 49 66 20 74 68 65 20 58 20 70 61 72 61 6d   ^If the X param
1d6d0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
1d6e0 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 0a 2a 2a 20  realloc(X,N).** 
1d6f0 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
1d700 72 20 74 68 65 6e 20 69 74 73 20 62 65 68 61 76  r then its behav
1d710 69 6f 72 20 69 73 20 69 64 65 6e 74 69 63 61 6c  ior is identical
1d720 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73   to calling.** s
1d730 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29  qlite3_malloc(N)
1d740 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e 20 70  ..** ^If the N p
1d750 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
1d760 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29  te3_realloc(X,N)
1d770 20 69 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e   is zero or.** n
1d780 65 67 61 74 69 76 65 20 74 68 65 6e 20 74 68 65  egative then the
1d790 20 62 65 68 61 76 69 6f 72 20 69 73 20 65 78 61   behavior is exa
1d7a0 63 74 6c 79 20 74 68 65 20 73 61 6d 65 20 61 73  ctly the same as
1d7b0 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69   calling.** sqli
1d7c0 74 65 33 5f 66 72 65 65 28 58 29 2e 0a 2a 2a 20  te3_free(X)..** 
1d7d0 5e 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  ^sqlite3_realloc
1d7e0 28 58 2c 4e 29 20 72 65 74 75 72 6e 73 20 61 20  (X,N) returns a 
1d7f0 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d  pointer to a mem
1d800 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  ory allocation.*
1d810 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e 20  * of at least N 
1d820 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 6f 72  bytes in size or
1d830 20 4e 55 4c 4c 20 69 66 20 69 6e 73 75 66 66 69   NULL if insuffi
1d840 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20  cient memory is 
1d850 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49  available..** ^I
1d860 66 20 4d 20 69 73 20 74 68 65 20 73 69 7a 65 20  f M is the size 
1d870 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c  of the prior all
1d880 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69  ocation, then mi
1d890 6e 28 4e 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20  n(N,M) bytes.** 
1d8a0 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c  of the prior all
1d8b0 6f 63 61 74 69 6f 6e 20 61 72 65 20 63 6f 70 69  ocation are copi
1d8c0 65 64 20 69 6e 74 6f 20 74 68 65 20 62 65 67 69  ed into the begi
1d8d0 6e 6e 69 6e 67 20 6f 66 20 62 75 66 66 65 72 20  nning of buffer 
1d8e0 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73  returned.** by s
1d8f0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58  qlite3_realloc(X
1d900 2c 4e 29 20 61 6e 64 20 74 68 65 20 70 72 69 6f  ,N) and the prio
1d910 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20  r allocation is 
1d920 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 73 71  freed..** ^If sq
1d930 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c  lite3_realloc(X,
1d940 4e 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20  N) returns NULL 
1d950 61 6e 64 20 4e 20 69 73 20 70 6f 73 69 74 69 76  and N is positiv
1d960 65 2c 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 70  e, then the.** p
1d970 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  rior allocation 
1d980 69 73 20 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a  is not freed..**
1d990 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1d9a0 5f 72 65 61 6c 6c 6f 63 36 34 28 58 2c 4e 29 20  _realloc64(X,N) 
1d9b0 69 6e 74 65 72 66 61 63 65 73 20 77 6f 72 6b 73  interfaces works
1d9c0 20 74 68 65 20 73 61 6d 65 20 61 73 0a 2a 2a 20   the same as.** 
1d9d0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1d9e0 58 2c 4e 29 20 65 78 63 65 70 74 20 74 68 61 74  X,N) except that
1d9f0 20 4e 20 69 73 20 61 20 36 34 2d 62 69 74 20 75   N is a 64-bit u
1da00 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20  nsigned integer 
1da10 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20  instead.** of a 
1da20 33 32 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e  32-bit signed in
1da30 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  teger..**.** ^If
1da40 20 58 20 69 73 20 61 20 6d 65 6d 6f 72 79 20 61   X is a memory a
1da50 6c 6c 6f 63 61 74 69 6f 6e 20 70 72 65 76 69 6f  llocation previo
1da60 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72  usly obtained fr
1da70 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  om sqlite3_mallo
1da80 63 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  c(),.** sqlite3_
1da90 6d 61 6c 6c 6f 63 36 34 28 29 2c 20 73 71 6c 69  malloc64(), sqli
1daa0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2c 20 6f  te3_realloc(), o
1dab0 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  r sqlite3_reallo
1dac0 63 36 34 28 29 2c 20 74 68 65 6e 0a 2a 2a 20 73  c64(), then.** s
1dad0 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20  qlite3_msize(X) 
1dae0 72 65 74 75 72 6e 73 20 74 68 65 20 73 69 7a 65  returns the size
1daf0 20 6f 66 20 74 68 61 74 20 6d 65 6d 6f 72 79 20   of that memory 
1db00 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 6e 20 62 79  allocation in by
1db10 74 65 73 2e 0a 2a 2a 20 5e 54 68 65 20 76 61 6c  tes..** ^The val
1db20 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ue returned by s
1db30 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20  qlite3_msize(X) 
1db40 6d 69 67 68 74 20 62 65 20 6c 61 72 67 65 72 20  might be larger 
1db50 74 68 61 6e 20 74 68 65 20 6e 75 6d 62 65 72 0a  than the number.
1db60 2a 2a 20 6f 66 20 62 79 74 65 73 20 72 65 71 75  ** of bytes requ
1db70 65 73 74 65 64 20 77 68 65 6e 20 58 20 77 61 73  ested when X was
1db80 20 61 6c 6c 6f 63 61 74 65 64 2e 20 20 5e 49 66   allocated.  ^If
1db90 20 58 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69   X is a NULL poi
1dba0 6e 74 65 72 20 74 68 65 6e 0a 2a 2a 20 73 71 6c  nter then.** sql
1dbb0 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 72 65  ite3_msize(X) re
1dbc0 74 75 72 6e 73 20 7a 65 72 6f 2e 20 20 49 66 20  turns zero.  If 
1dbd0 58 20 70 6f 69 6e 74 73 20 74 6f 20 73 6f 6d 65  X points to some
1dbe0 74 68 69 6e 67 20 74 68 61 74 20 69 73 20 6e 6f  thing that is no
1dbf0 74 0a 2a 2a 20 74 68 65 20 62 65 67 69 6e 6e 69  t.** the beginni
1dc00 6e 67 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c  ng of memory all
1dc10 6f 63 61 74 69 6f 6e 2c 20 6f 72 20 69 66 20 69  ocation, or if i
1dc20 74 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 66 6f  t points to a fo
1dc30 72 6d 65 72 6c 79 0a 2a 2a 20 76 61 6c 69 64 20  rmerly.** valid 
1dc40 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
1dc50 6e 20 74 68 61 74 20 68 61 73 20 6e 6f 77 20 62  n that has now b
1dc60 65 65 6e 20 66 72 65 65 64 2c 20 74 68 65 6e 20  een freed, then 
1dc70 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20  the behavior.** 
1dc80 6f 66 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65  of sqlite3_msize
1dc90 28 58 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64  (X) is undefined
1dca0 20 61 6e 64 20 70 6f 73 73 69 62 6c 79 20 68 61   and possibly ha
1dcb0 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  rmful..**.** ^Th
1dcc0 65 20 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e 65  e memory returne
1dcd0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c  d by sqlite3_mal
1dce0 6c 6f 63 28 29 2c 20 73 71 6c 69 74 65 33 5f 72  loc(), sqlite3_r
1dcf0 65 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c  ealloc(),.** sql
1dd00 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c  ite3_malloc64(),
1dd10 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 61   and sqlite3_rea
1dd20 6c 6c 6f 63 36 34 28 29 0a 2a 2a 20 69 73 20 61  lloc64().** is a
1dd30 6c 77 61 79 73 20 61 6c 69 67 6e 65 64 20 74 6f  lways aligned to
1dd40 20 61 74 20 6c 65 61 73 74 20 61 6e 20 38 20 62   at least an 8 b
1dd50 79 74 65 20 62 6f 75 6e 64 61 72 79 2c 20 6f 72  yte boundary, or
1dd60 20 74 6f 20 61 0a 2a 2a 20 34 20 62 79 74 65 20   to a.** 4 byte 
1dd70 62 6f 75 6e 64 61 72 79 20 69 66 20 74 68 65 20  boundary if the 
1dd80 5b 53 51 4c 49 54 45 5f 34 5f 42 59 54 45 5f 41  [SQLITE_4_BYTE_A
1dd90 4c 49 47 4e 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63  LIGNED_MALLOC] c
1dda0 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f  ompile-time.** o
1ddb0 70 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a  ption is used..*
1ddc0 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20 76  *.** In SQLite v
1ddd0 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64  ersion 3.5.0 and
1dde0 20 33 2e 35 2e 31 2c 20 69 74 20 77 61 73 20 70   3.5.1, it was p
1ddf0 6f 73 73 69 62 6c 65 20 74 6f 20 64 65 66 69 6e  ossible to defin
1de00 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49 54 45 5f  e.** the SQLITE_
1de10 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f  OMIT_MEMORY_ALLO
1de20 43 41 54 49 4f 4e 20 77 68 69 63 68 20 77 6f 75  CATION which wou
1de30 6c 64 20 63 61 75 73 65 20 74 68 65 20 62 75 69  ld cause the bui
1de40 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65  lt-in.** impleme
1de50 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 73 65  ntation of these
1de60 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20   routines to be 
1de70 6f 6d 69 74 74 65 64 2e 20 20 54 68 61 74 20 63  omitted.  That c
1de80 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20  apability.** is 
1de90 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64  no longer provid
1dea0 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d  ed.  Only built-
1deb0 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  in memory alloca
1dec0 74 6f 72 73 20 63 61 6e 20 62 65 20 75 73 65 64  tors can be used
1ded0 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72 20 74 6f  ..**.** Prior to
1dee0 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
1def0 33 2e 37 2e 31 30 2c 20 74 68 65 20 57 69 6e 64  3.7.10, the Wind
1df00 6f 77 73 20 4f 53 20 69 6e 74 65 72 66 61 63 65  ows OS interface
1df10 20 6c 61 79 65 72 20 63 61 6c 6c 65 64 0a 2a 2a   layer called.**
1df20 20 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c   the system mall
1df30 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20  oc() and free() 
1df40 64 69 72 65 63 74 6c 79 20 77 68 65 6e 20 63 6f  directly when co
1df50 6e 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65  nverting.** file
1df60 6e 61 6d 65 73 20 62 65 74 77 65 65 6e 20 74 68  names between th
1df70 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67  e UTF-8 encoding
1df80 20 75 73 65 64 20 62 79 20 53 51 4c 69 74 65 0a   used by SQLite.
1df90 2a 2a 20 61 6e 64 20 77 68 61 74 65 76 65 72 20  ** and whatever 
1dfa0 66 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e  filename encodin
1dfb0 67 20 69 73 20 75 73 65 64 20 62 79 20 74 68 65  g is used by the
1dfc0 20 70 61 72 74 69 63 75 6c 61 72 20 57 69 6e 64   particular Wind
1dfd0 6f 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74  ows.** installat
1dfe0 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c  ion.  Memory all
1dff0 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 73 20 77  ocation errors w
1e000 65 72 65 20 64 65 74 65 63 74 65 64 2c 20 62 75  ere detected, bu
1e010 74 0a 2a 2a 20 74 68 65 79 20 77 65 72 65 20 72  t.** they were r
1e020 65 70 6f 72 74 65 64 20 62 61 63 6b 20 61 73 20  eported back as 
1e030 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e  [SQLITE_CANTOPEN
1e040 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ] or.** [SQLITE_
1e050 49 4f 45 52 52 5d 20 72 61 74 68 65 72 20 74 68  IOERR] rather th
1e060 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  an [SQLITE_NOMEM
1e070 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69  ]..**.** The poi
1e080 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 73 20 74  nter arguments t
1e090 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  o [sqlite3_free(
1e0a0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
1e0b0 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75  realloc()].** mu
1e0c0 73 74 20 62 65 20 65 69 74 68 65 72 20 4e 55 4c  st be either NUL
1e0d0 4c 20 6f 72 20 65 6c 73 65 20 70 6f 69 6e 74 65  L or else pointe
1e0e0 72 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  rs obtained from
1e0f0 20 61 20 70 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f   a prior.** invo
1e100 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74  cation of [sqlit
1e110 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20  e3_malloc()] or 
1e120 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
1e130 28 29 5d 20 74 68 61 74 20 68 61 76 65 0a 2a 2a  ()] that have.**
1e140 20 6e 6f 74 20 79 65 74 20 62 65 65 6e 20 72 65   not yet been re
1e150 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  leased..**.** Th
1e160 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
1e170 73 74 20 6e 6f 74 20 72 65 61 64 20 6f 72 20 77  st not read or w
1e180 72 69 74 65 20 61 6e 79 20 70 61 72 74 20 6f 66  rite any part of
1e190 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d  .** a block of m
1e1a0 65 6d 6f 72 79 20 61 66 74 65 72 20 69 74 20 68  emory after it h
1e1b0 61 73 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64  as been released
1e1c0 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
1e1d0 65 33 5f 66 72 65 65 28 29 5d 20 6f 72 20 5b 73  e3_free()] or [s
1e1e0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1e1f0 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  ]..*/.SQLITE_API
1e200 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d   void *sqlite3_m
1e210 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 53 51 4c 49  alloc(int);.SQLI
1e220 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c  TE_API void *sql
1e230 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 73 71  ite3_malloc64(sq
1e240 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a 53  lite3_uint64);.S
1e250 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a  QLITE_API void *
1e260 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1e270 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c  void*, int);.SQL
1e280 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71  ITE_API void *sq
1e290 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28  lite3_realloc64(
1e2a0 76 6f 69 64 2a 2c 20 73 71 6c 69 74 65 33 5f 75  void*, sqlite3_u
1e2b0 69 6e 74 36 34 29 3b 0a 53 51 4c 49 54 45 5f 41  int64);.SQLITE_A
1e2c0 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  PI void sqlite3_
1e2d0 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a 53 51 4c  free(void*);.SQL
1e2e0 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f  ITE_API sqlite3_
1e2f0 75 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d  uint64 sqlite3_m
1e300 73 69 7a 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a  size(void*);../*
1e310 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65  .** CAPI3REF: Me
1e320 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53  mory Allocator S
1e330 74 61 74 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20  tatistics.**.** 
1e340 53 51 4c 69 74 65 20 70 72 6f 76 69 64 65 73 20  SQLite provides 
1e350 74 68 65 73 65 20 74 77 6f 20 69 6e 74 65 72 66  these two interf
1e360 61 63 65 73 20 66 6f 72 20 72 65 70 6f 72 74 69  aces for reporti
1e370 6e 67 20 6f 6e 20 74 68 65 20 73 74 61 74 75 73  ng on the status
1e380 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  .** of the [sqli
1e390 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b  te3_malloc()], [
1e3a0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2c  sqlite3_free()],
1e3b0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65   and [sqlite3_re
1e3c0 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74  alloc()].** rout
1e3d0 69 6e 65 73 2c 20 77 68 69 63 68 20 66 6f 72 6d  ines, which form
1e3e0 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65   the built-in me
1e3f0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
1e400 73 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a  subsystem..**.**
1e410 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d   ^The [sqlite3_m
1e420 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 72 6f  emory_used()] ro
1e430 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
1e440 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
1e450 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 63  s.** of memory c
1e460 75 72 72 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e  urrently outstan
1e470 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62  ding (malloced b
1e480 75 74 20 6e 6f 74 20 66 72 65 65 64 29 2e 0a 2a  ut not freed)..*
1e490 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  * ^The [sqlite3_
1e4a0 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
1e4b0 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75  ()] routine retu
1e4c0 72 6e 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a  rns the maximum.
1e4d0 2a 2a 20 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c  ** value of [sql
1e4e0 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
1e4f0 28 29 5d 20 73 69 6e 63 65 20 74 68 65 20 68 69  ()] since the hi
1e500 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a  gh-water mark.**
1e510 20 77 61 73 20 6c 61 73 74 20 72 65 73 65 74 2e   was last reset.
1e520 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65    ^The values re
1e530 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
1e540 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
1e550 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  ] and.** [sqlite
1e560 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
1e570 65 72 28 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e  er()] include an
1e580 79 20 6f 76 65 72 68 65 61 64 0a 2a 2a 20 61 64  y overhead.** ad
1e590 64 65 64 20 62 79 20 53 51 4c 69 74 65 20 69 6e  ded by SQLite in
1e5a0 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74   its implementat
1e5b0 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ion of [sqlite3_
1e5c0 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75  malloc()],.** bu
1e5d0 74 20 6e 6f 74 20 6f 76 65 72 68 65 61 64 20 61  t not overhead a
1e5e0 64 64 65 64 20 62 79 20 74 68 65 20 61 6e 79 20  dded by the any 
1e5f0 75 6e 64 65 72 6c 79 69 6e 67 20 73 79 73 74 65  underlying syste
1e600 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20 72 6f 75  m library.** rou
1e610 74 69 6e 65 73 20 74 68 61 74 20 5b 73 71 6c 69  tines that [sqli
1e620 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61  te3_malloc()] ma
1e630 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54  y call..**.** ^T
1e640 68 65 20 6d 65 6d 6f 72 79 20 68 69 67 68 2d 77  he memory high-w
1e650 61 74 65 72 20 6d 61 72 6b 20 69 73 20 72 65 73  ater mark is res
1e660 65 74 20 74 6f 20 74 68 65 20 63 75 72 72 65 6e  et to the curren
1e670 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73  t value of.** [s
1e680 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
1e690 65 64 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c  ed()] if and onl
1e6a0 79 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74  y if the paramet
1e6b0 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  er to.** [sqlite
1e6c0 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
1e6d0 65 72 28 29 5d 20 69 73 20 74 72 75 65 2e 20 20  er()] is true.  
1e6e0 5e 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 72  ^The value retur
1e6f0 6e 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74  ned.** by [sqlit
1e700 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
1e710 74 65 72 28 31 29 5d 20 69 73 20 74 68 65 20 68  ter(1)] is the h
1e720 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a  igh-water mark.*
1e730 2a 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 72  * prior to the r
1e740 65 73 65 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  eset..*/.SQLITE_
1e750 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  API sqlite3_int6
1e760 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79  4 sqlite3_memory
1e770 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a 53 51 4c  _used(void);.SQL
1e780 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f  ITE_API sqlite3_
1e790 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65  int64 sqlite3_me
1e7a0 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 69  mory_highwater(i
1e7b0 6e 74 20 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a  nt resetFlag);..
1e7c0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1e7d0 50 73 65 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75  Pseudo-Random Nu
1e7e0 6d 62 65 72 20 47 65 6e 65 72 61 74 6f 72 0a 2a  mber Generator.*
1e7f0 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74  *.** SQLite cont
1e800 61 69 6e 73 20 61 20 68 69 67 68 2d 71 75 61 6c  ains a high-qual
1e810 69 74 79 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f  ity pseudo-rando
1e820 6d 20 6e 75 6d 62 65 72 20 67 65 6e 65 72 61 74  m number generat
1e830 6f 72 20 28 50 52 4e 47 29 20 75 73 65 64 20 74  or (PRNG) used t
1e840 6f 0a 2a 2a 20 73 65 6c 65 63 74 20 72 61 6e 64  o.** select rand
1e850 6f 6d 20 5b 52 4f 57 49 44 20 7c 20 52 4f 57 49  om [ROWID | ROWI
1e860 44 73 5d 20 77 68 65 6e 20 69 6e 73 65 72 74 69  Ds] when inserti
1e870 6e 67 20 6e 65 77 20 72 65 63 6f 72 64 73 20 69  ng new records i
1e880 6e 74 6f 20 61 20 74 61 62 6c 65 20 74 68 61 74  nto a table that
1e890 0a 2a 2a 20 61 6c 72 65 61 64 79 20 75 73 65 73  .** already uses
1e8a0 20 74 68 65 20 6c 61 72 67 65 73 74 20 70 6f 73   the largest pos
1e8b0 73 69 62 6c 65 20 5b 52 4f 57 49 44 5d 2e 20 20  sible [ROWID].  
1e8c0 54 68 65 20 50 52 4e 47 20 69 73 20 61 6c 73 6f  The PRNG is also
1e8d0 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65   used for.** the
1e8e0 20 62 75 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d   build-in random
1e8f0 28 29 20 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f  () and randomblo
1e900 62 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  b() SQL function
1e910 73 2e 20 20 54 68 69 73 20 69 6e 74 65 72 66 61  s.  This interfa
1e920 63 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70  ce allows.** app
1e930 6c 69 63 61 74 69 6f 6e 73 20 74 6f 20 61 63 63  lications to acc
1e940 65 73 73 20 74 68 65 20 73 61 6d 65 20 50 52 4e  ess the same PRN
1e950 47 20 66 6f 72 20 6f 74 68 65 72 20 70 75 72 70  G for other purp
1e960 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63  oses..**.** ^A c
1e970 61 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74  all to this rout
1e980 69 6e 65 20 73 74 6f 72 65 73 20 4e 20 62 79 74  ine stores N byt
1e990 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73  es of randomness
1e9a0 20 69 6e 74 6f 20 62 75 66 66 65 72 20 50 2e 0a   into buffer P..
1e9b0 2a 2a 20 5e 49 66 20 4e 20 69 73 20 6c 65 73 73  ** ^If N is less
1e9c0 20 74 68 61 6e 20 6f 6e 65 2c 20 74 68 65 6e 20   than one, then 
1e9d0 50 20 63 61 6e 20 62 65 20 61 20 4e 55 4c 4c 20  P can be a NULL 
1e9e0 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  pointer..**.** ^
1e9f0 49 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  If this routine 
1ea00 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 70 72 65  has not been pre
1ea10 76 69 6f 75 73 6c 79 20 63 61 6c 6c 65 64 20 6f  viously called o
1ea20 72 20 69 66 20 74 68 65 20 70 72 65 76 69 6f 75  r if the previou
1ea30 73 0a 2a 2a 20 63 61 6c 6c 20 68 61 64 20 4e 20  s.** call had N 
1ea40 6c 65 73 73 20 74 68 61 6e 20 6f 6e 65 2c 20 74  less than one, t
1ea50 68 65 6e 20 74 68 65 20 50 52 4e 47 20 69 73 20  hen the PRNG is 
1ea60 73 65 65 64 65 64 20 75 73 69 6e 67 20 72 61 6e  seeded using ran
1ea70 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6f 62 74 61 69  domness.** obtai
1ea80 6e 65 64 20 66 72 6f 6d 20 74 68 65 20 78 52 61  ned from the xRa
1ea90 6e 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20  ndomness method 
1eaa0 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b  of the default [
1eab0 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
1eac0 65 63 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ect..** ^If the 
1ead0 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f  previous call to
1eae0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 68 61   this routine ha
1eaf0 64 20 61 6e 20 4e 20 6f 66 20 31 20 6f 72 20 6d  d an N of 1 or m
1eb00 6f 72 65 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20  ore then.** the 
1eb10 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73  pseudo-randomnes
1eb20 73 20 69 73 20 67 65 6e 65 72 61 74 65 64 0a 2a  s is generated.*
1eb30 2a 20 69 6e 74 65 72 6e 61 6c 6c 79 20 61 6e 64  * internally and
1eb40 20 77 69 74 68 6f 75 74 20 72 65 63 6f 75 72 73   without recours
1eb50 65 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  e to the [sqlite
1eb60 33 5f 76 66 73 5d 20 78 52 61 6e 64 6f 6d 6e 65  3_vfs] xRandomne
1eb70 73 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2f  ss.** method..*/
1eb80 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
1eb90 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e   sqlite3_randomn
1eba0 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20  ess(int N, void 
1ebb0 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  *P);../*.** CAPI
1ebc0 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69  3REF: Compile-Ti
1ebd0 6d 65 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e  me Authorization
1ebe0 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a   Callbacks.**.**
1ebf0 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72   ^This routine r
1ec00 65 67 69 73 74 65 72 73 20 61 6e 20 61 75 74 68  egisters an auth
1ec10 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1ec20 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61  with a particula
1ec30 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  r.** [database c
1ec40 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70  onnection], supp
1ec50 6c 69 65 64 20 69 6e 20 74 68 65 20 66 69 72 73  lied in the firs
1ec60 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e  t argument..** ^
1ec70 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  The authorizer c
1ec80 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
1ec90 65 64 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d  ed as SQL statem
1eca0 65 6e 74 73 20 61 72 65 20 62 65 69 6e 67 20 63  ents are being c
1ecb0 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73  ompiled.** by [s
1ecc0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
1ecd0 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74  ] or its variant
1ece0 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  s [sqlite3_prepa
1ecf0 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71  re_v2()],.** [sq
1ed00 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
1ed10 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
1ed20 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e  prepare16_v2()].
1ed30 20 20 5e 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a    ^At various.**
1ed40 20 70 6f 69 6e 74 73 20 64 75 72 69 6e 67 20 74   points during t
1ed50 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70  he compilation p
1ed60 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67 69 63  rocess, as logic
1ed70 20 69 73 20 62 65 69 6e 67 20 63 72 65 61 74 65   is being create
1ed80 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20  d.** to perform 
1ed90 76 61 72 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c  various actions,
1eda0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
1edb0 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
1edc0 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66  ked to.** see if
1edd0 20 74 68 6f 73 65 20 61 63 74 69 6f 6e 73 20 61   those actions a
1ede0 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20 5e 54 68  re allowed.  ^Th
1edf0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
1ee00 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20  lback should.** 
1ee10 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f  return [SQLITE_O
1ee20 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20  K] to allow the 
1ee30 61 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f  action, [SQLITE_
1ee40 49 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c  IGNORE] to disal
1ee50 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65 63 69  low the.** speci
1ee60 66 69 63 20 61 63 74 69 6f 6e 20 62 75 74 20 61  fic action but a
1ee70 6c 6c 6f 77 20 74 68 65 20 53 51 4c 20 73 74 61  llow the SQL sta
1ee80 74 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e  tement to contin
1ee90 75 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70  ue to be.** comp
1eea0 69 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45  iled, or [SQLITE
1eeb0 5f 44 45 4e 59 5d 20 74 6f 20 63 61 75 73 65 20  _DENY] to cause 
1eec0 74 68 65 20 65 6e 74 69 72 65 20 53 51 4c 20 73  the entire SQL s
1eed0 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a  tatement to be.*
1eee0 2a 20 72 65 6a 65 63 74 65 64 20 77 69 74 68 20  * rejected with 
1eef0 61 6e 20 65 72 72 6f 72 2e 20 20 5e 49 66 20 74  an error.  ^If t
1ef00 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
1ef10 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a  llback returns.*
1ef20 2a 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65  * any value othe
1ef30 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49  r than [SQLITE_I
1ef40 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f  GNORE], [SQLITE_
1ef50 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  OK], or [SQLITE_
1ef60 44 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 68  DENY].** then th
1ef70 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  e [sqlite3_prepa
1ef80 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69  re_v2()] or equi
1ef90 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74  valent call that
1efa0 20 74 72 69 67 67 65 72 65 64 0a 2a 2a 20 74 68   triggered.** th
1efb0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c  e authorizer wil
1efc0 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65  l fail with an e
1efd0 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a  rror message..**
1efe0 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 63 61 6c  .** When the cal
1eff0 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53  lback returns [S
1f000 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20  QLITE_OK], that 
1f010 6d 65 61 6e 73 20 74 68 65 20 6f 70 65 72 61 74  means the operat
1f020 69 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 74 65 64  ion.** requested
1f030 20 69 73 20 6f 6b 2e 20 20 5e 57 68 65 6e 20 74   is ok.  ^When t
1f040 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
1f050 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59  rns [SQLITE_DENY
1f060 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ], the.** [sqlit
1f070 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
1f080 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63   or equivalent c
1f090 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72  all that trigger
1f0a0 65 64 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72  ed the.** author
1f0b0 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77  izer will fail w
1f0c0 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73  ith an error mes
1f0d0 73 61 67 65 20 65 78 70 6c 61 69 6e 69 6e 67 20  sage explaining 
1f0e0 74 68 61 74 0a 2a 2a 20 61 63 63 65 73 73 20 69  that.** access i
1f0f0 73 20 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a  s denied. .**.**
1f100 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61   ^The first para
1f110 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74  meter to the aut
1f120 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1f130 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68   is a copy of th
1f140 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d  e third.** param
1f150 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
1f160 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
1f170 65 72 28 29 20 69 6e 74 65 72 66 61 63 65 2e 20  er() interface. 
1f180 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61  ^The second para
1f190 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  meter.** to the 
1f1a0 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69  callback is an i
1f1b0 6e 74 65 67 65 72 20 5b 53 51 4c 49 54 45 5f 43  nteger [SQLITE_C
1f1c0 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64  OPY | action cod
1f1d0 65 5d 20 74 68 61 74 20 73 70 65 63 69 66 69 65  e] that specifie
1f1e0 73 0a 2a 2a 20 74 68 65 20 70 61 72 74 69 63 75  s.** the particu
1f1f0 6c 61 72 20 61 63 74 69 6f 6e 20 74 6f 20 62 65  lar action to be
1f200 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 5e 54 68   authorized. ^Th
1f210 65 20 74 68 69 72 64 20 74 68 72 6f 75 67 68 20  e third through 
1f220 73 69 78 74 68 20 70 61 72 61 6d 65 74 65 72 73  sixth parameters
1f230 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  .** to the callb
1f240 61 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74 65 72  ack are zero-ter
1f250 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20  minated strings 
1f260 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 61 64 64  that contain add
1f270 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61 69  itional.** detai
1f280 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61 63 74  ls about the act
1f290 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72  ion to be author
1f2a0 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ized..**.** ^If 
1f2b0 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20  the action code 
1f2c0 69 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d  is [SQLITE_READ]
1f2d0 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63 61 6c 6c  .** and the call
1f2e0 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51  back returns [SQ
1f2f0 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65  LITE_IGNORE] the
1f300 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  n the.** [prepar
1f310 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 73 74  ed statement] st
1f320 61 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74  atement is const
1f330 72 75 63 74 65 64 20 74 6f 20 73 75 62 73 74 69  ructed to substi
1f340 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76  tute.** a NULL v
1f350 61 6c 75 65 20 69 6e 20 70 6c 61 63 65 20 6f 66  alue in place of
1f360 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d   the table colum
1f370 6e 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76  n that would hav
1f380 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64 20 69  e.** been read i
1f390 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61  f [SQLITE_OK] ha
1f3a0 64 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64 2e  d been returned.
1f3b0 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 47    The [SQLITE_IG
1f3c0 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e 20  NORE].** return 
1f3d0 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 64  can be used to d
1f3e0 65 6e 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64  eny an untrusted
1f3f0 20 75 73 65 72 20 61 63 63 65 73 73 20 74 6f 20   user access to 
1f400 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63 6f  individual.** co
1f410 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c 65  lumns of a table
1f420 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74  ..** ^If the act
1f430 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c  ion code is [SQL
1f440 49 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20  ITE_DELETE] and 
1f450 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
1f460 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  urns.** [SQLITE_
1f470 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65  IGNORE] then the
1f480 20 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72 61 74   [DELETE] operat
1f490 69 6f 6e 20 70 72 6f 63 65 65 64 73 20 62 75 74  ion proceeds but
1f4a0 20 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74   the.** [truncat
1f4b0 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20  e optimization] 
1f4c0 69 73 20 64 69 73 61 62 6c 65 64 20 61 6e 64 20  is disabled and 
1f4d0 61 6c 6c 20 72 6f 77 73 20 61 72 65 20 64 65 6c  all rows are del
1f4e0 65 74 65 64 20 69 6e 64 69 76 69 64 75 61 6c 6c  eted individuall
1f4f0 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68  y..**.** An auth
1f500 6f 72 69 7a 65 72 20 69 73 20 75 73 65 64 20 77  orizer is used w
1f510 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  hen [sqlite3_pre
1f520 70 61 72 65 20 7c 20 70 72 65 70 61 72 69 6e 67  pare | preparing
1f530 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65  ].** SQL stateme
1f540 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72  nts from an untr
1f550 75 73 74 65 64 20 73 6f 75 72 63 65 2c 20 74 6f  usted source, to
1f560 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65   ensure that the
1f570 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
1f580 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f  ** do not try to
1f590 20 61 63 63 65 73 73 20 64 61 74 61 20 74 68 65   access data the
1f5a0 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65  y are not allowe
1f5b0 64 20 74 6f 20 73 65 65 2c 20 6f 72 20 74 68 61  d to see, or tha
1f5c0 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a  t they do not.**
1f5d0 20 74 72 79 20 74 6f 20 65 78 65 63 75 74 65 20   try to execute 
1f5e0 6d 61 6c 69 63 69 6f 75 73 20 73 74 61 74 65 6d  malicious statem
1f5f0 65 6e 74 73 20 74 68 61 74 20 64 61 6d 61 67 65  ents that damage
1f600 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 20   the database.  
1f610 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20  For.** example, 
1f620 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  an application m
1f630 61 79 20 61 6c 6c 6f 77 20 61 20 75 73 65 72 20  ay allow a user 
1f640 74 6f 20 65 6e 74 65 72 20 61 72 62 69 74 72 61  to enter arbitra
1f650 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69 65  ry.** SQL querie
1f660 73 20 66 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e  s for evaluation
1f670 20 62 79 20 61 20 64 61 74 61 62 61 73 65 2e 20   by a database. 
1f680 20 42 75 74 20 74 68 65 20 61 70 70 6c 69 63 61   But the applica
1f690 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74  tion does.** not
1f6a0 20 77 61 6e 74 20 74 68 65 20 75 73 65 72 20 74   want the user t
1f6b0 6f 20 62 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b  o be able to mak
1f6c0 65 20 61 72 62 69 74 72 61 72 79 20 63 68 61 6e  e arbitrary chan
1f6d0 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61  ges to the.** da
1f6e0 74 61 62 61 73 65 2e 20 20 41 6e 20 61 75 74 68  tabase.  An auth
1f6f0 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20 74 68 65  orizer could the
1f700 6e 20 62 65 20 70 75 74 20 69 6e 20 70 6c 61 63  n be put in plac
1f710 65 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75  e while the.** u
1f720 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 20  ser-entered SQL 
1f730 69 73 20 62 65 69 6e 67 20 5b 73 71 6c 69 74 65  is being [sqlite
1f740 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70  3_prepare | prep
1f750 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69  ared] that.** di
1f760 73 61 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 69  sallows everythi
1f770 6e 67 20 65 78 63 65 70 74 20 5b 53 45 4c 45 43  ng except [SELEC
1f780 54 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  T] statements..*
1f790 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e  *.** Application
1f7a0 73 20 74 68 61 74 20 6e 65 65 64 20 74 6f 20 70  s that need to p
1f7b0 72 6f 63 65 73 73 20 53 51 4c 20 66 72 6f 6d 20  rocess SQL from 
1f7c0 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65  untrusted source
1f7d0 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20  s.** might also 
1f7e0 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72 69 6e  consider lowerin
1f7f0 67 20 72 65 73 6f 75 72 63 65 20 6c 69 6d 69 74  g resource limit
1f800 73 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  s using [sqlite3
1f810 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64  _limit()].** and
1f820 20 6c 69 6d 69 74 69 6e 67 20 64 61 74 61 62 61   limiting databa
1f830 73 65 20 73 69 7a 65 20 75 73 69 6e 67 20 74 68  se size using th
1f840 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e  e [max_page_coun
1f850 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69  t] [PRAGMA].** i
1f860 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f 20 75 73  n addition to us
1f870 69 6e 67 20 61 6e 20 61 75 74 68 6f 72 69 7a 65  ing an authorize
1f880 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20  r..**.** ^(Only 
1f890 61 20 73 69 6e 67 6c 65 20 61 75 74 68 6f 72 69  a single authori
1f8a0 7a 65 72 20 63 61 6e 20 62 65 20 69 6e 20 70 6c  zer can be in pl
1f8b0 61 63 65 20 6f 6e 20 61 20 64 61 74 61 62 61 73  ace on a databas
1f8c0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
1f8d0 61 74 20 61 20 74 69 6d 65 2e 20 20 45 61 63 68  at a time.  Each
1f8e0 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
1f8f0 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20  _set_authorizer 
1f900 6f 76 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a  overrides the.**
1f910 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e 29   previous call.)
1f920 5e 20 20 5e 44 69 73 61 62 6c 65 20 74 68 65 20  ^  ^Disable the 
1f930 61 75 74 68 6f 72 69 7a 65 72 20 62 79 20 69 6e  authorizer by in
1f940 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20  stalling a NULL 
1f950 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65  callback..** The
1f960 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 64   authorizer is d
1f970 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  isabled by defau
1f980 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75  lt..**.** The au
1f990 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1f9a0 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e  k must not do an
1f9b0 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c  ything that will
1f9c0 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64   modify.** the d
1f9d0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1f9e0 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  on that invoked 
1f9f0 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
1fa00 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65  allback..** Note
1fa10 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70   that [sqlite3_p
1fa20 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
1fa30 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
1fa40 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68  ] both modify th
1fa50 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  eir.** database 
1fa60 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20  connections for 
1fa70 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22  the meaning of "
1fa80 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20  modify" in this 
1fa90 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a  paragraph..**.**
1faa0 20 5e 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f   ^When [sqlite3_
1fab0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 69 73  prepare_v2()] is
1fac0 20 75 73 65 64 20 74 6f 20 70 72 65 70 61 72 65   used to prepare
1fad0 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 20 74 68   a statement, th
1fae0 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d  e.** statement m
1faf0 69 67 68 74 20 62 65 20 72 65 2d 70 72 65 70 61  ight be re-prepa
1fb00 72 65 64 20 64 75 72 69 6e 67 20 5b 73 71 6c 69  red during [sqli
1fb10 74 65 33 5f 73 74 65 70 28 29 5d 20 64 75 65 20  te3_step()] due 
1fb20 74 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20  to a .** schema 
1fb30 63 68 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20  change.  Hence, 
1fb40 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
1fb50 73 68 6f 75 6c 64 20 65 6e 73 75 72 65 20 74 68  should ensure th
1fb60 61 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63  at the.** correc
1fb70 74 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  t authorizer cal
1fb80 6c 62 61 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e  lback remains in
1fb90 20 70 6c 61 63 65 20 64 75 72 69 6e 67 20 74 68   place during th
1fba0 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  e [sqlite3_step(
1fbb0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20  )]..**.** ^Note 
1fbc0 74 68 61 74 20 74 68 65 20 61 75 74 68 6f 72 69  that the authori
1fbd0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
1fbe0 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72  invoked only dur
1fbf0 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
1fc00 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74  prepare()] or it
1fc10 73 20 76 61 72 69 61 6e 74 73 2e 20 20 41 75 74  s variants.  Aut
1fc20 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f  horization is no
1fc30 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 64  t.** performed d
1fc40 75 72 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20  uring statement 
1fc50 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73  evaluation in [s
1fc60 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20  qlite3_step()], 
1fc70 75 6e 6c 65 73 73 0a 2a 2a 20 61 73 20 73 74 61  unless.** as sta
1fc80 74 65 64 20 69 6e 20 74 68 65 20 70 72 65 76 69  ted in the previ
1fc90 6f 75 73 20 70 61 72 61 67 72 61 70 68 2c 20 73  ous paragraph, s
1fca0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e  qlite3_step() in
1fcb0 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33  vokes.** sqlite3
1fcc0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 74 6f  _prepare_v2() to
1fcd0 20 72 65 70 72 65 70 61 72 65 20 61 20 73 74 61   reprepare a sta
1fce0 74 65 6d 65 6e 74 20 61 66 74 65 72 20 61 20 73  tement after a s
1fcf0 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 0a 2a 2f  chema change..*/
1fd00 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
1fd10 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
1fd20 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c 69 74 65  orizer(.  sqlite
1fd30 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75 74  3*,.  int (*xAut
1fd40 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  h)(void*,int,con
1fd50 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  st char*,const c
1fd60 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
1fd70 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20  ,const char*),. 
1fd80 20 76 6f 69 64 20 2a 70 55 73 65 72 44 61 74 61   void *pUserData
1fd90 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
1fda0 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20  REF: Authorizer 
1fdb0 52 65 74 75 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a  Return Codes.**.
1fdc0 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** The [sqlite3_
1fdd0 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c  set_authorizer |
1fde0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1fdf0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d  back function] m
1fe00 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69  ust.** return ei
1fe10 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  ther [SQLITE_OK]
1fe20 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 73 65   or one of these
1fe30 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69   two constants i
1fe40 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69  n order.** to si
1fe50 67 6e 61 6c 20 53 51 4c 69 74 65 20 77 68 65 74  gnal SQLite whet
1fe60 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 61  her or not the a
1fe70 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74  ction is permitt
1fe80 65 64 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20  ed.  See the.** 
1fe90 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
1fea0 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72  horizer | author
1feb0 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61 74 69  izer documentati
1fec0 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  on] for addition
1fed0 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  al.** informatio
1fee0 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68  n..**.** Note th
1fef0 61 74 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  at SQLITE_IGNORE
1ff00 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20 61 73   is also used as
1ff10 20 61 20 5b 63 6f 6e 66 6c 69 63 74 20 72 65 73   a [conflict res
1ff20 6f 6c 75 74 69 6f 6e 20 6d 6f 64 65 5d 0a 2a 2a  olution mode].**
1ff30 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 74   returned from t
1ff40 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 74 61 62  he [sqlite3_vtab
1ff50 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d 20  _on_conflict()] 
1ff60 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 64  interface..*/.#d
1ff70 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e  efine SQLITE_DEN
1ff80 59 20 20 20 31 20 20 20 2f 2a 20 41 62 6f 72 74  Y   1   /* Abort
1ff90 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
1ffa0 6e 74 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72  nt with an error
1ffb0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1ffc0 54 45 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a  TE_IGNORE 2   /*
1ffd0 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63   Don't allow acc
1ffe0 65 73 73 2c 20 62 75 74 20 64 6f 6e 27 74 20 67  ess, but don't g
1fff0 65 6e 65 72 61 74 65 20 61 6e 20 65 72 72 6f 72  enerate an error
20000 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
20010 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20  REF: Authorizer 
20020 41 63 74 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a  Action Codes.**.
20030 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** The [sqlite3_
20040 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29  set_authorizer()
20050 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69  ] interface regi
20060 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b  sters a callback
20070 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61   function.** tha
20080 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20  t is invoked to 
20090 61 75 74 68 6f 72 69 7a 65 20 63 65 72 74 61 69  authorize certai
200a0 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  n SQL statement 
200b0 61 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a  actions.  The.**
200c0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
200d0 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  r to the callbac
200e0 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  k is an integer 
200f0 63 6f 64 65 20 74 68 61 74 20 73 70 65 63 69 66  code that specif
20100 69 65 73 0a 2a 2a 20 77 68 61 74 20 61 63 74 69  ies.** what acti
20110 6f 6e 20 69 73 20 62 65 69 6e 67 20 61 75 74 68  on is being auth
20120 6f 72 69 7a 65 64 2e 20 20 54 68 65 73 65 20 61  orized.  These a
20130 72 65 20 74 68 65 20 69 6e 74 65 67 65 72 20 61  re the integer a
20140 63 74 69 6f 6e 20 63 6f 64 65 73 20 74 68 61 74  ction codes that
20150 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a  .** the authoriz
20160 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20  er callback may 
20170 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a  be passed..**.**
20180 20 54 68 65 73 65 20 61 63 74 69 6f 6e 20 63 6f   These action co
20190 64 65 20 76 61 6c 75 65 73 20 73 69 67 6e 69 66  de values signif
201a0 79 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f  y what kind of o
201b0 70 65 72 61 74 69 6f 6e 20 69 73 20 74 6f 20 62  peration is to b
201c0 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e  e.** authorized.
201d0 20 20 54 68 65 20 33 72 64 20 61 6e 64 20 34 74    The 3rd and 4t
201e0 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20  h parameters to 
201f0 74 68 65 20 61 75 74 68 6f 72 69 7a 61 74 69 6f  the authorizatio
20200 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75  n.** callback fu
20210 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70  nction will be p
20220 61 72 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c  arameters or NUL
20230 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77  L depending on w
20240 68 69 63 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a  hich of these.**
20250 20 63 6f 64 65 73 20 69 73 20 75 73 65 64 20 61   codes is used a
20260 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  s the second par
20270 61 6d 65 74 65 72 2e 20 20 5e 28 54 68 65 20 35  ameter.  ^(The 5
20280 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
20290 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65  the.** authorize
202a0 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68  r callback is th
202b0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61  e name of the da
202c0 74 61 62 61 73 65 20 28 22 6d 61 69 6e 22 2c 20  tabase ("main", 
202d0 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e 29  "temp",.** etc.)
202e0 20 69 66 20 61 70 70 6c 69 63 61 62 6c 65 2e 29   if applicable.)
202f0 5e 20 20 5e 54 68 65 20 36 74 68 20 70 61 72 61  ^  ^The 6th para
20300 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74  meter to the aut
20310 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
20320 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20  .** is the name 
20330 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73  of the inner-mos
20340 74 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 65  t trigger or vie
20350 77 20 74 68 61 74 20 69 73 20 72 65 73 70 6f 6e  w that is respon
20360 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65  sible for.** the
20370 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20   access attempt 
20380 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 20  or NULL if this 
20390 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 69  access attempt i
203a0 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a  s directly from.
203b0 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c  ** top-level SQL
203c0 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a   code..*/./*****
203d0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
203e0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
203f0 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a  ****** 3rd *****
20400 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a  ******* 4th ****
20410 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65  *******/.#define
20420 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 49   SQLITE_CREATE_I
20430 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 31 20  NDEX          1 
20440 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
20450 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20       Table Name 
20460 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
20470 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 41  SQLITE_CREATE_TA
20480 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 20 20  BLE          2  
20490 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
204a0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
204b0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
204c0 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d  QLITE_CREATE_TEM
204d0 50 5f 49 4e 44 45 58 20 20 20 20 20 33 20 20 20  P_INDEX     3   
204e0 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
204f0 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
20500 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
20510 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50  LITE_CREATE_TEMP
20520 5f 54 41 42 4c 45 20 20 20 20 20 34 20 20 20 2f  _TABLE     4   /
20530 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
20540 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
20550 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
20560 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f  ITE_CREATE_TEMP_
20570 54 52 49 47 47 45 52 20 20 20 35 20 20 20 2f 2a  TRIGGER   5   /*
20580 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20   Trigger Name   
20590 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
205a0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
205b0 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 56  TE_CREATE_TEMP_V
205c0 49 45 57 20 20 20 20 20 20 36 20 20 20 2f 2a 20  IEW      6   /* 
205d0 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20  View Name       
205e0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
205f0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
20600 45 5f 43 52 45 41 54 45 5f 54 52 49 47 47 45 52  E_CREATE_TRIGGER
20610 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 54          7   /* T
20620 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54  rigger Name    T
20630 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
20640 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
20650 5f 43 52 45 41 54 45 5f 56 49 45 57 20 20 20 20  _CREATE_VIEW    
20660 20 20 20 20 20 20 20 38 20 20 20 2f 2a 20 56 69         8   /* Vi
20670 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55  ew Name       NU
20680 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
20690 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
206a0 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20 20  DELETE          
206b0 20 20 20 20 20 20 39 20 20 20 2f 2a 20 54 61 62        9   /* Tab
206c0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
206d0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
206e0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
206f0 52 4f 50 5f 49 4e 44 45 58 20 20 20 20 20 20 20  ROP_INDEX       
20700 20 20 20 20 31 30 20 20 20 2f 2a 20 49 6e 64 65      10   /* Inde
20710 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c  x Name      Tabl
20720 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
20730 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
20740 4f 50 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20  OP_TABLE        
20750 20 20 20 31 31 20 20 20 2f 2a 20 54 61 62 6c 65     11   /* Table
20760 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
20770 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
20780 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
20790 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20  P_TEMP_INDEX    
207a0 20 20 31 32 20 20 20 2f 2a 20 49 6e 64 65 78 20    12   /* Index 
207b0 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20  Name      Table 
207c0 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
207d0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
207e0 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20  _TEMP_TABLE     
207f0 20 31 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   13   /* Table N
20800 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
20810 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
20820 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
20830 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 20  TEMP_TRIGGER    
20840 31 34 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20  14   /* Trigger 
20850 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61  Name    Table Na
20860 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
20870 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
20880 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 20 31  EMP_VIEW       1
20890 35 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65  5   /* View Name
208a0 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
208b0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
208c0 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52  e SQLITE_DROP_TR
208d0 49 47 47 45 52 20 20 20 20 20 20 20 20 20 31 36  IGGER         16
208e0 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61     /* Trigger Na
208f0 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  me    Table Name
20900 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
20910 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45   SQLITE_DROP_VIE
20920 57 20 20 20 20 20 20 20 20 20 20 20 20 31 37 20  W            17 
20930 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20    /* View Name  
20940 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
20950 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
20960 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 20 20 20  SQLITE_INSERT   
20970 20 20 20 20 20 20 20 20 20 20 20 20 31 38 20 20              18  
20980 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
20990 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
209a0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
209b0 51 4c 49 54 45 5f 50 52 41 47 4d 41 20 20 20 20  QLITE_PRAGMA    
209c0 20 20 20 20 20 20 20 20 20 20 20 31 39 20 20 20             19   
209d0 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65 20 20  /* Pragma Name  
209e0 20 20 20 31 73 74 20 61 72 67 20 6f 72 20 4e 55     1st arg or NU
209f0 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  LL */.#define SQ
20a00 4c 49 54 45 5f 52 45 41 44 20 20 20 20 20 20 20  LITE_READ       
20a10 20 20 20 20 20 20 20 20 20 20 32 30 20 20 20 2f            20   /
20a20 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
20a30 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20    Column Name   
20a40 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
20a50 49 54 45 5f 53 45 4c 45 43 54 20 20 20 20 20 20  ITE_SELECT      
20a60 20 20 20 20 20 20 20 20 20 32 31 20 20 20 2f 2a           21   /*
20a70 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
20a80 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
20a90 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
20aa0 54 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20 20  TE_TRANSACTION  
20ab0 20 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20          22   /* 
20ac0 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20  Operation       
20ad0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
20ae0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
20af0 45 5f 55 50 44 41 54 45 20 20 20 20 20 20 20 20  E_UPDATE        
20b00 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 54         23   /* T
20b10 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43  able Name      C
20b20 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a  olumn Name     *
20b30 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
20b40 5f 41 54 54 41 43 48 20 20 20 20 20 20 20 20 20  _ATTACH         
20b50 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20 46 69        24   /* Fi
20b60 6c 65 6e 61 6d 65 20 20 20 20 20 20 20 20 4e 55  lename        NU
20b70 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
20b80 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
20b90 44 45 54 41 43 48 20 20 20 20 20 20 20 20 20 20  DETACH          
20ba0 20 20 20 20 20 32 35 20 20 20 2f 2a 20 44 61 74       25   /* Dat
20bb0 61 62 61 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c  abase Name   NUL
20bc0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
20bd0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
20be0 4c 54 45 52 5f 54 41 42 4c 45 20 20 20 20 20 20  LTER_TABLE      
20bf0 20 20 20 20 32 36 20 20 20 2f 2a 20 44 61 74 61      26   /* Data
20c00 62 61 73 65 20 4e 61 6d 65 20 20 20 54 61 62 6c  base Name   Tabl
20c10 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
20c20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45  define SQLITE_RE
20c30 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20  INDEX           
20c40 20 20 20 32 37 20 20 20 2f 2a 20 49 6e 64 65 78     27   /* Index
20c50 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
20c60 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
20c70 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41  efine SQLITE_ANA
20c80 4c 59 5a 45 20 20 20 20 20 20 20 20 20 20 20 20  LYZE            
20c90 20 20 32 38 20 20 20 2f 2a 20 54 61 62 6c 65 20    28   /* Table 
20ca0 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
20cb0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
20cc0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
20cd0 54 45 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20  TE_VTABLE       
20ce0 20 32 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   29   /* Table N
20cf0 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20  ame      Module 
20d00 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66  Name     */.#def
20d10 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
20d20 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20  VTABLE          
20d30 33 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  30   /* Table Na
20d40 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e  me      Module N
20d50 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  ame     */.#defi
20d60 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e 43 54 49  ne SQLITE_FUNCTI
20d70 4f 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 33  ON             3
20d80 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20  1   /* NULL     
20d90 20 20 20 20 20 20 20 46 75 6e 63 74 69 6f 6e 20         Function 
20da0 4e 61 6d 65 20 20 20 2a 2f 0a 23 64 65 66 69 6e  Name   */.#defin
20db0 65 20 53 51 4c 49 54 45 5f 53 41 56 45 50 4f 49  e SQLITE_SAVEPOI
20dc0 4e 54 20 20 20 20 20 20 20 20 20 20 20 20 33 32  NT            32
20dd0 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20     /* Operation 
20de0 20 20 20 20 20 20 53 61 76 65 70 6f 69 6e 74 20        Savepoint 
20df0 4e 61 6d 65 20 20 2a 2f 0a 23 64 65 66 69 6e 65  Name  */.#define
20e00 20 53 51 4c 49 54 45 5f 43 4f 50 59 20 20 20 20   SQLITE_COPY    
20e10 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 20                0 
20e20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75    /* No longer u
20e30 73 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  sed */.#define S
20e40 51 4c 49 54 45 5f 52 45 43 55 52 53 49 56 45 20  QLITE_RECURSIVE 
20e50 20 20 20 20 20 20 20 20 20 20 20 33 33 20 20 20             33   
20e60 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20  /* NULL         
20e70 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
20e80 20 20 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50     */../*.** CAP
20e90 49 33 52 45 46 3a 20 54 72 61 63 69 6e 67 20 41  I3REF: Tracing A
20ea0 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e  nd Profiling Fun
20eb0 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65  ctions.**.** The
20ec0 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 67 69  se routines regi
20ed0 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75  ster callback fu
20ee0 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 63 61 6e  nctions that can
20ef0 20 62 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20   be used for.** 
20f00 74 72 61 63 69 6e 67 20 61 6e 64 20 70 72 6f 66  tracing and prof
20f10 69 6c 69 6e 67 20 74 68 65 20 65 78 65 63 75 74  iling the execut
20f20 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61 74 65  ion of SQL state
20f30 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ments..**.** ^Th
20f40 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
20f50 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62  ion registered b
20f60 79 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28  y sqlite3_trace(
20f70 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a  ) is invoked at.
20f80 2a 2a 20 76 61 72 69 6f 75 73 20 74 69 6d 65 73  ** various times
20f90 20 77 68 65 6e 20 61 6e 20 53 51 4c 20 73 74 61   when an SQL sta
20fa0 74 65 6d 65 6e 74 20 69 73 20 62 65 69 6e 67 20  tement is being 
20fb0 72 75 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  run by [sqlite3_
20fc0 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65  step()]..** ^The
20fd0 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29   sqlite3_trace()
20fe0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
20ff0 6f 6b 65 64 20 77 69 74 68 20 61 20 55 54 46 2d  oked with a UTF-
21000 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74  8 rendering of t
21010 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d  he.** SQL statem
21020 65 6e 74 20 74 65 78 74 20 61 73 20 74 68 65 20  ent text as the 
21030 73 74 61 74 65 6d 65 6e 74 20 66 69 72 73 74 20  statement first 
21040 62 65 67 69 6e 73 20 65 78 65 63 75 74 69 6e 67  begins executing
21050 2e 0a 2a 2a 20 5e 28 41 64 64 69 74 69 6f 6e 61  ..** ^(Additiona
21060 6c 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28  l sqlite3_trace(
21070 29 20 63 61 6c 6c 62 61 63 6b 73 20 6d 69 67 68  ) callbacks migh
21080 74 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20 65 61  t occur.** as ea
21090 63 68 20 74 72 69 67 67 65 72 65 64 20 73 75 62  ch triggered sub
210a0 70 72 6f 67 72 61 6d 20 69 73 20 65 6e 74 65 72  program is enter
210b0 65 64 2e 20 20 54 68 65 20 63 61 6c 6c 62 61 63  ed.  The callbac
210c0 6b 73 20 66 6f 72 20 74 72 69 67 67 65 72 73 0a  ks for triggers.
210d0 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55 54 46  ** contain a UTF
210e0 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 74  -8 SQL comment t
210f0 68 61 74 20 69 64 65 6e 74 69 66 69 65 73 20 74  hat identifies t
21100 68 65 20 74 72 69 67 67 65 72 2e 29 5e 0a 2a 2a  he trigger.)^.**
21110 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
21120 54 52 41 43 45 5f 53 49 5a 45 5f 4c 49 4d 49 54  TRACE_SIZE_LIMIT
21130 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
21140 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65  ption can be use
21150 64 20 74 6f 20 6c 69 6d 69 74 0a 2a 2a 20 74 68  d to limit.** th
21160 65 20 6c 65 6e 67 74 68 20 6f 66 20 5b 62 6f 75  e length of [bou
21170 6e 64 20 70 61 72 61 6d 65 74 65 72 5d 20 65 78  nd parameter] ex
21180 70 61 6e 73 69 6f 6e 20 69 6e 20 74 68 65 20 6f  pansion in the o
21190 75 74 70 75 74 20 6f 66 20 73 71 6c 69 74 65 33  utput of sqlite3
211a0 5f 74 72 61 63 65 28 29 2e 0a 2a 2a 0a 2a 2a 20  _trace()..**.** 
211b0 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75  ^The callback fu
211c0 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65  nction registere
211d0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 70 72 6f  d by sqlite3_pro
211e0 66 69 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  file() is invoke
211f0 64 0a 2a 2a 20 61 73 20 65 61 63 68 20 53 51 4c  d.** as each SQL
21200 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73   statement finis
21210 68 65 73 2e 20 20 5e 54 68 65 20 70 72 6f 66 69  hes.  ^The profi
21220 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74  le callback cont
21230 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69 67  ains.** the orig
21240 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 20 74  inal statement t
21250 65 78 74 20 61 6e 64 20 61 6e 20 65 73 74 69 6d  ext and an estim
21260 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63  ate of wall-cloc
21270 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77  k time.** of how
21280 20 6c 6f 6e 67 20 74 68 61 74 20 73 74 61 74 65   long that state
21290 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e  ment took to run
212a0 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20  .  ^The profile 
212b0 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 69 6d 65  callback.** time
212c0 20 69 73 20 69 6e 20 75 6e 69 74 73 20 6f 66 20   is in units of 
212d0 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c 20 68 6f 77  nanoseconds, how
212e0 65 76 65 72 20 74 68 65 20 63 75 72 72 65 6e 74  ever the current
212f0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a   implementation.
21300 2a 2a 20 69 73 20 6f 6e 6c 79 20 63 61 70 61 62  ** is only capab
21310 6c 65 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e  le of millisecon
21320 64 20 72 65 73 6f 6c 75 74 69 6f 6e 20 73 6f 20  d resolution so 
21330 74 68 65 20 73 69 78 20 6c 65 61 73 74 20 73 69  the six least si
21340 67 6e 69 66 69 63 61 6e 74 0a 2a 2a 20 64 69 67  gnificant.** dig
21350 69 74 73 20 69 6e 20 74 68 65 20 74 69 6d 65 20  its in the time 
21360 61 72 65 20 6d 65 61 6e 69 6e 67 6c 65 73 73 2e  are meaningless.
21370 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e    Future version
21380 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 6d  s of SQLite.** m
21390 69 67 68 74 20 70 72 6f 76 69 64 65 20 67 72 65  ight provide gre
213a0 61 74 65 72 20 72 65 73 6f 6c 75 74 69 6f 6e 20  ater resolution 
213b0 6f 6e 20 74 68 65 20 70 72 6f 66 69 6c 65 72 20  on the profiler 
213c0 63 61 6c 6c 62 61 63 6b 2e 20 20 54 68 65 0a 2a  callback.  The.*
213d0 2a 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c  * sqlite3_profil
213e0 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  e() function is 
213f0 63 6f 6e 73 69 64 65 72 65 64 20 65 78 70 65 72  considered exper
21400 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 0a 2a  imental and is.*
21410 2a 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61  * subject to cha
21420 6e 67 65 20 69 6e 20 66 75 74 75 72 65 20 76 65  nge in future ve
21430 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
21440 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
21450 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 74 72  void *sqlite3_tr
21460 61 63 65 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f  ace(sqlite3*, vo
21470 69 64 28 2a 78 54 72 61 63 65 29 28 76 6f 69 64  id(*xTrace)(void
21480 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20  *,const char*), 
21490 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 41  void*);.SQLITE_A
214a0 50 49 20 53 51 4c 49 54 45 5f 45 58 50 45 52 49  PI SQLITE_EXPERI
214b0 4d 45 4e 54 41 4c 20 76 6f 69 64 20 2a 73 71 6c  MENTAL void *sql
214c0 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c  ite3_profile(sql
214d0 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a  ite3*,.   void(*
214e0 78 50 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c  xProfile)(void*,
214f0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c 69  const char*,sqli
21500 74 65 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69  te3_uint64), voi
21510 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d*);../*.** CAPI
21520 33 52 45 46 3a 20 51 75 65 72 79 20 50 72 6f 67  3REF: Query Prog
21530 72 65 73 73 20 43 61 6c 6c 62 61 63 6b 73 0a 2a  ress Callbacks.*
21540 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
21550 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c  3_progress_handl
21560 65 72 28 44 2c 4e 2c 58 2c 50 29 20 69 6e 74 65  er(D,N,X,P) inte
21570 72 66 61 63 65 20 63 61 75 73 65 73 20 74 68 65  rface causes the
21580 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e   callback.** fun
21590 63 74 69 6f 6e 20 58 20 74 6f 20 62 65 20 69 6e  ction X to be in
215a0 76 6f 6b 65 64 20 70 65 72 69 6f 64 69 63 61 6c  voked periodical
215b0 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67 20 72  ly during long r
215c0 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f 0a  unning calls to.
215d0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  ** [sqlite3_exec
215e0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74  ()], [sqlite3_st
215f0 65 70 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ep()] and [sqlit
21600 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20  e3_get_table()] 
21610 66 6f 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  for.** database 
21620 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 20 41  connection D.  A
21630 6e 20 65 78 61 6d 70 6c 65 20 75 73 65 20 66 6f  n example use fo
21640 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66  r this.** interf
21650 61 63 65 20 69 73 20 74 6f 20 6b 65 65 70 20 61  ace is to keep a
21660 20 47 55 49 20 75 70 64 61 74 65 64 20 64 75 72   GUI updated dur
21670 69 6e 67 20 61 20 6c 61 72 67 65 20 71 75 65 72  ing a large quer
21680 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 61  y..**.** ^The pa
21690 72 61 6d 65 74 65 72 20 50 20 69 73 20 70 61 73  rameter P is pas
216a0 73 65 64 20 74 68 72 6f 75 67 68 20 61 73 20 74  sed through as t
216b0 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65  he only paramete
216c0 72 20 74 6f 20 74 68 65 20 0a 2a 2a 20 63 61 6c  r to the .** cal
216d0 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58  lback function X
216e0 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65  .  ^The paramete
216f0 72 20 4e 20 69 73 20 74 68 65 20 61 70 70 72 6f  r N is the appro
21700 78 69 6d 61 74 65 20 6e 75 6d 62 65 72 20 6f 66  ximate number of
21710 20 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 6d 61   .** [virtual ma
21720 63 68 69 6e 65 20 69 6e 73 74 72 75 63 74 69 6f  chine instructio
21730 6e 73 5d 20 74 68 61 74 20 61 72 65 20 65 76 61  ns] that are eva
21740 6c 75 61 74 65 64 20 62 65 74 77 65 65 6e 20 73  luated between s
21750 75 63 63 65 73 73 69 76 65 0a 2a 2a 20 69 6e 76  uccessive.** inv
21760 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ocations of the 
21770 63 61 6c 6c 62 61 63 6b 20 58 2e 20 20 5e 49 66  callback X.  ^If
21780 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20   N is less than 
21790 6f 6e 65 20 74 68 65 6e 20 74 68 65 20 70 72 6f  one then the pro
217a0 67 72 65 73 73 0a 2a 2a 20 68 61 6e 64 6c 65 72  gress.** handler
217b0 20 69 73 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a   is disabled..**
217c0 0a 2a 2a 20 5e 4f 6e 6c 79 20 61 20 73 69 6e 67  .** ^Only a sing
217d0 6c 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64  le progress hand
217e0 6c 65 72 20 6d 61 79 20 62 65 20 64 65 66 69 6e  ler may be defin
217f0 65 64 20 61 74 20 6f 6e 65 20 74 69 6d 65 20 70  ed at one time p
21800 65 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  er.** [database 
21810 63 6f 6e 6e 65 63 74 69 6f 6e 5d 3b 20 73 65 74  connection]; set
21820 74 69 6e 67 20 61 20 6e 65 77 20 70 72 6f 67 72  ting a new progr
21830 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6e 63  ess handler canc
21840 65 6c 73 20 74 68 65 0a 2a 2a 20 6f 6c 64 20 6f  els the.** old o
21850 6e 65 2e 20 20 5e 53 65 74 74 69 6e 67 20 70 61  ne.  ^Setting pa
21860 72 61 6d 65 74 65 72 20 58 20 74 6f 20 4e 55 4c  rameter X to NUL
21870 4c 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 70  L disables the p
21880 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e  rogress handler.
21890 0a 2a 2a 20 5e 54 68 65 20 70 72 6f 67 72 65 73  .** ^The progres
218a0 73 20 68 61 6e 64 6c 65 72 20 69 73 20 61 6c 73  s handler is als
218b0 6f 20 64 69 73 61 62 6c 65 64 20 62 79 20 73 65  o disabled by se
218c0 74 74 69 6e 67 20 4e 20 74 6f 20 61 20 76 61 6c  tting N to a val
218d0 75 65 20 6c 65 73 73 0a 2a 2a 20 74 68 61 6e 20  ue less.** than 
218e0 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  1..**.** ^If the
218f0 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61   progress callba
21900 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a  ck returns non-z
21910 65 72 6f 2c 20 74 68 65 20 6f 70 65 72 61 74 69  ero, the operati
21920 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72 72 75  on is.** interru
21930 70 74 65 64 2e 20 20 54 68 69 73 20 66 65 61 74  pted.  This feat
21940 75 72 65 20 63 61 6e 20 62 65 20 75 73 65 64 20  ure can be used 
21950 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a  to implement a.*
21960 2a 20 22 43 61 6e 63 65 6c 22 20 62 75 74 74 6f  * "Cancel" butto
21970 6e 20 6f 6e 20 61 20 47 55 49 20 70 72 6f 67 72  n on a GUI progr
21980 65 73 73 20 64 69 61 6c 6f 67 20 62 6f 78 2e 0a  ess dialog box..
21990 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 6f 67 72 65  **.** The progre
219a0 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62  ss handler callb
219b0 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20  ack must not do 
219c0 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69  anything that wi
219d0 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65  ll modify.** the
219e0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
219f0 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65  tion that invoke
21a00 64 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 68  d the progress h
21a10 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65 20  andler..** Note 
21a20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72  that [sqlite3_pr
21a30 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20  epare_v2()] and 
21a40 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
21a50 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65   both modify the
21a60 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  ir.** database c
21a70 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74  onnections for t
21a80 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d  he meaning of "m
21a90 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70  odify" in this p
21aa0 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a  aragraph..**.*/.
21ab0 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
21ac0 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73  sqlite3_progress
21ad0 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33  _handler(sqlite3
21ae0 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76  *, int, int(*)(v
21af0 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a  oid*), void*);..
21b00 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
21b10 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 61  Opening A New Da
21b20 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f  tabase Connectio
21b30 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  n.**.** ^These r
21b40 6f 75 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e 20  outines open an 
21b50 53 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 20  SQLite database 
21b60 66 69 6c 65 20 61 73 20 73 70 65 63 69 66 69 65  file as specifie
21b70 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 66 69 6c  d by the .** fil
21b80 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 2e 20  ename argument. 
21b90 5e 54 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72  ^The filename ar
21ba0 67 75 6d 65 6e 74 20 69 73 20 69 6e 74 65 72 70  gument is interp
21bb0 72 65 74 65 64 20 61 73 20 55 54 46 2d 38 20 66  reted as UTF-8 f
21bc0 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70  or.** sqlite3_op
21bd0 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  en() and sqlite3
21be0 5f 6f 70 65 6e 5f 76 32 28 29 20 61 6e 64 20 61  _open_v2() and a
21bf0 73 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20  s UTF-16 in the 
21c00 6e 61 74 69 76 65 20 62 79 74 65 0a 2a 2a 20 6f  native byte.** o
21c10 72 64 65 72 20 66 6f 72 20 73 71 6c 69 74 65 33  rder for sqlite3
21c20 5f 6f 70 65 6e 31 36 28 29 2e 20 5e 28 41 20 5b  _open16(). ^(A [
21c30 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
21c40 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 69 73 20 75  ion] handle is u
21c50 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 74 75 72 6e  sually.** return
21c60 65 64 20 69 6e 20 2a 70 70 44 62 2c 20 65 76 65  ed in *ppDb, eve
21c70 6e 20 69 66 20 61 6e 20 65 72 72 6f 72 20 6f 63  n if an error oc
21c80 63 75 72 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20  curs.  The only 
21c90 65 78 63 65 70 74 69 6f 6e 20 69 73 20 74 68 61  exception is tha
21ca0 74 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65 20 69  t.** if SQLite i
21cb0 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f  s unable to allo
21cc0 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 68  cate memory to h
21cd0 6f 6c 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33  old the [sqlite3
21ce0 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61 20 4e  ] object,.** a N
21cf0 55 4c 4c 20 77 69 6c 6c 20 62 65 20 77 72 69 74  ULL will be writ
21d00 74 65 6e 20 69 6e 74 6f 20 2a 70 70 44 62 20 69  ten into *ppDb i
21d10 6e 73 74 65 61 64 20 6f 66 20 61 20 70 6f 69 6e  nstead of a poin
21d20 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ter to the [sqli
21d30 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2e 29  te3].** object.)
21d40 5e 20 5e 28 49 66 20 74 68 65 20 64 61 74 61 62  ^ ^(If the datab
21d50 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 28 61  ase is opened (a
21d60 6e 64 2f 6f 72 20 63 72 65 61 74 65 64 29 20 73  nd/or created) s
21d70 75 63 63 65 73 73 66 75 6c 6c 79 2c 20 74 68 65  uccessfully, the
21d80 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  n.** [SQLITE_OK]
21d90 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f   is returned.  O
21da0 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72  therwise an [err
21db0 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75  or code] is retu
21dc0 72 6e 65 64 2e 29 5e 20 5e 54 68 65 0a 2a 2a 20  rned.)^ ^The.** 
21dd0 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  [sqlite3_errmsg(
21de0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65  )] or [sqlite3_e
21df0 72 72 6d 73 67 31 36 28 29 5d 20 72 6f 75 74 69  rrmsg16()] routi
21e00 6e 65 73 20 63 61 6e 20 62 65 20 75 73 65 64 20  nes can be used 
21e10 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e 20  to obtain.** an 
21e20 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61 67 65  English language
21e30 20 64 65 73 63 72 69 70 74 69 6f 6e 20 6f 66 20   description of 
21e40 74 68 65 20 65 72 72 6f 72 20 66 6f 6c 6c 6f 77  the error follow
21e50 69 6e 67 20 61 20 66 61 69 6c 75 72 65 20 6f 66  ing a failure of
21e60 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73   any.** of the s
21e70 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 72 6f  qlite3_open() ro
21e80 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  utines..**.** ^T
21e90 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64  he default encod
21ea0 69 6e 67 20 77 69 6c 6c 20 62 65 20 55 54 46 2d  ing will be UTF-
21eb0 38 20 66 6f 72 20 64 61 74 61 62 61 73 65 73 20  8 for databases 
21ec0 63 72 65 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a  created using.**
21ed0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
21ee0 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
21ef0 76 32 28 29 2e 20 20 5e 54 68 65 20 64 65 66 61  v2().  ^The defa
21f00 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72  ult encoding for
21f10 20 64 61 74 61 62 61 73 65 73 0a 2a 2a 20 63 72   databases.** cr
21f20 65 61 74 65 64 20 75 73 69 6e 67 20 73 71 6c 69  eated using sqli
21f30 74 65 33 5f 6f 70 65 6e 31 36 28 29 20 77 69 6c  te3_open16() wil
21f40 6c 20 62 65 20 55 54 46 2d 31 36 20 69 6e 20 74  l be UTF-16 in t
21f50 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  he native byte o
21f60 72 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74  rder..**.** Whet
21f70 68 65 72 20 6f 72 20 6e 6f 74 20 61 6e 20 65 72  her or not an er
21f80 72 6f 72 20 6f 63 63 75 72 73 20 77 68 65 6e 20  ror occurs when 
21f90 69 74 20 69 73 20 6f 70 65 6e 65 64 2c 20 72 65  it is opened, re
21fa0 73 6f 75 72 63 65 73 0a 2a 2a 20 61 73 73 6f 63  sources.** assoc
21fb0 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 5b  iated with the [
21fc0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
21fd0 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 73 68 6f 75  ion] handle shou
21fe0 6c 64 20 62 65 20 72 65 6c 65 61 73 65 64 20 62  ld be released b
21ff0 79 0a 2a 2a 20 70 61 73 73 69 6e 67 20 69 74 20  y.** passing it 
22000 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73  to [sqlite3_clos
22010 65 28 29 5d 20 77 68 65 6e 20 69 74 20 69 73 20  e()] when it is 
22020 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71 75 69 72  no longer requir
22030 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ed..**.** The sq
22040 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
22050 69 6e 74 65 72 66 61 63 65 20 77 6f 72 6b 73 20  interface works 
22060 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 6f 70 65  like sqlite3_ope
22070 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74 20 74 68  n().** except th
22080 61 74 20 69 74 20 61 63 63 65 70 74 73 20 74 77  at it accepts tw
22090 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 70 61 72  o additional par
220a0 61 6d 65 74 65 72 73 20 66 6f 72 20 61 64 64 69  ameters for addi
220b0 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a  tional control.*
220c0 2a 20 6f 76 65 72 20 74 68 65 20 6e 65 77 20 64  * over the new d
220d0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
220e0 6f 6e 2e 20 20 5e 28 54 68 65 20 66 6c 61 67 73  on.  ^(The flags
220f0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
22100 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
22110 28 29 20 63 61 6e 20 74 61 6b 65 20 6f 6e 65 20  () can take one 
22120 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77  of.** the follow
22130 69 6e 67 20 74 68 72 65 65 20 76 61 6c 75 65 73  ing three values
22140 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d  , optionally com
22150 62 69 6e 65 64 20 77 69 74 68 20 74 68 65 20 0a  bined with the .
22160 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
22170 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54  NOMUTEX], [SQLIT
22180 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58  E_OPEN_FULLMUTEX
22190 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ], [SQLITE_OPEN_
221a0 53 48 41 52 45 44 43 41 43 48 45 5d 2c 0a 2a 2a  SHAREDCACHE],.**
221b0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52   [SQLITE_OPEN_PR
221c0 49 56 41 54 45 43 41 43 48 45 5d 2c 20 61 6e 64  IVATECACHE], and
221d0 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  /or [SQLITE_OPEN
221e0 5f 55 52 49 5d 20 66 6c 61 67 73 3a 29 5e 0a 2a  _URI] flags:)^.*
221f0 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c  *.** <dl>.** ^(<
22200 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  dt>[SQLITE_OPEN_
22210 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a  READONLY]</dt>.*
22220 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61  * <dd>The databa
22230 73 65 20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20  se is opened in 
22240 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20  read-only mode. 
22250 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65   If the database
22260 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72   does not.** alr
22270 65 61 64 79 20 65 78 69 73 74 2c 20 61 6e 20 65  eady exist, an e
22280 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64  rror is returned
22290 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  .</dd>)^.**.** ^
222a0 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45  (<dt>[SQLITE_OPE
222b0 4e 5f 52 45 41 44 57 52 49 54 45 5d 3c 2f 64 74  N_READWRITE]</dt
222c0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74  >.** <dd>The dat
222d0 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
222e0 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20  for reading and 
222f0 77 72 69 74 69 6e 67 20 69 66 20 70 6f 73 73 69  writing if possi
22300 62 6c 65 2c 20 6f 72 20 72 65 61 64 69 6e 67 0a  ble, or reading.
22310 2a 2a 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 66  ** only if the f
22320 69 6c 65 20 69 73 20 77 72 69 74 65 20 70 72 6f  ile is write pro
22330 74 65 63 74 65 64 20 62 79 20 74 68 65 20 6f 70  tected by the op
22340 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20  erating system. 
22350 20 49 6e 20 65 69 74 68 65 72 0a 2a 2a 20 63 61   In either.** ca
22360 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  se the database 
22370 6d 75 73 74 20 61 6c 72 65 61 64 79 20 65 78 69  must already exi
22380 73 74 2c 20 6f 74 68 65 72 77 69 73 65 20 61 6e  st, otherwise an
22390 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e   error is return
223a0 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  ed.</dd>)^.**.**
223b0 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f   ^(<dt>[SQLITE_O
223c0 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c  PEN_READWRITE] |
223d0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52   [SQLITE_OPEN_CR
223e0 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  EATE]</dt>.** <d
223f0 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69  d>The database i
22400 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61  s opened for rea
22410 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67  ding and writing
22420 2c 20 61 6e 64 20 69 73 20 63 72 65 61 74 65 64  , and is created
22430 20 69 66 0a 2a 2a 20 69 74 20 64 6f 65 73 20 6e   if.** it does n
22440 6f 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74  ot already exist
22450 2e 20 54 68 69 73 20 69 73 20 74 68 65 20 62 65  . This is the be
22460 68 61 76 69 6f 72 20 74 68 61 74 20 69 73 20 61  havior that is a
22470 6c 77 61 79 73 20 75 73 65 64 20 66 6f 72 0a 2a  lways used for.*
22480 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  * sqlite3_open()
22490 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65   and sqlite3_ope
224a0 6e 31 36 28 29 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  n16().</dd>)^.**
224b0 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20   </dl>.**.** If 
224c0 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65  the 3rd paramete
224d0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65  r to sqlite3_ope
224e0 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 6f 6e  n_v2() is not on
224f0 65 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6d 62  e of the.** comb
22500 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61  inations shown a
22510 62 6f 76 65 20 6f 70 74 69 6f 6e 61 6c 6c 79 20  bove optionally 
22520 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 6f 74  combined with ot
22530 68 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  her.** [SQLITE_O
22540 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 53  PEN_READONLY | S
22550 51 4c 49 54 45 5f 4f 50 45 4e 5f 2a 20 62 69 74  QLITE_OPEN_* bit
22560 73 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 62  s].** then the b
22570 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66  ehavior is undef
22580 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ined..**.** ^If 
22590 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  the [SQLITE_OPEN
225a0 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c 61 67 20 69  _NOMUTEX] flag i
225b0 73 20 73 65 74 2c 20 74 68 65 6e 20 74 68 65 20  s set, then the 
225c0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
225d0 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e 20  ion.** opens in 
225e0 74 68 65 20 6d 75 6c 74 69 2d 74 68 72 65 61 64  the multi-thread
225f0 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
22600 5d 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65  ] as long as the
22610 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 0a 2a   single-thread.*
22620 2a 20 6d 6f 64 65 20 68 61 73 20 6e 6f 74 20 62  * mode has not b
22630 65 65 6e 20 73 65 74 20 61 74 20 63 6f 6d 70 69  een set at compi
22640 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74  le-time or start
22650 2d 74 69 6d 65 2e 20 20 5e 49 66 20 74 68 65 0a  -time.  ^If the.
22660 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
22670 46 55 4c 4c 4d 55 54 45 58 5d 20 66 6c 61 67 20  FULLMUTEX] flag 
22680 69 73 20 73 65 74 20 74 68 65 6e 20 74 68 65 20  is set then the 
22690 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
226a0 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20  ion opens.** in 
226b0 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b  the serialized [
226c0 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
226d0 75 6e 6c 65 73 73 20 73 69 6e 67 6c 65 2d 74 68  unless single-th
226e0 72 65 61 64 20 77 61 73 0a 2a 2a 20 70 72 65 76  read was.** prev
226f0 69 6f 75 73 6c 79 20 73 65 6c 65 63 74 65 64 20  iously selected 
22700 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  at compile-time 
22710 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 0a 2a  or start-time..*
22720 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f  * ^The [SQLITE_O
22730 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d  PEN_SHAREDCACHE]
22740 20 66 6c 61 67 20 63 61 75 73 65 73 20 74 68 65   flag causes the
22750 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
22760 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 65 6c  tion to be.** el
22770 69 67 69 62 6c 65 20 74 6f 20 75 73 65 20 5b 73  igible to use [s
22780 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65  hared cache mode
22790 5d 2c 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66  ], regardless of
227a0 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
227b0 73 68 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 20  shared.** cache 
227c0 69 73 20 65 6e 61 62 6c 65 64 20 75 73 69 6e 67  is enabled using
227d0 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65   [sqlite3_enable
227e0 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28 29 5d  _shared_cache()]
227f0 2e 20 20 5e 54 68 65 0a 2a 2a 20 5b 53 51 4c 49  .  ^The.** [SQLI
22800 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43  TE_OPEN_PRIVATEC
22810 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65  ACHE] flag cause
22820 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  s the database c
22830 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 6e 6f 74  onnection to not
22840 0a 2a 2a 20 70 61 72 74 69 63 69 70 61 74 65 20  .** participate 
22850 69 6e 20 5b 73 68 61 72 65 64 20 63 61 63 68 65  in [shared cache
22860 20 6d 6f 64 65 5d 20 65 76 65 6e 20 69 66 20 69   mode] even if i
22870 74 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a  t is enabled..**
22880 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20  .** ^The fourth 
22890 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
228a0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
228b0 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
228c0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66  e.** [sqlite3_vf
228d0 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64  s] object that d
228e0 65 66 69 6e 65 73 20 74 68 65 20 6f 70 65 72 61  efines the opera
228f0 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65  ting system inte
22900 72 66 61 63 65 20 74 68 61 74 0a 2a 2a 20 74 68  rface that.** th
22910 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63  e new database c
22920 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64  onnection should
22930 20 75 73 65 2e 20 20 5e 49 66 20 74 68 65 20 66   use.  ^If the f
22940 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
22950 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69  is.** a NULL poi
22960 6e 74 65 72 20 74 68 65 6e 20 74 68 65 20 64 65  nter then the de
22970 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76  fault [sqlite3_v
22980 66 73 5d 20 6f 62 6a 65 63 74 20 69 73 20 75 73  fs] object is us
22990 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ed..**.** ^If th
229a0 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 22 3a  e filename is ":
229b0 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61  memory:", then a
229c0 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72   private, tempor
229d0 61 72 79 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61  ary in-memory da
229e0 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 63 72 65  tabase.** is cre
229f0 61 74 65 64 20 66 6f 72 20 74 68 65 20 63 6f 6e  ated for the con
22a00 6e 65 63 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20  nection.  ^This 
22a10 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61  in-memory databa
22a20 73 65 20 77 69 6c 6c 20 76 61 6e 69 73 68 20 77  se will vanish w
22a30 68 65 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  hen.** the datab
22a40 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
22a50 73 20 63 6c 6f 73 65 64 2e 20 20 46 75 74 75 72  s closed.  Futur
22a60 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
22a70 4c 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20 6d 61  Lite might.** ma
22a80 6b 65 20 75 73 65 20 6f 66 20 61 64 64 69 74 69  ke use of additi
22a90 6f 6e 61 6c 20 73 70 65 63 69 61 6c 20 66 69 6c  onal special fil
22aa0 65 6e 61 6d 65 73 20 74 68 61 74 20 62 65 67 69  enames that begi
22ab0 6e 20 77 69 74 68 20 74 68 65 20 22 3a 22 20 63  n with the ":" c
22ac0 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49 74 20  haracter..** It 
22ad0 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74  is recommended t
22ae0 68 61 74 20 77 68 65 6e 20 61 20 64 61 74 61 62  hat when a datab
22af0 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 61 63 74  ase filename act
22b00 75 61 6c 6c 79 20 64 6f 65 73 20 62 65 67 69 6e  ually does begin
22b10 20 77 69 74 68 0a 2a 2a 20 61 20 22 3a 22 20 63   with.** a ":" c
22b20 68 61 72 61 63 74 65 72 20 79 6f 75 20 73 68 6f  haracter you sho
22b30 75 6c 64 20 70 72 65 66 69 78 20 74 68 65 20 66  uld prefix the f
22b40 69 6c 65 6e 61 6d 65 20 77 69 74 68 20 61 20 70  ilename with a p
22b50 61 74 68 6e 61 6d 65 20 73 75 63 68 20 61 73 0a  athname such as.
22b60 2a 2a 20 22 2e 2f 22 20 74 6f 20 61 76 6f 69 64  ** "./" to avoid
22b70 20 61 6d 62 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a   ambiguity..**.*
22b80 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61  * ^If the filena
22b90 6d 65 20 69 73 20 61 6e 20 65 6d 70 74 79 20 73  me is an empty s
22ba0 74 72 69 6e 67 2c 20 74 68 65 6e 20 61 20 70 72  tring, then a pr
22bb0 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79  ivate, temporary
22bc0 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61  .** on-disk data
22bd0 62 61 73 65 20 77 69 6c 6c 20 62 65 20 63 72 65  base will be cre
22be0 61 74 65 64 2e 20 20 5e 54 68 69 73 20 70 72 69  ated.  ^This pri
22bf0 76 61 74 65 20 64 61 74 61 62 61 73 65 20 77 69  vate database wi
22c00 6c 6c 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74  ll be.** automat
22c10 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 61  ically deleted a
22c20 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 64 61  s soon as the da
22c30 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
22c40 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a  n is closed..**.
22c50 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d  ** [[URI filenam
22c60 65 73 20 69 6e 20 73 71 6c 69 74 65 33 5f 6f 70  es in sqlite3_op
22c70 65 6e 28 29 5d 5d 20 3c 68 33 3e 55 52 49 20 46  en()]] <h3>URI F
22c80 69 6c 65 6e 61 6d 65 73 3c 2f 68 33 3e 0a 2a 2a  ilenames</h3>.**
22c90 0a 2a 2a 20 5e 49 66 20 5b 55 52 49 20 66 69 6c  .** ^If [URI fil
22ca0 65 6e 61 6d 65 5d 20 69 6e 74 65 72 70 72 65 74  ename] interpret
22cb0 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64  ation is enabled
22cc0 2c 20 61 6e 64 20 74 68 65 20 66 69 6c 65 6e 61  , and the filena
22cd0 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 62  me argument.** b
22ce0 65 67 69 6e 73 20 77 69 74 68 20 22 66 69 6c 65  egins with "file
22cf0 3a 22 2c 20 74 68 65 6e 20 74 68 65 20 66 69 6c  :", then the fil
22d00 65 6e 61 6d 65 20 69 73 20 69 6e 74 65 72 70 72  ename is interpr
22d10 65 74 65 64 20 61 73 20 61 20 55 52 49 2e 20 5e  eted as a URI. ^
22d20 55 52 49 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20  URI.** filename 
22d30 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69  interpretation i
22d40 73 20 65 6e 61 62 6c 65 64 20 69 66 20 74 68 65  s enabled if the
22d50 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52   [SQLITE_OPEN_UR
22d60 49 5d 20 66 6c 61 67 20 69 73 0a 2a 2a 20 73 65  I] flag is.** se
22d70 74 20 69 6e 20 74 68 65 20 66 6f 75 72 74 68 20  t in the fourth 
22d80 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
22d90 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2c 20 6f  te3_open_v2(), o
22da0 72 20 69 66 20 69 74 20 68 61 73 0a 2a 2a 20 62  r if it has.** b
22db0 65 65 6e 20 65 6e 61 62 6c 65 64 20 67 6c 6f 62  een enabled glob
22dc0 61 6c 6c 79 20 75 73 69 6e 67 20 74 68 65 20 5b  ally using the [
22dd0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52  SQLITE_CONFIG_UR
22de0 49 5d 20 6f 70 74 69 6f 6e 20 77 69 74 68 20 74  I] option with t
22df0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  he.** [sqlite3_c
22e00 6f 6e 66 69 67 28 29 5d 20 6d 65 74 68 6f 64 20  onfig()] method 
22e10 6f 72 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54  or by the [SQLIT
22e20 45 5f 55 53 45 5f 55 52 49 5d 20 63 6f 6d 70 69  E_USE_URI] compi
22e30 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a  le-time option..
22e40 2a 2a 20 41 73 20 6f 66 20 53 51 4c 69 74 65 20  ** As of SQLite 
22e50 76 65 72 73 69 6f 6e 20 33 2e 37 2e 37 2c 20 55  version 3.7.7, U
22e60 52 49 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65  RI filename inte
22e70 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 74 75  rpretation is tu
22e80 72 6e 65 64 20 6f 66 66 0a 2a 2a 20 62 79 20 64  rned off.** by d
22e90 65 66 61 75 6c 74 2c 20 62 75 74 20 66 75 74 75  efault, but futu
22ea0 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
22eb0 51 4c 69 74 65 20 6d 69 67 68 74 20 65 6e 61 62  QLite might enab
22ec0 6c 65 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 0a  le URI filename.
22ed0 2a 2a 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f  ** interpretatio
22ee0 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 20 20 53  n by default.  S
22ef0 65 65 20 22 5b 55 52 49 20 66 69 6c 65 6e 61 6d  ee "[URI filenam
22f00 65 73 5d 22 20 66 6f 72 20 61 64 64 69 74 69 6f  es]" for additio
22f10 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  nal.** informati
22f20 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55 52 49 20 66 69  on..**.** URI fi
22f30 6c 65 6e 61 6d 65 73 20 61 72 65 20 70 61 72 73  lenames are pars
22f40 65 64 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20  ed according to 
22f50 52 46 43 20 33 39 38 36 2e 20 5e 49 66 20 74 68  RFC 3986. ^If th
22f60 65 20 55 52 49 20 63 6f 6e 74 61 69 6e 73 20 61  e URI contains a
22f70 6e 0a 2a 2a 20 61 75 74 68 6f 72 69 74 79 2c 20  n.** authority, 
22f80 74 68 65 6e 20 69 74 20 6d 75 73 74 20 62 65 20  then it must be 
22f90 65 69 74 68 65 72 20 61 6e 20 65 6d 70 74 79 20  either an empty 
22fa0 73 74 72 69 6e 67 20 6f 72 20 74 68 65 20 73 74  string or the st
22fb0 72 69 6e 67 20 0a 2a 2a 20 22 6c 6f 63 61 6c 68  ring .** "localh
22fc0 6f 73 74 22 2e 20 5e 49 66 20 74 68 65 20 61 75  ost". ^If the au
22fd0 74 68 6f 72 69 74 79 20 69 73 20 6e 6f 74 20 61  thority is not a
22fe0 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f  n empty string o
22ff0 72 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2c 20 61  r "localhost", a
23000 6e 20 0a 2a 2a 20 65 72 72 6f 72 20 69 73 20 72  n .** error is r
23010 65 74 75 72 6e 65 64 20 74 6f 20 74 68 65 20 63  eturned to the c
23020 61 6c 6c 65 72 2e 20 5e 54 68 65 20 66 72 61 67  aller. ^The frag
23030 6d 65 6e 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f  ment component o
23040 66 20 61 20 55 52 49 2c 20 69 66 20 0a 2a 2a 20  f a URI, if .** 
23050 70 72 65 73 65 6e 74 2c 20 69 73 20 69 67 6e 6f  present, is igno
23060 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69  red..**.** ^SQLi
23070 74 65 20 75 73 65 73 20 74 68 65 20 70 61 74 68  te uses the path
23080 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 74 68   component of th
23090 65 20 55 52 49 20 61 73 20 74 68 65 20 6e 61 6d  e URI as the nam
230a0 65 20 6f 66 20 74 68 65 20 64 69 73 6b 20 66 69  e of the disk fi
230b0 6c 65 0a 2a 2a 20 77 68 69 63 68 20 63 6f 6e 74  le.** which cont
230c0 61 69 6e 73 20 74 68 65 20 64 61 74 61 62 61 73  ains the databas
230d0 65 2e 20 5e 49 66 20 74 68 65 20 70 61 74 68 20  e. ^If the path 
230e0 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 27 2f  begins with a '/
230f0 27 20 63 68 61 72 61 63 74 65 72 2c 20 0a 2a 2a  ' character, .**
23100 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e 74 65   then it is inte
23110 72 70 72 65 74 65 64 20 61 73 20 61 6e 20 61 62  rpreted as an ab
23120 73 6f 6c 75 74 65 20 70 61 74 68 2e 20 5e 49 66  solute path. ^If
23130 20 74 68 65 20 70 61 74 68 20 64 6f 65 73 20 6e   the path does n
23140 6f 74 20 62 65 67 69 6e 20 0a 2a 2a 20 77 69 74  ot begin .** wit
23150 68 20 61 20 27 2f 27 20 28 6d 65 61 6e 69 6e 67  h a '/' (meaning
23160 20 74 68 61 74 20 74 68 65 20 61 75 74 68 6f 72   that the author
23170 69 74 79 20 73 65 63 74 69 6f 6e 20 69 73 20 6f  ity section is o
23180 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20  mitted from the 
23190 55 52 49 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65  URI).** then the
231a0 20 70 61 74 68 20 69 73 20 69 6e 74 65 72 70 72   path is interpr
231b0 65 74 65 64 20 61 73 20 61 20 72 65 6c 61 74 69  eted as a relati
231c0 76 65 20 70 61 74 68 2e 20 0a 2a 2a 20 5e 28 4f  ve path. .** ^(O
231d0 6e 20 77 69 6e 64 6f 77 73 2c 20 74 68 65 20 66  n windows, the f
231e0 69 72 73 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f  irst component o
231f0 66 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61  f an absolute pa
23200 74 68 20 0a 2a 2a 20 69 73 20 61 20 64 72 69 76  th .** is a driv
23210 65 20 73 70 65 63 69 66 69 63 61 74 69 6f 6e 20  e specification 
23220 28 65 2e 67 2e 20 22 43 3a 22 29 2e 29 5e 0a 2a  (e.g. "C:").)^.*
23230 2a 0a 2a 2a 20 5b 5b 63 6f 72 65 20 55 52 49 20  *.** [[core URI 
23240 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 73  query parameters
23250 5d 5d 0a 2a 2a 20 54 68 65 20 71 75 65 72 79 20  ]].** The query 
23260 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55  component of a U
23270 52 49 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 70  RI may contain p
23280 61 72 61 6d 65 74 65 72 73 20 74 68 61 74 20 61  arameters that a
23290 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 0a 2a  re interpreted.*
232a0 2a 20 65 69 74 68 65 72 20 62 79 20 53 51 4c 69  * either by SQLi
232b0 74 65 20 69 74 73 65 6c 66 2c 20 6f 72 20 62 79  te itself, or by
232c0 20 61 20 5b 56 46 53 20 7c 20 63 75 73 74 6f 6d   a [VFS | custom
232d0 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
232e0 69 6f 6e 5d 2e 0a 2a 2a 20 53 51 4c 69 74 65 20  ion]..** SQLite 
232f0 61 6e 64 20 69 74 73 20 62 75 69 6c 74 2d 69 6e  and its built-in
23300 20 5b 56 46 53 65 73 5d 20 69 6e 74 65 72 70 72   [VFSes] interpr
23310 65 74 20 74 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77  et the.** follow
23320 69 6e 67 20 71 75 65 72 79 20 70 61 72 61 6d 65  ing query parame
23330 74 65 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ters:.**.** <ul>
23340 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 76 66  .**   <li> <b>vf
23350 73 3c 2f 62 3e 3a 20 5e 54 68 65 20 22 76 66 73  s</b>: ^The "vfs
23360 22 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  " parameter may 
23370 62 65 20 75 73 65 64 20 74 6f 20 73 70 65 63 69  be used to speci
23380 66 79 20 74 68 65 20 6e 61 6d 65 20 6f 66 0a 2a  fy the name of.*
23390 2a 20 20 20 20 20 61 20 56 46 53 20 6f 62 6a 65  *     a VFS obje
233a0 63 74 20 74 68 61 74 20 70 72 6f 76 69 64 65 73  ct that provides
233b0 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73   the operating s
233c0 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20  ystem interface 
233d0 74 68 61 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 20  that should.**  
233e0 20 20 20 62 65 20 75 73 65 64 20 74 6f 20 61 63     be used to ac
233f0 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61 73  cess the databas
23400 65 20 66 69 6c 65 20 6f 6e 20 64 69 73 6b 2e 20  e file on disk. 
23410 5e 49 66 20 74 68 69 73 20 6f 70 74 69 6f 6e 20  ^If this option 
23420 69 73 20 73 65 74 20 74 6f 0a 2a 2a 20 20 20 20  is set to.**    
23430 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
23440 20 74 68 65 20 64 65 66 61 75 6c 74 20 56 46 53   the default VFS
23450 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e   object is used.
23460 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61 6e 20   ^Specifying an 
23470 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20 20 20 20 56  unknown.**     V
23480 46 53 20 69 73 20 61 6e 20 65 72 72 6f 72 2e 20  FS is an error. 
23490 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ^If sqlite3_open
234a0 5f 76 32 28 29 20 69 73 20 75 73 65 64 20 61 6e  _v2() is used an
234b0 64 20 74 68 65 20 76 66 73 20 6f 70 74 69 6f 6e  d the vfs option
234c0 20 69 73 0a 2a 2a 20 20 20 20 20 70 72 65 73 65   is.**     prese
234d0 6e 74 2c 20 74 68 65 6e 20 74 68 65 20 56 46 53  nt, then the VFS
234e0 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68   specified by th
234f0 65 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 70  e option takes p
23500 72 65 63 65 64 65 6e 63 65 20 6f 76 65 72 0a 2a  recedence over.*
23510 2a 20 20 20 20 20 74 68 65 20 76 61 6c 75 65 20  *     the value 
23520 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66 6f  passed as the fo
23530 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
23540 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
23550 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69  2()..**.**   <li
23560 3e 20 3c 62 3e 6d 6f 64 65 3c 2f 62 3e 3a 20 5e  > <b>mode</b>: ^
23570 28 54 68 65 20 6d 6f 64 65 20 70 61 72 61 6d 65  (The mode parame
23580 74 65 72 20 6d 61 79 20 62 65 20 73 65 74 20 74  ter may be set t
23590 6f 20 65 69 74 68 65 72 20 22 72 6f 22 2c 20 22  o either "ro", "
235a0 72 77 22 2c 0a 2a 2a 20 20 20 20 20 22 72 77 63  rw",.**     "rwc
235b0 22 2c 20 6f 72 20 22 6d 65 6d 6f 72 79 22 2e 20  ", or "memory". 
235c0 41 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 73 65  Attempting to se
235d0 74 20 69 74 20 74 6f 20 61 6e 79 20 6f 74 68 65  t it to any othe
235e0 72 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 20 20  r value is.**   
235f0 20 20 61 6e 20 65 72 72 6f 72 29 5e 2e 20 0a 2a    an error)^. .*
23600 2a 20 20 20 20 20 5e 49 66 20 22 72 6f 22 20 69  *     ^If "ro" i
23610 73 20 73 70 65 63 69 66 69 65 64 2c 20 74 68 65  s specified, the
23620 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  n the database i
23630 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61  s opened for rea
23640 64 2d 6f 6e 6c 79 20 0a 2a 2a 20 20 20 20 20 61  d-only .**     a
23650 63 63 65 73 73 2c 20 6a 75 73 74 20 61 73 20 69  ccess, just as i
23660 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  f the [SQLITE_OP
23670 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20 66 6c 61  EN_READONLY] fla
23680 67 20 68 61 64 20 62 65 65 6e 20 73 65 74 20 69  g had been set i
23690 6e 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 74 68  n the .**     th
236a0 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ird argument to 
236b0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
236c0 29 2e 20 5e 49 66 20 74 68 65 20 6d 6f 64 65 20  ). ^If the mode 
236d0 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f  option is set to
236e0 20 0a 2a 2a 20 20 20 20 20 22 72 77 22 2c 20 74   .**     "rw", t
236f0 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
23700 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72   is opened for r
23710 65 61 64 2d 77 72 69 74 65 20 28 62 75 74 20 6e  ead-write (but n
23720 6f 74 20 63 72 65 61 74 65 29 20 0a 2a 2a 20 20  ot create) .**  
23730 20 20 20 61 63 63 65 73 73 2c 20 61 73 20 69 66     access, as if
23740 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41   SQLITE_OPEN_REA
23750 44 57 52 49 54 45 20 28 62 75 74 20 6e 6f 74 20  DWRITE (but not 
23760 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
23770 54 45 29 20 68 61 64 20 0a 2a 2a 20 20 20 20 20  TE) had .**     
23780 62 65 65 6e 20 73 65 74 2e 20 5e 56 61 6c 75 65  been set. ^Value
23790 20 22 72 77 63 22 20 69 73 20 65 71 75 69 76 61   "rwc" is equiva
237a0 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20  lent to setting 
237b0 62 6f 74 68 20 0a 2a 2a 20 20 20 20 20 53 51 4c  both .**     SQL
237c0 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
237d0 54 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 4f 50  TE and SQLITE_OP
237e0 45 4e 5f 43 52 45 41 54 45 2e 20 20 5e 49 66 20  EN_CREATE.  ^If 
237f0 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20  the mode option 
23800 69 73 0a 2a 2a 20 20 20 20 20 73 65 74 20 74 6f  is.**     set to
23810 20 22 6d 65 6d 6f 72 79 22 20 74 68 65 6e 20 61   "memory" then a
23820 20 70 75 72 65 20 5b 69 6e 2d 6d 65 6d 6f 72 79   pure [in-memory
23830 20 64 61 74 61 62 61 73 65 5d 20 74 68 61 74 20   database] that 
23840 6e 65 76 65 72 20 72 65 61 64 73 0a 2a 2a 20 20  never reads.**  
23850 20 20 20 6f 72 20 77 72 69 74 65 73 20 66 72 6f     or writes fro
23860 6d 20 64 69 73 6b 20 69 73 20 75 73 65 64 2e 20  m disk is used. 
23870 5e 49 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20  ^It is an error 
23880 74 6f 20 73 70 65 63 69 66 79 20 61 20 76 61 6c  to specify a val
23890 75 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20 74 68  ue for.**     th
238a0 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 72  e mode parameter
238b0 20 74 68 61 74 20 69 73 20 6c 65 73 73 20 72 65   that is less re
238c0 73 74 72 69 63 74 69 76 65 20 74 68 61 6e 20 74  strictive than t
238d0 68 61 74 20 73 70 65 63 69 66 69 65 64 20 62 79  hat specified by
238e0 0a 2a 2a 20 20 20 20 20 74 68 65 20 66 6c 61 67  .**     the flag
238f0 73 20 70 61 73 73 65 64 20 69 6e 20 74 68 65 20  s passed in the 
23900 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
23910 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
23920 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c  v2()..**.**   <l
23930 69 3e 20 3c 62 3e 63 61 63 68 65 3c 2f 62 3e 3a  i> <b>cache</b>:
23940 20 5e 54 68 65 20 63 61 63 68 65 20 70 61 72 61   ^The cache para
23950 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73 65 74  meter may be set
23960 20 74 6f 20 65 69 74 68 65 72 20 22 73 68 61 72   to either "shar
23970 65 64 22 20 6f 72 0a 2a 2a 20 20 20 20 20 22 70  ed" or.**     "p
23980 72 69 76 61 74 65 22 2e 20 5e 53 65 74 74 69 6e  rivate". ^Settin
23990 67 20 69 74 20 74 6f 20 22 73 68 61 72 65 64 22  g it to "shared"
239a0 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74   is equivalent t
239b0 6f 20 73 65 74 74 69 6e 67 20 74 68 65 0a 2a 2a  o setting the.**
239c0 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e       SQLITE_OPEN
239d0 5f 53 48 41 52 45 44 43 41 43 48 45 20 62 69 74  _SHAREDCACHE bit
239e0 20 69 6e 20 74 68 65 20 66 6c 61 67 73 20 61 72   in the flags ar
239f0 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 74 6f  gument passed to
23a00 0a 2a 2a 20 20 20 20 20 73 71 6c 69 74 65 33 5f  .**     sqlite3_
23a10 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 53 65 74 74  open_v2(). ^Sett
23a20 69 6e 67 20 74 68 65 20 63 61 63 68 65 20 70 61  ing the cache pa
23a30 72 61 6d 65 74 65 72 20 74 6f 20 22 70 72 69 76  rameter to "priv
23a40 61 74 65 22 20 69 73 20 0a 2a 2a 20 20 20 20 20  ate" is .**     
23a50 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65  equivalent to se
23a60 74 74 69 6e 67 20 74 68 65 20 53 51 4c 49 54 45  tting the SQLITE
23a70 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43  _OPEN_PRIVATECAC
23a80 48 45 20 62 69 74 2e 0a 2a 2a 20 20 20 20 20 5e  HE bit..**     ^
23a90 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  If sqlite3_open_
23aa0 76 32 28 29 20 69 73 20 75 73 65 64 20 61 6e 64  v2() is used and
23ab0 20 74 68 65 20 22 63 61 63 68 65 22 20 70 61 72   the "cache" par
23ac0 61 6d 65 74 65 72 20 69 73 20 70 72 65 73 65 6e  ameter is presen
23ad0 74 20 69 6e 0a 2a 2a 20 20 20 20 20 61 20 55 52  t in.**     a UR
23ae0 49 20 66 69 6c 65 6e 61 6d 65 2c 20 69 74 73 20  I filename, its 
23af0 76 61 6c 75 65 20 6f 76 65 72 72 69 64 65 73 20  value overrides 
23b00 61 6e 79 20 62 65 68 61 76 69 6f 72 20 72 65 71  any behavior req
23b10 75 65 73 74 65 64 20 62 79 20 73 65 74 74 69 6e  uested by settin
23b20 67 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f  g.**     SQLITE_
23b30 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48  OPEN_PRIVATECACH
23b40 45 20 6f 72 20 53 51 4c 49 54 45 5f 4f 50 45 4e  E or SQLITE_OPEN
23b50 5f 53 48 41 52 45 44 43 41 43 48 45 20 66 6c 61  _SHAREDCACHE fla
23b60 67 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c  g..**.**  <li> <
23b70 62 3e 70 73 6f 77 3c 2f 62 3e 3a 20 5e 54 68 65  b>psow</b>: ^The
23b80 20 70 73 6f 77 20 70 61 72 61 6d 65 74 65 72 20   psow parameter 
23b90 69 6e 64 69 63 61 74 65 73 20 77 68 65 74 68 65  indicates whethe
23ba0 72 20 6f 72 20 6e 6f 74 20 74 68 65 0a 2a 2a 20  r or not the.** 
23bb0 20 20 20 20 5b 70 6f 77 65 72 73 61 66 65 20 6f      [powersafe o
23bc0 76 65 72 77 72 69 74 65 5d 20 70 72 6f 70 65 72  verwrite] proper
23bd0 74 79 20 64 6f 65 73 20 6f 72 20 64 6f 65 73 20  ty does or does 
23be0 6e 6f 74 20 61 70 70 6c 79 20 74 6f 20 74 68 65  not apply to the
23bf0 0a 2a 2a 20 20 20 20 20 73 74 6f 72 61 67 65 20  .**     storage 
23c00 6d 65 64 69 61 20 6f 6e 20 77 68 69 63 68 20 74  media on which t
23c10 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
23c20 20 72 65 73 69 64 65 73 2e 0a 2a 2a 0a 2a 2a 20   resides..**.** 
23c30 20 3c 6c 69 3e 20 3c 62 3e 6e 6f 6c 6f 63 6b 3c   <li> <b>nolock<
23c40 2f 62 3e 3a 20 5e 54 68 65 20 6e 6f 6c 6f 63 6b  /b>: ^The nolock
23c50 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
23c60 62 6f 6f 6c 65 61 6e 20 71 75 65 72 79 20 70 61  boolean query pa
23c70 72 61 6d 65 74 65 72 0a 2a 2a 20 20 20 20 20 77  rameter.**     w
23c80 68 69 63 68 20 69 66 20 73 65 74 20 64 69 73 61  hich if set disa
23c90 62 6c 65 73 20 66 69 6c 65 20 6c 6f 63 6b 69 6e  bles file lockin
23ca0 67 20 69 6e 20 72 6f 6c 6c 62 61 63 6b 20 6a 6f  g in rollback jo
23cb0 75 72 6e 61 6c 20 6d 6f 64 65 73 2e 20 20 54 68  urnal modes.  Th
23cc0 69 73 0a 2a 2a 20 20 20 20 20 69 73 20 75 73 65  is.**     is use
23cd0 66 75 6c 20 66 6f 72 20 61 63 63 65 73 73 69 6e  ful for accessin
23ce0 67 20 61 20 64 61 74 61 62 61 73 65 20 6f 6e 20  g a database on 
23cf0 61 20 66 69 6c 65 73 79 73 74 65 6d 20 74 68 61  a filesystem tha
23d00 74 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 20 20  t does not.**   
23d10 20 20 73 75 70 70 6f 72 74 20 6c 6f 63 6b 69 6e    support lockin
23d20 67 2e 20 20 43 61 75 74 69 6f 6e 3a 20 20 44 61  g.  Caution:  Da
23d30 74 61 62 61 73 65 20 63 6f 72 72 75 70 74 69 6f  tabase corruptio
23d40 6e 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69  n might result i
23d50 66 20 74 77 6f 0a 2a 2a 20 20 20 20 20 6f 72 20  f two.**     or 
23d60 6d 6f 72 65 20 70 72 6f 63 65 73 73 65 73 20 77  more processes w
23d70 72 69 74 65 20 74 6f 20 74 68 65 20 73 61 6d 65  rite to the same
23d80 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 61 6e   database and an
23d90 79 20 6f 6e 65 20 6f 66 20 74 68 6f 73 65 0a 2a  y one of those.*
23da0 2a 20 20 20 20 20 70 72 6f 63 65 73 73 65 73 20  *     processes 
23db0 75 73 65 73 20 6e 6f 6c 6f 63 6b 3d 31 2e 0a 2a  uses nolock=1..*
23dc0 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 69 6d  *.**  <li> <b>im
23dd0 6d 75 74 61 62 6c 65 3c 2f 62 3e 3a 20 5e 54 68  mutable</b>: ^Th
23de0 65 20 69 6d 6d 75 74 61 62 6c 65 20 70 61 72 61  e immutable para
23df0 6d 65 74 65 72 20 69 73 20 61 20 62 6f 6f 6c 65  meter is a boole
23e00 61 6e 20 71 75 65 72 79 0a 2a 2a 20 20 20 20 20  an query.**     
23e10 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 20 69  parameter that i
23e20 6e 64 69 63 61 74 65 73 20 74 68 61 74 20 74 68  ndicates that th
23e30 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
23e40 69 73 20 73 74 6f 72 65 64 20 6f 6e 0a 2a 2a 20  is stored on.** 
23e50 20 20 20 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 65      read-only me
23e60 64 69 61 2e 20 20 5e 57 68 65 6e 20 69 6d 6d 75  dia.  ^When immu
23e70 74 61 62 6c 65 20 69 73 20 73 65 74 2c 20 53 51  table is set, SQ
23e80 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74 68 61  Lite assumes tha
23e90 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 64 61 74  t the.**     dat
23ea0 61 62 61 73 65 20 66 69 6c 65 20 63 61 6e 6e 6f  abase file canno
23eb0 74 20 62 65 20 63 68 61 6e 67 65 64 2c 20 65 76  t be changed, ev
23ec0 65 6e 20 62 79 20 61 20 70 72 6f 63 65 73 73 20  en by a process 
23ed0 77 69 74 68 20 68 69 67 68 65 72 0a 2a 2a 20 20  with higher.**  
23ee0 20 20 20 70 72 69 76 69 6c 65 67 65 2c 20 61 6e     privilege, an
23ef0 64 20 73 6f 20 74 68 65 20 64 61 74 61 62 61 73  d so the databas
23f00 65 20 69 73 20 6f 70 65 6e 65 64 20 72 65 61 64  e is opened read
23f10 2d 6f 6e 6c 79 20 61 6e 64 20 61 6c 6c 20 6c 6f  -only and all lo
23f20 63 6b 69 6e 67 0a 2a 2a 20 20 20 20 20 61 6e 64  cking.**     and
23f30 20 63 68 61 6e 67 65 20 64 65 74 65 63 74 69 6f   change detectio
23f40 6e 20 69 73 20 64 69 73 61 62 6c 65 64 2e 20 20  n is disabled.  
23f50 43 61 75 74 69 6f 6e 3a 20 53 65 74 74 69 6e 67  Caution: Setting
23f60 20 74 68 65 20 69 6d 6d 75 74 61 62 6c 65 0a 2a   the immutable.*
23f70 2a 20 20 20 20 20 70 72 6f 70 65 72 74 79 20 6f  *     property o
23f80 6e 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c  n a database fil
23f90 65 20 74 68 61 74 20 64 6f 65 73 20 69 6e 20 66  e that does in f
23fa0 61 63 74 20 63 68 61 6e 67 65 20 63 61 6e 20 72  act change can r
23fb0 65 73 75 6c 74 0a 2a 2a 20 20 20 20 20 69 6e 20  esult.**     in 
23fc0 69 6e 63 6f 72 72 65 63 74 20 71 75 65 72 79 20  incorrect query 
23fd0 72 65 73 75 6c 74 73 20 61 6e 64 2f 6f 72 20 5b  results and/or [
23fe0 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 20  SQLITE_CORRUPT] 
23ff0 65 72 72 6f 72 73 2e 0a 2a 2a 20 20 20 20 20 53  errors..**     S
24000 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45  ee also: [SQLITE
24010 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45  _IOCAP_IMMUTABLE
24020 5d 2e 0a 2a 2a 20 20 20 20 20 20 20 0a 2a 2a 20  ]..**       .** 
24030 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 53 70 65  </ul>.**.** ^Spe
24040 63 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f  cifying an unkno
24050 77 6e 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20  wn parameter in 
24060 74 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e  the query compon
24070 65 6e 74 20 6f 66 20 61 20 55 52 49 20 69 73 20  ent of a URI is 
24080 6e 6f 74 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 2e  not an.** error.
24090 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e    Future version
240a0 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68  s of SQLite migh
240b0 74 20 75 6e 64 65 72 73 74 61 6e 64 20 61 64 64  t understand add
240c0 69 74 69 6f 6e 61 6c 20 71 75 65 72 79 0a 2a 2a  itional query.**
240d0 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 53 65   parameters.  Se
240e0 65 20 22 5b 71 75 65 72 79 20 70 61 72 61 6d 65  e "[query parame
240f0 74 65 72 73 20 77 69 74 68 20 73 70 65 63 69 61  ters with specia
24100 6c 20 6d 65 61 6e 69 6e 67 20 74 6f 20 53 51 4c  l meaning to SQL
24110 69 74 65 5d 22 20 66 6f 72 0a 2a 2a 20 61 64 64  ite]" for.** add
24120 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74  itional informat
24130 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49  ion..**.** [[URI
24140 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c   filename exampl
24150 65 73 5d 5d 20 3c 68 33 3e 55 52 49 20 66 69 6c  es]] <h3>URI fil
24160 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73 3c 2f  ename examples</
24170 68 33 3e 0a 2a 2a 0a 2a 2a 20 3c 74 61 62 6c 65  h3>.**.** <table
24180 20 62 6f 72 64 65 72 3d 22 31 22 20 61 6c 69 67   border="1" alig
24190 6e 3d 63 65 6e 74 65 72 20 63 65 6c 6c 70 61 64  n=center cellpad
241a0 64 69 6e 67 3d 35 3e 0a 2a 2a 20 3c 74 72 3e 3c  ding=5>.** <tr><
241b0 74 68 3e 20 55 52 49 20 66 69 6c 65 6e 61 6d 65  th> URI filename
241c0 73 20 3c 74 68 3e 20 52 65 73 75 6c 74 73 0a 2a  s <th> Results.*
241d0 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a  * <tr><td> file:
241e0 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a  data.db <td> .**
241f0 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 74            Open t
24200 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62  he file "data.db
24210 22 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74  " in the current
24220 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 20 3c   directory..** <
24230 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f  tr><td> file:/ho
24240 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 3c  me/fred/data.db<
24250 62 72 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  br>.**          
24260 66 69 6c 65 3a 2f 2f 2f 68 6f 6d 65 2f 66 72 65  file:///home/fre
24270 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 0a  d/data.db <br> .
24280 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 65  **          file
24290 3a 2f 2f 6c 6f 63 61 6c 68 6f 73 74 2f 68 6f 6d  ://localhost/hom
242a0 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c  e/fred/data.db <
242b0 62 72 3e 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20  br> <td> .**    
242c0 20 20 20 20 20 20 4f 70 65 6e 20 74 68 65 20 64        Open the d
242d0 61 74 61 62 61 73 65 20 66 69 6c 65 20 22 2f 68  atabase file "/h
242e0 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
242f0 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66  "..** <tr><td> f
24300 69 6c 65 3a 2f 2f 64 61 72 6b 73 74 61 72 2f 68  ile://darkstar/h
24310 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
24320 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20   <td> .**       
24330 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 64 61     An error. "da
24340 72 6b 73 74 61 72 22 20 69 73 20 6e 6f 74 20 61  rkstar" is not a
24350 20 72 65 63 6f 67 6e 69 7a 65 64 20 61 75 74 68   recognized auth
24360 6f 72 69 74 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74  ority..** <tr><t
24370 64 20 73 74 79 6c 65 3d 22 77 68 69 74 65 2d 73  d style="white-s
24380 70 61 63 65 3a 6e 6f 77 72 61 70 22 3e 20 0a 2a  pace:nowrap"> .*
24390 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a  *          file:
243a0 2f 2f 2f 43 3a 2f 44 6f 63 75 6d 65 6e 74 73 25  ///C:/Documents%
243b0 32 30 61 6e 64 25 32 30 53 65 74 74 69 6e 67 73  20and%20Settings
243c0 2f 66 72 65 64 2f 44 65 73 6b 74 6f 70 2f 64 61  /fred/Desktop/da
243d0 74 61 2e 64 62 0a 2a 2a 20 20 20 20 20 3c 74 64  ta.db.**     <td
243e0 3e 20 57 69 6e 64 6f 77 73 20 6f 6e 6c 79 3a 20  > Windows only: 
243f0 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20 22 64  Open the file "d
24400 61 74 61 2e 64 62 22 20 6f 6e 20 66 72 65 64 27  ata.db" on fred'
24410 73 20 64 65 73 6b 74 6f 70 20 6f 6e 20 64 72 69  s desktop on dri
24420 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 43  ve.**          C
24430 3a 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65  :. Note that the
24440 20 25 32 30 20 65 73 63 61 70 69 6e 67 20 69 6e   %20 escaping in
24450 20 74 68 69 73 20 65 78 61 6d 70 6c 65 20 69 73   this example is
24460 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 0a 2a   not strictly .*
24470 2a 20 20 20 20 20 20 20 20 20 20 6e 65 63 65 73  *          neces
24480 73 61 72 79 20 2d 20 73 70 61 63 65 20 63 68 61  sary - space cha
24490 72 61 63 74 65 72 73 20 63 61 6e 20 62 65 20 75  racters can be u
244a0 73 65 64 20 6c 69 74 65 72 61 6c 6c 79 0a 2a 2a  sed literally.**
244b0 20 20 20 20 20 20 20 20 20 20 69 6e 20 55 52 49            in URI
244c0 20 66 69 6c 65 6e 61 6d 65 73 2e 0a 2a 2a 20 3c   filenames..** <
244d0 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74  tr><td> file:dat
244e0 61 2e 64 62 3f 6d 6f 64 65 3d 72 6f 26 63 61 63  a.db?mode=ro&cac
244f0 68 65 3d 70 72 69 76 61 74 65 20 3c 74 64 3e 20  he=private <td> 
24500 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65  .**          Ope
24510 6e 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22  n file "data.db"
24520 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20   in the current 
24530 64 69 72 65 63 74 6f 72 79 20 66 6f 72 20 72 65  directory for re
24540 61 64 2d 6f 6e 6c 79 20 61 63 63 65 73 73 2e 0a  ad-only access..
24550 2a 2a 20 20 20 20 20 20 20 20 20 20 52 65 67 61  **          Rega
24560 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65  rdless of whethe
24570 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 2d  r or not shared-
24580 63 61 63 68 65 20 6d 6f 64 65 20 69 73 20 65 6e  cache mode is en
24590 61 62 6c 65 64 20 62 79 0a 2a 2a 20 20 20 20 20  abled by.**     
245a0 20 20 20 20 20 64 65 66 61 75 6c 74 2c 20 75 73       default, us
245b0 65 20 61 20 70 72 69 76 61 74 65 20 63 61 63 68  e a private cach
245c0 65 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66  e..** <tr><td> f
245d0 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  ile:/home/fred/d
245e0 61 74 61 2e 64 62 3f 76 66 73 3d 75 6e 69 78 2d  ata.db?vfs=unix-
245f0 64 6f 74 66 69 6c 65 20 3c 74 64 3e 0a 2a 2a 20  dotfile <td>.** 
24600 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 66 69           Open fi
24610 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  le "/home/fred/d
24620 61 74 61 2e 64 62 22 2e 20 55 73 65 20 74 68 65  ata.db". Use the
24630 20 73 70 65 63 69 61 6c 20 56 46 53 20 22 75 6e   special VFS "un
24640 69 78 2d 64 6f 74 66 69 6c 65 22 0a 2a 2a 20 20  ix-dotfile".**  
24650 20 20 20 20 20 20 20 20 74 68 61 74 20 75 73 65          that use
24660 73 20 64 6f 74 2d 66 69 6c 65 73 20 69 6e 20 70  s dot-files in p
24670 6c 61 63 65 20 6f 66 20 70 6f 73 69 78 20 61 64  lace of posix ad
24680 76 69 73 6f 72 79 20 6c 6f 63 6b 69 6e 67 2e 0a  visory locking..
24690 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65  ** <tr><td> file
246a0 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 65  :data.db?mode=re
246b0 61 64 6f 6e 6c 79 20 3c 74 64 3e 20 0a 2a 2a 20  adonly <td> .** 
246c0 20 20 20 20 20 20 20 20 20 41 6e 20 65 72 72 6f           An erro
246d0 72 2e 20 22 72 65 61 64 6f 6e 6c 79 22 20 69 73  r. "readonly" is
246e0 20 6e 6f 74 20 61 20 76 61 6c 69 64 20 6f 70 74   not a valid opt
246f0 69 6f 6e 20 66 6f 72 20 74 68 65 20 22 6d 6f 64  ion for the "mod
24700 65 22 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  e" parameter..**
24710 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 0a 2a 2a 20   </table>.**.** 
24720 5e 55 52 49 20 68 65 78 61 64 65 63 69 6d 61 6c  ^URI hexadecimal
24730 20 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 65   escape sequence
24740 73 20 28 25 48 48 29 20 61 72 65 20 73 75 70 70  s (%HH) are supp
24750 6f 72 74 65 64 20 77 69 74 68 69 6e 20 74 68 65  orted within the
24760 20 70 61 74 68 20 61 6e 64 0a 2a 2a 20 71 75 65   path and.** que
24770 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66  ry components of
24780 20 61 20 55 52 49 2e 20 41 20 68 65 78 61 64 65   a URI. A hexade
24790 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71  cimal escape seq
247a0 75 65 6e 63 65 20 63 6f 6e 73 69 73 74 73 20 6f  uence consists o
247b0 66 20 61 0a 2a 2a 20 70 65 72 63 65 6e 74 20 73  f a.** percent s
247c0 69 67 6e 20 2d 20 22 25 22 20 2d 20 66 6f 6c 6c  ign - "%" - foll
247d0 6f 77 65 64 20 62 79 20 65 78 61 63 74 6c 79 20  owed by exactly 
247e0 74 77 6f 20 68 65 78 61 64 65 63 69 6d 61 6c 20  two hexadecimal 
247f0 64 69 67 69 74 73 20 0a 2a 2a 20 73 70 65 63 69  digits .** speci
24800 66 79 69 6e 67 20 61 6e 20 6f 63 74 65 74 20 76  fying an octet v
24810 61 6c 75 65 2e 20 5e 42 65 66 6f 72 65 20 74 68  alue. ^Before th
24820 65 20 70 61 74 68 20 6f 72 20 71 75 65 72 79 20  e path or query 
24830 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61 0a  components of a.
24840 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 20  ** URI filename 
24850 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 2c  are interpreted,
24860 20 74 68 65 79 20 61 72 65 20 65 6e 63 6f 64 65   they are encode
24870 64 20 75 73 69 6e 67 20 55 54 46 2d 38 20 61 6e  d using UTF-8 an
24880 64 20 61 6c 6c 20 0a 2a 2a 20 68 65 78 61 64 65  d all .** hexade
24890 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71  cimal escape seq
248a0 75 65 6e 63 65 73 20 72 65 70 6c 61 63 65 64 20  uences replaced 
248b0 62 79 20 61 20 73 69 6e 67 6c 65 20 62 79 74 65  by a single byte
248c0 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 0a   containing the.
248d0 2a 2a 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  ** corresponding
248e0 20 6f 63 74 65 74 2e 20 49 66 20 74 68 69 73 20   octet. If this 
248f0 70 72 6f 63 65 73 73 20 67 65 6e 65 72 61 74 65  process generate
24900 73 20 61 6e 20 69 6e 76 61 6c 69 64 20 55 54 46  s an invalid UTF
24910 2d 38 20 65 6e 63 6f 64 69 6e 67 2c 0a 2a 2a 20  -8 encoding,.** 
24920 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
24930 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
24940 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64   <b>Note to Wind
24950 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20  ows users:</b>  
24960 54 68 65 20 65 6e 63 6f 64 69 6e 67 20 75 73 65  The encoding use
24970 64 20 66 6f 72 20 74 68 65 20 66 69 6c 65 6e 61  d for the filena
24980 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f  me argument.** o
24990 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  f sqlite3_open()
249a0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65   and sqlite3_ope
249b0 6e 5f 76 32 28 29 20 6d 75 73 74 20 62 65 20 55  n_v2() must be U
249c0 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65 76  TF-8, not whatev
249d0 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20 69  er.** codepage i
249e0 73 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69  s currently defi
249f0 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20  ned.  Filenames 
24a00 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65 72  containing inter
24a10 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72  national.** char
24a20 61 63 74 65 72 73 20 6d 75 73 74 20 62 65 20 63  acters must be c
24a30 6f 6e 76 65 72 74 65 64 20 74 6f 20 55 54 46 2d  onverted to UTF-
24a40 38 20 70 72 69 6f 72 20 74 6f 20 70 61 73 73 69  8 prior to passi
24a50 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20  ng them into.** 
24a60 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f  sqlite3_open() o
24a70 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
24a80 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f  2()..**.** <b>No
24a90 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 52 75  te to Windows Ru
24aa0 6e 74 69 6d 65 20 75 73 65 72 73 3a 3c 2f 62 3e  ntime users:</b>
24ab0 20 20 54 68 65 20 74 65 6d 70 6f 72 61 72 79 20    The temporary 
24ac0 64 69 72 65 63 74 6f 72 79 20 6d 75 73 74 20 62  directory must b
24ad0 65 20 73 65 74 0a 2a 2a 20 70 72 69 6f 72 20 74  e set.** prior t
24ae0 6f 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65  o calling sqlite
24af0 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69  3_open() or sqli
24b00 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 20  te3_open_v2().  
24b10 4f 74 68 65 72 77 69 73 65 2c 20 76 61 72 69 6f  Otherwise, vario
24b20 75 73 0a 2a 2a 20 66 65 61 74 75 72 65 73 20 74  us.** features t
24b30 68 61 74 20 72 65 71 75 69 72 65 20 74 68 65 20  hat require the 
24b40 75 73 65 20 6f 66 20 74 65 6d 70 6f 72 61 72 79  use of temporary
24b50 20 66 69 6c 65 73 20 6d 61 79 20 66 61 69 6c 2e   files may fail.
24b60 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
24b70 20 5b 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64   [sqlite3_temp_d
24b80 69 72 65 63 74 6f 72 79 5d 0a 2a 2f 0a 53 51 4c  irectory].*/.SQL
24b90 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
24ba0 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73  te3_open(.  cons
24bb0 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65  t char *filename
24bc0 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  ,   /* Database 
24bd0 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29  filename (UTF-8)
24be0 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a   */.  sqlite3 **
24bf0 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a  ppDb          /*
24c00 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20   OUT: SQLite db 
24c10 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 53 51 4c  handle */.);.SQL
24c20 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
24c30 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f  te3_open16(.  co
24c40 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61  nst void *filena
24c50 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73  me,   /* Databas
24c60 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d  e filename (UTF-
24c70 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  16) */.  sqlite3
24c80 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20   **ppDb         
24c90 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20   /* OUT: SQLite 
24ca0 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a  db handle */.);.
24cb0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
24cc0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 0a  qlite3_open_v2(.
24cd0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69    const char *fi
24ce0 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74  lename,   /* Dat
24cf0 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28  abase filename (
24d00 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69  UTF-8) */.  sqli
24d10 74 65 33 20 2a 2a 70 70 44 62 2c 20 20 20 20 20  te3 **ppDb,     
24d20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69      /* OUT: SQLi
24d30 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a  te db handle */.
24d40 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 20 20 20    int flags,    
24d50 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 6c 61            /* Fla
24d60 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  gs */.  const ch
24d70 61 72 20 2a 7a 56 66 73 20 20 20 20 20 20 20 20  ar *zVfs        
24d80 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53 20 6d  /* Name of VFS m
24d90 6f 64 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f 0a  odule to use */.
24da0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
24db0 45 46 3a 20 4f 62 74 61 69 6e 20 56 61 6c 75 65  EF: Obtain Value
24dc0 73 20 46 6f 72 20 55 52 49 20 50 61 72 61 6d 65  s For URI Parame
24dd0 74 65 72 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ters.**.** These
24de0 20 61 72 65 20 75 74 69 6c 69 74 79 20 72 6f 75   are utility rou
24df0 74 69 6e 65 73 2c 20 75 73 65 66 75 6c 20 74 6f  tines, useful to
24e00 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
24e10 69 6f 6e 73 2c 20 74 68 61 74 20 63 68 65 63 6b  ions, that check
24e20 0a 2a 2a 20 74 6f 20 73 65 65 20 69 66 20 61 20  .** to see if a 
24e30 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 61  database file wa
24e40 73 20 61 20 55 52 49 20 74 68 61 74 20 63 6f 6e  s a URI that con
24e50 74 61 69 6e 65 64 20 61 20 73 70 65 63 69 66 69  tained a specifi
24e60 63 20 71 75 65 72 79 20 0a 2a 2a 20 70 61 72 61  c query .** para
24e70 6d 65 74 65 72 2c 20 61 6e 64 20 69 66 20 73 6f  meter, and if so
24e80 20 6f 62 74 61 69 6e 73 20 74 68 65 20 76 61 6c   obtains the val
24e90 75 65 20 6f 66 20 74 68 61 74 20 71 75 65 72 79  ue of that query
24ea0 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
24eb0 2a 20 49 66 20 46 20 69 73 20 74 68 65 20 64 61  * If F is the da
24ec0 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
24ed0 70 6f 69 6e 74 65 72 20 70 61 73 73 65 64 20 69  pointer passed i
24ee0 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 20  nto the xOpen() 
24ef0 6d 65 74 68 6f 64 20 6f 66 20 0a 2a 2a 20 61 20  method of .** a 
24f00 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  VFS implementati
24f10 6f 6e 20 77 68 65 6e 20 74 68 65 20 66 6c 61 67  on when the flag
24f20 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78  s parameter to x
24f30 4f 70 65 6e 28 29 20 68 61 73 20 6f 6e 65 20 6f  Open() has one o
24f40 72 20 0a 2a 2a 20 6d 6f 72 65 20 6f 66 20 74 68  r .** more of th
24f50 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55  e [SQLITE_OPEN_U
24f60 52 49 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4f  RI] or [SQLITE_O
24f70 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 20 62 69 74  PEN_MAIN_DB] bit
24f80 73 20 73 65 74 20 61 6e 64 0a 2a 2a 20 50 20 69  s set and.** P i
24f90 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
24fa0 65 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  e query paramete
24fb0 72 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74  r, then.** sqlit
24fc0 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72  e3_uri_parameter
24fd0 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20 74 68  (F,P) returns th
24fe0 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 50  e value of the P
24ff0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69 66  .** parameter if
25000 20 69 74 20 65 78 69 73 74 73 20 6f 72 20 61 20   it exists or a 
25010 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20  NULL pointer if 
25020 50 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 65 61  P does not appea
25030 72 20 61 73 20 61 20 0a 2a 2a 20 71 75 65 72 79  r as a .** query
25040 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 46 2e   parameter on F.
25050 20 20 49 66 20 50 20 69 73 20 61 20 71 75 65 72    If P is a quer
25060 79 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 46  y parameter of F
25070 0a 2a 2a 20 68 61 73 20 6e 6f 20 65 78 70 6c 69  .** has no expli
25080 63 69 74 20 76 61 6c 75 65 2c 20 74 68 65 6e 20  cit value, then 
25090 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61  sqlite3_uri_para
250a0 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 72  meter(F,P) retur
250b0 6e 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20  ns.** a pointer 
250c0 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69  to an empty stri
250d0 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ng..**.** The sq
250e0 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61  lite3_uri_boolea
250f0 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65  n(F,P,B) routine
25100 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 50 20   assumes that P 
25110 69 73 20 61 20 62 6f 6f 6c 65 61 6e 0a 2a 2a 20  is a boolean.** 
25120 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65  parameter and re
25130 74 75 72 6e 73 20 74 72 75 65 20 28 31 29 20 6f  turns true (1) o
25140 72 20 66 61 6c 73 65 20 28 30 29 20 61 63 63 6f  r false (0) acco
25150 72 64 69 6e 67 20 74 6f 20 74 68 65 20 76 61 6c  rding to the val
25160 75 65 0a 2a 2a 20 6f 66 20 50 2e 20 20 54 68 65  ue.** of P.  The
25170 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f   sqlite3_uri_boo
25180 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74  lean(F,P,B) rout
25190 69 6e 65 20 72 65 74 75 72 6e 73 20 74 72 75 65  ine returns true
251a0 20 28 31 29 20 69 66 20 74 68 65 0a 2a 2a 20 76   (1) if the.** v
251b0 61 6c 75 65 20 6f 66 20 71 75 65 72 79 20 70 61  alue of query pa
251c0 72 61 6d 65 74 65 72 20 50 20 69 73 20 6f 6e 65  rameter P is one
251d0 20 6f 66 20 22 79 65 73 22 2c 20 22 74 72 75 65   of "yes", "true
251e0 22 2c 20 6f 72 20 22 6f 6e 22 20 69 6e 20 61 6e  ", or "on" in an
251f0 79 0a 2a 2a 20 63 61 73 65 20 6f 72 20 69 66 20  y.** case or if 
25200 74 68 65 20 76 61 6c 75 65 20 62 65 67 69 6e 73  the value begins
25210 20 77 69 74 68 20 61 20 6e 6f 6e 2d 7a 65 72 6f   with a non-zero
25220 20 6e 75 6d 62 65 72 2e 20 20 54 68 65 20 0a 2a   number.  The .*
25230 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f  * sqlite3_uri_bo
25240 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75  olean(F,P,B) rou
25250 74 69 6e 65 73 20 72 65 74 75 72 6e 73 20 66 61  tines returns fa
25260 6c 73 65 20 28 30 29 20 69 66 20 74 68 65 20 76  lse (0) if the v
25270 61 6c 75 65 20 6f 66 0a 2a 2a 20 71 75 65 72 79  alue of.** query
25280 20 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20   parameter P is 
25290 6f 6e 65 20 6f 66 20 22 6e 6f 22 2c 20 22 66 61  one of "no", "fa
252a0 6c 73 65 22 2c 20 6f 72 20 22 6f 66 66 22 20 69  lse", or "off" i
252b0 6e 20 61 6e 79 20 63 61 73 65 20 6f 72 0a 2a 2a  n any case or.**
252c0 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 62 65   if the value be
252d0 67 69 6e 73 20 77 69 74 68 20 61 20 6e 75 6d 65  gins with a nume
252e0 72 69 63 20 7a 65 72 6f 2e 20 20 49 66 20 50 20  ric zero.  If P 
252f0 69 73 20 6e 6f 74 20 61 20 71 75 65 72 79 0a 2a  is not a query.*
25300 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 46  * parameter on F
25310 20 6f 72 20 69 66 20 74 68 65 20 76 61 6c 75 65   or if the value
25320 20 6f 66 20 50 20 69 73 20 64 6f 65 73 20 6e 6f   of P is does no
25330 74 20 6d 61 74 63 68 20 61 6e 79 20 6f 66 20 74  t match any of t
25340 68 65 0a 2a 2a 20 61 62 6f 76 65 2c 20 74 68 65  he.** above, the
25350 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f  n sqlite3_uri_bo
25360 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74  olean(F,P,B) ret
25370 75 72 6e 73 20 28 42 21 3d 30 29 2e 0a 2a 2a 0a  urns (B!=0)..**.
25380 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75  ** The sqlite3_u
25390 72 69 5f 69 6e 74 36 34 28 46 2c 50 2c 44 29 20  ri_int64(F,P,D) 
253a0 72 6f 75 74 69 6e 65 20 63 6f 6e 76 65 72 74 73  routine converts
253b0 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20   the value of P 
253c0 69 6e 74 6f 20 61 0a 2a 2a 20 36 34 2d 62 69 74  into a.** 64-bit
253d0 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20   signed integer 
253e0 61 6e 64 20 72 65 74 75 72 6e 73 20 74 68 61 74  and returns that
253f0 20 69 6e 74 65 67 65 72 2c 20 6f 72 20 44 20 69   integer, or D i
25400 66 20 50 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20  f P does not.** 
25410 65 78 69 73 74 2e 20 20 49 66 20 74 68 65 20 76  exist.  If the v
25420 61 6c 75 65 20 6f 66 20 50 20 69 73 20 73 6f 6d  alue of P is som
25430 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61  ething other tha
25440 6e 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74 68  n an integer, th
25450 65 6e 0a 2a 2a 20 7a 65 72 6f 20 69 73 20 72 65  en.** zero is re
25460 74 75 72 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 49  turned..** .** I
25470 66 20 46 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  f F is a NULL po
25480 69 6e 74 65 72 2c 20 74 68 65 6e 20 73 71 6c 69  inter, then sqli
25490 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65  te3_uri_paramete
254a0 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20 4e  r(F,P) returns N
254b0 55 4c 4c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74  ULL and.** sqlit
254c0 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46  e3_uri_boolean(F
254d0 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 20 42 2e  ,P,B) returns B.
254e0 20 20 49 66 20 46 20 69 73 20 6e 6f 74 20 61 20    If F is not a 
254f0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64  NULL pointer and
25500 0a 2a 2a 20 69 73 20 6e 6f 74 20 61 20 64 61 74  .** is not a dat
25510 61 62 61 73 65 20 66 69 6c 65 20 70 61 74 68 6e  abase file pathn
25520 61 6d 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74  ame pointer that
25530 20 53 51 4c 69 74 65 20 70 61 73 73 65 64 20 69   SQLite passed i
25540 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 0a 2a 2a  nto the xOpen.**
25550 20 56 46 53 20 6d 65 74 68 6f 64 2c 20 74 68 65   VFS method, the
25560 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f  n the behavior o
25570 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69  f this routine i
25580 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20  s undefined and 
25590 70 72 6f 62 61 62 6c 79 0a 2a 2a 20 75 6e 64 65  probably.** unde
255a0 73 69 72 61 62 6c 65 2e 0a 2a 2f 0a 53 51 4c 49  sirable..*/.SQLI
255b0 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61  TE_API const cha
255c0 72 20 2a 73 71 6c 69 74 65 33 5f 75 72 69 5f 70  r *sqlite3_uri_p
255d0 61 72 61 6d 65 74 65 72 28 63 6f 6e 73 74 20 63  arameter(const c
255e0 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 2c 20  har *zFilename, 
255f0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 72  const char *zPar
25600 61 6d 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  am);.SQLITE_API 
25610 69 6e 74 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  int sqlite3_uri_
25620 62 6f 6f 6c 65 61 6e 28 63 6f 6e 73 74 20 63 68  boolean(const ch
25630 61 72 20 2a 7a 46 69 6c 65 2c 20 63 6f 6e 73 74  ar *zFile, const
25640 20 63 68 61 72 20 2a 7a 50 61 72 61 6d 2c 20 69   char *zParam, i
25650 6e 74 20 62 44 65 66 61 75 6c 74 29 3b 0a 53 51  nt bDefault);.SQ
25660 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33  LITE_API sqlite3
25670 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75  _int64 sqlite3_u
25680 72 69 5f 69 6e 74 36 34 28 63 6f 6e 73 74 20 63  ri_int64(const c
25690 68 61 72 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  har*, const char
256a0 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
256b0 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  );.../*.** CAPI3
256c0 52 45 46 3a 20 45 72 72 6f 72 20 43 6f 64 65 73  REF: Error Codes
256d0 20 41 6e 64 20 4d 65 73 73 61 67 65 73 0a 2a 2a   And Messages.**
256e0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
256f0 5f 65 72 72 63 6f 64 65 28 29 20 69 6e 74 65 72  _errcode() inter
25700 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
25710 20 6e 75 6d 65 72 69 63 20 5b 72 65 73 75 6c 74   numeric [result
25720 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78   code] or.** [ex
25730 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
25740 64 65 5d 20 66 6f 72 20 74 68 65 20 6d 6f 73 74  de] for the most
25750 20 72 65 63 65 6e 74 20 66 61 69 6c 65 64 20 73   recent failed s
25760 71 6c 69 74 65 33 5f 2a 20 41 50 49 20 63 61 6c  qlite3_* API cal
25770 6c 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20  l.** associated 
25780 77 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 65  with a [database
25790 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 49 66   connection]. If
257a0 20 61 20 70 72 69 6f 72 20 41 50 49 20 63 61 6c   a prior API cal
257b0 6c 20 66 61 69 6c 65 64 0a 2a 2a 20 62 75 74 20  l failed.** but 
257c0 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
257d0 41 50 49 20 63 61 6c 6c 20 73 75 63 63 65 65 64  API call succeed
257e0 65 64 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76  ed, the return v
257f0 61 6c 75 65 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c  alue from.** sql
25800 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69  ite3_errcode() i
25810 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 5e 54  s undefined.  ^T
25820 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  he sqlite3_exten
25830 64 65 64 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a  ded_errcode().**
25840 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 68   interface is th
25850 65 20 73 61 6d 65 20 65 78 63 65 70 74 20 74 68  e same except th
25860 61 74 20 69 74 20 61 6c 77 61 79 73 20 72 65 74  at it always ret
25870 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 65 78  urns the .** [ex
25880 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
25890 64 65 5d 20 65 76 65 6e 20 77 68 65 6e 20 65 78  de] even when ex
258a0 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
258b0 64 65 73 20 61 72 65 0a 2a 2a 20 64 69 73 61 62  des are.** disab
258c0 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  led..**.** ^The 
258d0 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
258e0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 65 72 72   and sqlite3_err
258f0 6d 73 67 31 36 28 29 20 72 65 74 75 72 6e 20 45  msg16() return E
25900 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a  nglish-language.
25910 2a 2a 20 74 65 78 74 20 74 68 61 74 20 64 65 73  ** text that des
25920 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72  cribes the error
25930 2c 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d  , as either UTF-
25940 38 20 6f 72 20 55 54 46 2d 31 36 20 72 65 73 70  8 or UTF-16 resp
25950 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28 4d  ectively..** ^(M
25960 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68  emory to hold th
25970 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  e error message 
25980 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65  string is manage
25990 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a  d internally..**
259a0 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
259b0 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74   does not need t
259c0 6f 20 77 6f 72 72 79 20 61 62 6f 75 74 20 66 72  o worry about fr
259d0 65 65 69 6e 67 20 74 68 65 20 72 65 73 75 6c 74  eeing the result
259e0 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68  ..** However, th
259f0 65 20 65 72 72 6f 72 20 73 74 72 69 6e 67 20 6d  e error string m
25a00 69 67 68 74 20 62 65 20 6f 76 65 72 77 72 69 74  ight be overwrit
25a10 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74  ten or deallocat
25a20 65 64 20 62 79 0a 2a 2a 20 73 75 62 73 65 71 75  ed by.** subsequ
25a30 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68  ent calls to oth
25a40 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
25a50 61 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e 29 5e  ace functions.)^
25a60 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
25a70 74 65 33 5f 65 72 72 73 74 72 28 29 20 69 6e 74  te3_errstr() int
25a80 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
25a90 68 65 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75  he English-langu
25aa0 61 67 65 20 74 65 78 74 0a 2a 2a 20 74 68 61 74  age text.** that
25ab0 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20 5b   describes the [
25ac0 72 65 73 75 6c 74 20 63 6f 64 65 5d 2c 20 61 73  result code], as
25ad0 20 55 54 46 2d 38 2e 0a 2a 2a 20 5e 28 4d 65 6d   UTF-8..** ^(Mem
25ae0 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20  ory to hold the 
25af0 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74  error message st
25b00 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20  ring is managed 
25b10 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 61 6e  internally.** an
25b20 64 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 66 72  d must not be fr
25b30 65 65 64 20 62 79 20 74 68 65 20 61 70 70 6c 69  eed by the appli
25b40 63 61 74 69 6f 6e 29 5e 2e 0a 2a 2a 0a 2a 2a 20  cation)^..**.** 
25b50 57 68 65 6e 20 74 68 65 20 73 65 72 69 61 6c 69  When the seriali
25b60 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  zed [threading m
25b70 6f 64 65 5d 20 69 73 20 69 6e 20 75 73 65 2c 20  ode] is in use, 
25b80 69 74 20 6d 69 67 68 74 20 62 65 20 74 68 65 0a  it might be the.
25b90 2a 2a 20 63 61 73 65 20 74 68 61 74 20 61 20 73  ** case that a s
25ba0 65 63 6f 6e 64 20 65 72 72 6f 72 20 6f 63 63 75  econd error occu
25bb0 72 73 20 6f 6e 20 61 20 73 65 70 61 72 61 74 65  rs on a separate
25bc0 20 74 68 72 65 61 64 20 69 6e 20 62 65 74 77 65   thread in betwe
25bd0 65 6e 0a 2a 2a 20 74 68 65 20 74 69 6d 65 20 6f  en.** the time o
25be0 66 20 74 68 65 20 66 69 72 73 74 20 65 72 72 6f  f the first erro
25bf0 72 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 20 74  r and the call t
25c00 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63  o these interfac
25c10 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 61 74  es..** When that
25c20 20 68 61 70 70 65 6e 73 2c 20 74 68 65 20 73 65   happens, the se
25c30 63 6f 6e 64 20 65 72 72 6f 72 20 77 69 6c 6c 20  cond error will 
25c40 62 65 20 72 65 70 6f 72 74 65 64 20 73 69 6e 63  be reported sinc
25c50 65 20 74 68 65 73 65 0a 2a 2a 20 69 6e 74 65 72  e these.** inter
25c60 66 61 63 65 73 20 61 6c 77 61 79 73 20 72 65 70  faces always rep
25c70 6f 72 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63  ort the most rec
25c80 65 6e 74 20 72 65 73 75 6c 74 2e 20 20 54 6f 20  ent result.  To 
25c90 61 76 6f 69 64 0a 2a 2a 20 74 68 69 73 2c 20 65  avoid.** this, e
25ca0 61 63 68 20 74 68 72 65 61 64 20 63 61 6e 20 6f  ach thread can o
25cb0 62 74 61 69 6e 20 65 78 63 6c 75 73 69 76 65 20  btain exclusive 
25cc0 75 73 65 20 6f 66 20 74 68 65 20 5b 64 61 74 61  use of the [data
25cd0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
25ce0 20 44 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b 69 6e   D.** by invokin
25cf0 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  g [sqlite3_mutex
25d00 5f 65 6e 74 65 72 5d 28 5b 73 71 6c 69 74 65 33  _enter]([sqlite3
25d10 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 62  _db_mutex](D)) b
25d20 65 66 6f 72 65 20 62 65 67 69 6e 6e 69 6e 67 0a  efore beginning.
25d30 2a 2a 20 74 6f 20 75 73 65 20 44 20 61 6e 64 20  ** to use D and 
25d40 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65  invoking [sqlite
25d50 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 5d 28 5b  3_mutex_leave]([
25d60 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78  sqlite3_db_mutex
25d70 5d 28 44 29 29 20 61 66 74 65 72 0a 2a 2a 20 61  ](D)) after.** a
25d80 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20  ll calls to the 
25d90 69 6e 74 65 72 66 61 63 65 73 20 6c 69 73 74 65  interfaces liste
25da0 64 20 68 65 72 65 20 61 72 65 20 63 6f 6d 70 6c  d here are compl
25db0 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61  eted..**.** If a
25dc0 6e 20 69 6e 74 65 72 66 61 63 65 20 66 61 69 6c  n interface fail
25dd0 73 20 77 69 74 68 20 53 51 4c 49 54 45 5f 4d 49  s with SQLITE_MI
25de0 53 55 53 45 2c 20 74 68 61 74 20 6d 65 61 6e 73  SUSE, that means
25df0 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a   the interface.*
25e00 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64 20 69 6e  * was invoked in
25e10 63 6f 72 72 65 63 74 6c 79 20 62 79 20 74 68 65  correctly by the
25e20 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 49   application.  I
25e30 6e 20 74 68 61 74 20 63 61 73 65 2c 20 74 68 65  n that case, the
25e40 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 61  .** error code a
25e50 6e 64 20 6d 65 73 73 61 67 65 20 6d 61 79 20 6f  nd message may o
25e60 72 20 6d 61 79 20 6e 6f 74 20 62 65 20 73 65 74  r may not be set
25e70 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
25e80 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 72 72 63  int sqlite3_errc
25e90 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29  ode(sqlite3 *db)
25ea0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
25eb0 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65   sqlite3_extende
25ec0 64 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65  d_errcode(sqlite
25ed0 33 20 2a 64 62 29 3b 0a 53 51 4c 49 54 45 5f 41  3 *db);.SQLITE_A
25ee0 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  PI const char *s
25ef0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 73 71  qlite3_errmsg(sq
25f00 6c 69 74 65 33 2a 29 3b 0a 53 51 4c 49 54 45 5f  lite3*);.SQLITE_
25f10 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  API const void *
25f20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36  sqlite3_errmsg16
25f30 28 73 71 6c 69 74 65 33 2a 29 3b 0a 53 51 4c 49  (sqlite3*);.SQLI
25f40 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61  TE_API const cha
25f50 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 73 74  r *sqlite3_errst
25f60 72 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  r(int);../*.** C
25f70 41 50 49 33 52 45 46 3a 20 53 51 4c 20 53 74 61  API3REF: SQL Sta
25f80 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a  tement Object.**
25f90 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 65 70   KEYWORDS: {prep
25fa0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 7d 20  ared statement} 
25fb0 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  {prepared statem
25fc0 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69  ents}.**.** An i
25fd0 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
25fe0 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74  object represent
25ff0 73 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 73  s a single SQL s
26000 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 54 68 69  tatement..** Thi
26010 73 20 6f 62 6a 65 63 74 20 69 73 20 76 61 72 69  s object is vari
26020 6f 75 73 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 61  ously known as a
26030 20 22 70 72 65 70 61 72 65 64 20 73 74 61 74 65   "prepared state
26040 6d 65 6e 74 22 20 6f 72 20 61 0a 2a 2a 20 22 63  ment" or a.** "c
26050 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73 74 61 74  ompiled SQL stat
26060 65 6d 65 6e 74 22 20 6f 72 20 73 69 6d 70 6c 79  ement" or simply
26070 20 61 73 20 61 20 22 73 74 61 74 65 6d 65 6e 74   as a "statement
26080 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69 66  "..**.** The lif
26090 65 20 6f 66 20 61 20 73 74 61 74 65 6d 65 6e 74  e of a statement
260a0 20 6f 62 6a 65 63 74 20 67 6f 65 73 20 73 6f 6d   object goes som
260b0 65 74 68 69 6e 67 20 6c 69 6b 65 20 74 68 69 73  ething like this
260c0 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20  :.**.** <ol>.** 
260d0 3c 6c 69 3e 20 43 72 65 61 74 65 20 74 68 65 20  <li> Create the 
260e0 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71  object using [sq
260f0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
26100 28 29 5d 20 6f 72 20 61 20 72 65 6c 61 74 65 64  ()] or a related
26110 0a 2a 2a 20 20 20 20 20 20 66 75 6e 63 74 69 6f  .**      functio
26120 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64 20  n..** <li> Bind 
26130 76 61 6c 75 65 73 20 74 6f 20 5b 68 6f 73 74 20  values to [host 
26140 70 61 72 61 6d 65 74 65 72 73 5d 20 75 73 69 6e  parameters] usin
26150 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  g the sqlite3_bi
26160 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 20 20 20 69  nd_*().**      i
26170 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 3c 6c  nterfaces..** <l
26180 69 3e 20 52 75 6e 20 74 68 65 20 53 51 4c 20 62  i> Run the SQL b
26190 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  y calling [sqlit
261a0 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65 20 6f  e3_step()] one o
261b0 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a  r more times..**
261c0 20 3c 6c 69 3e 20 52 65 73 65 74 20 74 68 65 20   <li> Reset the 
261d0 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20  statement using 
261e0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
261f0 5d 20 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a 2a  ] then go back.*
26200 2a 20 20 20 20 20 20 74 6f 20 73 74 65 70 20 32  *      to step 2
26210 2e 20 20 44 6f 20 74 68 69 73 20 7a 65 72 6f 20  .  Do this zero 
26220 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a  or more times..*
26230 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20 74  * <li> Destroy t
26240 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20  he object using 
26250 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
26260 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a  e()]..** </ol>.*
26270 2a 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 64 6f  *.** Refer to do
26280 63 75 6d 65 6e 74 61 74 69 6f 6e 20 6f 6e 20 69  cumentation on i
26290 6e 64 69 76 69 64 75 61 6c 20 6d 65 74 68 6f 64  ndividual method
262a0 73 20 61 62 6f 76 65 20 66 6f 72 20 61 64 64 69  s above for addi
262b0 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d  tional.** inform
262c0 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65  ation..*/.typede
262d0 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
262e0 5f 73 74 6d 74 20 73 71 6c 69 74 65 33 5f 73 74  _stmt sqlite3_st
262f0 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  mt;../*.** CAPI3
26300 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65 20 4c 69  REF: Run-time Li
26310 6d 69 74 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69  mits.**.** ^(Thi
26320 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f  s interface allo
26330 77 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 76  ws the size of v
26340 61 72 69 6f 75 73 20 63 6f 6e 73 74 72 75 63 74  arious construct
26350 73 20 74 6f 20 62 65 20 6c 69 6d 69 74 65 64 0a  s to be limited.
26360 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65 63 74 69  ** on a connecti
26370 6f 6e 20 62 79 20 63 6f 6e 6e 65 63 74 69 6f 6e  on by connection
26380 20 62 61 73 69 73 2e 20 20 54 68 65 20 66 69 72   basis.  The fir
26390 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  st parameter is 
263a0 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  the.** [database
263b0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 68 6f   connection] who
263c0 73 65 20 6c 69 6d 69 74 20 69 73 20 74 6f 20 62  se limit is to b
263d0 65 20 73 65 74 20 6f 72 20 71 75 65 72 69 65 64  e set or queried
263e0 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64  .  The.** second
263f0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6f 6e   parameter is on
26400 65 20 6f 66 20 74 68 65 20 5b 6c 69 6d 69 74 20  e of the [limit 
26410 63 61 74 65 67 6f 72 69 65 73 5d 20 74 68 61 74  categories] that
26420 20 64 65 66 69 6e 65 20 61 0a 2a 2a 20 63 6c 61   define a.** cla
26430 73 73 20 6f 66 20 63 6f 6e 73 74 72 75 63 74 73  ss of constructs
26440 20 74 6f 20 62 65 20 73 69 7a 65 20 6c 69 6d 69   to be size limi
26450 74 65 64 2e 20 20 54 68 65 20 74 68 69 72 64 20  ted.  The third 
26460 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
26470 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69 74 20 66 6f  .** new limit fo
26480 72 20 74 68 61 74 20 63 6f 6e 73 74 72 75 63 74  r that construct
26490 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  .)^.**.** ^If th
264a0 65 20 6e 65 77 20 6c 69 6d 69 74 20 69 73 20 61  e new limit is a
264b0 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62 65 72   negative number
264c0 2c 20 74 68 65 20 6c 69 6d 69 74 20 69 73 20 75  , the limit is u
264d0 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 5e 28 46  nchanged..** ^(F
264e0 6f 72 20 65 61 63 68 20 6c 69 6d 69 74 20 63 61  or each limit ca
264f0 74 65 67 6f 72 79 20 53 51 4c 49 54 45 5f 4c 49  tegory SQLITE_LI
26500 4d 49 54 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 20  MIT_<i>NAME</i> 
26510 74 68 65 72 65 20 69 73 20 61 20 0a 2a 2a 20 5b  there is a .** [
26520 6c 69 6d 69 74 73 20 7c 20 68 61 72 64 20 75 70  limits | hard up
26530 70 65 72 20 62 6f 75 6e 64 5d 0a 2a 2a 20 73 65  per bound].** se
26540 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  t at compile-tim
26550 65 20 62 79 20 61 20 43 20 70 72 65 70 72 6f 63  e by a C preproc
26560 65 73 73 6f 72 20 6d 61 63 72 6f 20 63 61 6c 6c  essor macro call
26570 65 64 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20  ed.** [limits | 
26580 53 51 4c 49 54 45 5f 4d 41 58 5f 3c 69 3e 4e 41  SQLITE_MAX_<i>NA
26590 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a 20 28 54 68 65  ME</i>]..** (The
265a0 20 22 5f 4c 49 4d 49 54 5f 22 20 69 6e 20 74 68   "_LIMIT_" in th
265b0 65 20 6e 61 6d 65 20 69 73 20 63 68 61 6e 67 65  e name is change
265c0 64 20 74 6f 20 22 5f 4d 41 58 5f 22 2e 29 29 5e  d to "_MAX_".))^
265d0 0a 2a 2a 20 5e 41 74 74 65 6d 70 74 73 20 74 6f  .** ^Attempts to
265e0 20 69 6e 63 72 65 61 73 65 20 61 20 6c 69 6d 69   increase a limi
265f0 74 20 61 62 6f 76 65 20 69 74 73 20 68 61 72 64  t above its hard
26600 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61 72 65   upper bound are
26610 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79 20 74 72 75  .** silently tru
26620 6e 63 61 74 65 64 20 74 6f 20 74 68 65 20 68 61  ncated to the ha
26630 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 2e 0a  rd upper bound..
26640 2a 2a 0a 2a 2a 20 5e 52 65 67 61 72 64 6c 65 73  **.** ^Regardles
26650 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20  s of whether or 
26660 6e 6f 74 20 74 68 65 20 6c 69 6d 69 74 20 77 61  not the limit wa
26670 73 20 63 68 61 6e 67 65 64 2c 20 74 68 65 20 0a  s changed, the .
26680 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  ** [sqlite3_limi
26690 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  t()] interface r
266a0 65 74 75 72 6e 73 20 74 68 65 20 70 72 69 6f 72  eturns the prior
266b0 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 6c 69   value of the li
266c0 6d 69 74 2e 0a 2a 2a 20 5e 48 65 6e 63 65 2c 20  mit..** ^Hence, 
266d0 74 6f 20 66 69 6e 64 20 74 68 65 20 63 75 72 72  to find the curr
266e0 65 6e 74 20 76 61 6c 75 65 20 6f 66 20 61 20 6c  ent value of a l
266f0 69 6d 69 74 20 77 69 74 68 6f 75 74 20 63 68 61  imit without cha
26700 6e 67 69 6e 67 20 69 74 2c 0a 2a 2a 20 73 69 6d  nging it,.** sim
26710 70 6c 79 20 69 6e 76 6f 6b 65 20 74 68 69 73 20  ply invoke this 
26720 69 6e 74 65 72 66 61 63 65 20 77 69 74 68 20 74  interface with t
26730 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
26740 65 72 20 73 65 74 20 74 6f 20 2d 31 2e 0a 2a 2a  er set to -1..**
26750 0a 2a 2a 20 52 75 6e 2d 74 69 6d 65 20 6c 69 6d  .** Run-time lim
26760 69 74 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64  its are intended
26770 20 66 6f 72 20 75 73 65 20 69 6e 20 61 70 70 6c   for use in appl
26780 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6d 61  ications that ma
26790 6e 61 67 65 0a 2a 2a 20 62 6f 74 68 20 74 68 65  nage.** both the
267a0 69 72 20 6f 77 6e 20 69 6e 74 65 72 6e 61 6c 20  ir own internal 
267b0 64 61 74 61 62 61 73 65 20 61 6e 64 20 61 6c 73  database and als
267c0 6f 20 64 61 74 61 62 61 73 65 73 20 74 68 61 74  o databases that
267d0 20 61 72 65 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a   are controlled.
267e0 2a 2a 20 62 79 20 75 6e 74 72 75 73 74 65 64 20  ** by untrusted 
267f0 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73  external sources
26800 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 61 70  .  An example ap
26810 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67 68 74 20  plication might 
26820 62 65 20 61 0a 2a 2a 20 77 65 62 20 62 72 6f 77  be a.** web brow
26830 73 65 72 20 74 68 61 74 20 68 61 73 20 69 74 73  ser that has its
26840 20 6f 77 6e 20 64 61 74 61 62 61 73 65 73 20 66   own databases f
26850 6f 72 20 73 74 6f 72 69 6e 67 20 68 69 73 74 6f  or storing histo
26860 72 79 20 61 6e 64 0a 2a 2a 20 73 65 70 61 72 61  ry and.** separa
26870 74 65 20 64 61 74 61 62 61 73 65 73 20 63 6f 6e  te databases con
26880 74 72 6f 6c 6c 65 64 20 62 79 20 4a 61 76 61 53  trolled by JavaS
26890 63 72 69 70 74 20 61 70 70 6c 69 63 61 74 69 6f  cript applicatio
268a0 6e 73 20 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a  ns downloaded.**
268b0 20 6f 66 66 20 74 68 65 20 49 6e 74 65 72 6e 65   off the Interne
268c0 74 2e 20 20 54 68 65 20 69 6e 74 65 72 6e 61 6c  t.  The internal
268d0 20 64 61 74 61 62 61 73 65 73 20 63 61 6e 20 62   databases can b
268e0 65 20 67 69 76 65 6e 20 74 68 65 0a 2a 2a 20 6c  e given the.** l
268f0 61 72 67 65 2c 20 64 65 66 61 75 6c 74 20 6c 69  arge, default li
26900 6d 69 74 73 2e 20 20 44 61 74 61 62 61 73 65 73  mits.  Databases
26910 20 6d 61 6e 61 67 65 64 20 62 79 20 65 78 74 65   managed by exte
26920 72 6e 61 6c 20 73 6f 75 72 63 65 73 20 63 61 6e  rnal sources can
26930 0a 2a 2a 20 62 65 20 67 69 76 65 6e 20 6d 75 63  .** be given muc
26940 68 20 73 6d 61 6c 6c 65 72 20 6c 69 6d 69 74 73  h smaller limits
26950 20 64 65 73 69 67 6e 65 64 20 74 6f 20 70 72 65   designed to pre
26960 76 65 6e 74 20 61 20 64 65 6e 69 61 6c 20 6f 66  vent a denial of
26970 20 73 65 72 76 69 63 65 0a 2a 2a 20 61 74 74 61   service.** atta
26980 63 6b 2e 20 20 44 65 76 65 6c 6f 70 65 72 73 20  ck.  Developers 
26990 6d 69 67 68 74 20 61 6c 73 6f 20 77 61 6e 74 20  might also want 
269a0 74 6f 20 75 73 65 20 74 68 65 20 5b 73 71 6c 69  to use the [sqli
269b0 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
269c0 65 72 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61  er()].** interfa
269d0 63 65 20 74 6f 20 66 75 72 74 68 65 72 20 63 6f  ce to further co
269e0 6e 74 72 6f 6c 20 75 6e 74 72 75 73 74 65 64 20  ntrol untrusted 
269f0 53 51 4c 2e 20 20 54 68 65 20 73 69 7a 65 20 6f  SQL.  The size o
26a00 66 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  f the database.*
26a10 2a 20 63 72 65 61 74 65 64 20 62 79 20 61 6e 20  * created by an 
26a20 75 6e 74 72 75 73 74 65 64 20 73 63 72 69 70 74  untrusted script
26a30 20 63 61 6e 20 62 65 20 63 6f 6e 74 61 69 6e 65   can be containe
26a40 64 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b  d using the.** [
26a50 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20  max_page_count] 
26a60 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20  [PRAGMA]..**.** 
26a70 4e 65 77 20 72 75 6e 2d 74 69 6d 65 20 6c 69 6d  New run-time lim
26a80 69 74 20 63 61 74 65 67 6f 72 69 65 73 20 6d 61  it categories ma
26a90 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75  y be added in fu
26aa0 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a  ture releases..*
26ab0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
26ac0 20 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 73   sqlite3_limit(s
26ad0 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 69 64 2c  qlite3*, int id,
26ae0 20 69 6e 74 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f   int newVal);../
26af0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
26b00 75 6e 2d 54 69 6d 65 20 4c 69 6d 69 74 20 43 61  un-Time Limit Ca
26b10 74 65 67 6f 72 69 65 73 0a 2a 2a 20 4b 45 59 57  tegories.** KEYW
26b20 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63 61 74  ORDS: {limit cat
26b30 65 67 6f 72 79 7d 20 7b 2a 6c 69 6d 69 74 20 63  egory} {*limit c
26b40 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a  ategories}.**.**
26b50 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73   These constants
26b60 20 64 65 66 69 6e 65 20 76 61 72 69 6f 75 73 20   define various 
26b70 70 65 72 66 6f 72 6d 61 6e 63 65 20 6c 69 6d 69  performance limi
26b80 74 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62  ts.** that can b
26b90 65 20 6c 6f 77 65 72 65 64 20 61 74 20 72 75 6e  e lowered at run
26ba0 2d 74 69 6d 65 20 75 73 69 6e 67 20 5b 73 71 6c  -time using [sql
26bb0 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a  ite3_limit()]..*
26bc0 2a 20 54 68 65 20 73 79 6e 6f 70 73 69 73 20 6f  * The synopsis o
26bd0 66 20 74 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f  f the meanings o
26be0 66 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c 69  f the various li
26bf0 6d 69 74 73 20 69 73 20 73 68 6f 77 6e 20 62 65  mits is shown be
26c00 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e  low..** Addition
26c10 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  al information i
26c20 73 20 61 76 61 69 6c 61 62 6c 65 20 61 74 20 5b  s available at [
26c30 6c 69 6d 69 74 73 20 7c 20 4c 69 6d 69 74 73 20  limits | Limits 
26c40 69 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a  in SQLite]..**.*
26c50 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49  * <dl>.** [[SQLI
26c60 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d  TE_LIMIT_LENGTH]
26c70 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
26c80 49 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e  IMIT_LENGTH</dt>
26c90 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
26ca0 6d 75 6d 20 73 69 7a 65 20 6f 66 20 61 6e 79 20  mum size of any 
26cb0 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 6f  string or BLOB o
26cc0 72 20 74 61 62 6c 65 20 72 6f 77 2c 20 69 6e 20  r table row, in 
26cd0 62 79 74 65 73 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a  bytes.<dd>)^.**.
26ce0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
26cf0 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 5d 5d 20 5e  T_SQL_LENGTH]] ^
26d00 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
26d10 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74  T_SQL_LENGTH</dt
26d20 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
26d30 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 61  imum length of a
26d40 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  n SQL statement,
26d50 20 69 6e 20 62 79 74 65 73 2e 3c 2f 64 64 3e 29   in bytes.</dd>)
26d60 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
26d70 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 5d 5d 20  _LIMIT_COLUMN]] 
26d80 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
26d90 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a  IT_COLUMN</dt>.*
26da0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
26db0 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  m number of colu
26dc0 6d 6e 73 20 69 6e 20 61 20 74 61 62 6c 65 20 64  mns in a table d
26dd0 65 66 69 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20  efinition or in 
26de0 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65  the.** result se
26df0 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20  t of a [SELECT] 
26e00 6f 72 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e  or the maximum n
26e10 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
26e20 20 69 6e 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20   in an index.** 
26e30 6f 72 20 69 6e 20 61 6e 20 4f 52 44 45 52 20 42  or in an ORDER B
26e40 59 20 6f 72 20 47 52 4f 55 50 20 42 59 20 63 6c  Y or GROUP BY cl
26e50 61 75 73 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  ause.</dd>)^.**.
26e60 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
26e70 54 5f 45 58 50 52 5f 44 45 50 54 48 5d 5d 20 5e  T_EXPR_DEPTH]] ^
26e80 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
26e90 54 5f 45 58 50 52 5f 44 45 50 54 48 3c 2f 64 74  T_EXPR_DEPTH</dt
26ea0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
26eb0 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 74 68  imum depth of th
26ec0 65 20 70 61 72 73 65 20 74 72 65 65 20 6f 6e 20  e parse tree on 
26ed0 61 6e 79 20 65 78 70 72 65 73 73 69 6f 6e 2e 3c  any expression.<
26ee0 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
26ef0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50  QLITE_LIMIT_COMP
26f00 4f 55 4e 44 5f 53 45 4c 45 43 54 5d 5d 20 5e 28  OUND_SELECT]] ^(
26f10 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
26f20 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54  _COMPOUND_SELECT
26f30 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
26f40 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
26f50 6f 66 20 74 65 72 6d 73 20 69 6e 20 61 20 63 6f  of terms in a co
26f60 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54 20 73 74  mpound SELECT st
26f70 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29 5e 0a  atement.</dd>)^.
26f80 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
26f90 49 4d 49 54 5f 56 44 42 45 5f 4f 50 5d 5d 20 5e  IMIT_VDBE_OP]] ^
26fa0 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
26fb0 54 5f 56 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a  T_VDBE_OP</dt>.*
26fc0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
26fd0 6d 20 6e 75 6d 62 65 72 20 6f 66 20 69 6e 73 74  m number of inst
26fe0 72 75 63 74 69 6f 6e 73 20 69 6e 20 61 20 76 69  ructions in a vi
26ff0 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 70 72  rtual machine pr
27000 6f 67 72 61 6d 0a 2a 2a 20 75 73 65 64 20 74 6f  ogram.** used to
27010 20 69 6d 70 6c 65 6d 65 6e 74 20 61 6e 20 53 51   implement an SQ
27020 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 54 68  L statement.  Th
27030 69 73 20 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20  is limit is not 
27040 63 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 65 6e 66  currently.** enf
27050 6f 72 63 65 64 2c 20 74 68 6f 75 67 68 20 74 68  orced, though th
27060 61 74 20 6d 69 67 68 74 20 62 65 20 61 64 64 65  at might be adde
27070 64 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65  d in some future
27080 20 72 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53   release of.** S
27090 51 4c 69 74 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  QLite.</dd>)^.**
270a0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
270b0 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d  IT_FUNCTION_ARG]
270c0 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
270d0 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52  IMIT_FUNCTION_AR
270e0 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  G</dt>.** <dd>Th
270f0 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
27100 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e   of arguments on
27110 20 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64   a function.</dd
27120 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
27130 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45  TE_LIMIT_ATTACHE
27140 44 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  D]] ^(<dt>SQLITE
27150 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 3c  _LIMIT_ATTACHED<
27160 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
27170 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
27180 66 20 5b 41 54 54 41 43 48 20 7c 20 61 74 74 61  f [ATTACH | atta
27190 63 68 65 64 20 64 61 74 61 62 61 73 65 73 5d 2e  ched databases].
271a0 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  )^</dd>.**.** [[
271b0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b  SQLITE_LIMIT_LIK
271c0 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48  E_PATTERN_LENGTH
271d0 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49  ]].** ^(<dt>SQLI
271e0 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41  TE_LIMIT_LIKE_PA
271f0 54 54 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74  TTERN_LENGTH</dt
27200 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
27210 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 74  imum length of t
27220 68 65 20 70 61 74 74 65 72 6e 20 61 72 67 75 6d  he pattern argum
27230 65 6e 74 20 74 6f 20 74 68 65 20 5b 4c 49 4b 45  ent to the [LIKE
27240 5d 20 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f  ] or.** [GLOB] o
27250 70 65 72 61 74 6f 72 73 2e 3c 2f 64 64 3e 29 5e  perators.</dd>)^
27260 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
27270 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e  LIMIT_VARIABLE_N
27280 55 4d 42 45 52 5d 5d 0a 2a 2a 20 5e 28 3c 64 74  UMBER]].** ^(<dt
27290 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41  >SQLITE_LIMIT_VA
272a0 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64  RIABLE_NUMBER</d
272b0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
272c0 78 69 6d 75 6d 20 69 6e 64 65 78 20 6e 75 6d 62  ximum index numb
272d0 65 72 20 6f 66 20 61 6e 79 20 5b 70 61 72 61 6d  er of any [param
272e0 65 74 65 72 5d 20 69 6e 20 61 6e 20 53 51 4c 20  eter] in an SQL 
272f0 73 74 61 74 65 6d 65 6e 74 2e 29 5e 0a 2a 2a 0a  statement.)^.**.
27300 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
27310 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 5d  T_TRIGGER_DEPTH]
27320 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
27330 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50  IMIT_TRIGGER_DEP
27340 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
27350 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68  he maximum depth
27360 20 6f 66 20 72 65 63 75 72 73 69 6f 6e 20 66 6f   of recursion fo
27370 72 20 74 72 69 67 67 65 72 73 2e 3c 2f 64 64 3e  r triggers.</dd>
27380 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
27390 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54  E_LIMIT_WORKER_T
273a0 48 52 45 41 44 53 5d 5d 20 5e 28 3c 64 74 3e 53  HREADS]] ^(<dt>S
273b0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b  QLITE_LIMIT_WORK
273c0 45 52 5f 54 48 52 45 41 44 53 3c 2f 64 74 3e 0a  ER_THREADS</dt>.
273d0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
273e0 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 75 78  um number of aux
273f0 69 6c 69 61 72 79 20 77 6f 72 6b 65 72 20 74 68  iliary worker th
27400 72 65 61 64 73 20 74 68 61 74 20 61 20 73 69 6e  reads that a sin
27410 67 6c 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  gle.** [prepared
27420 20 73 74 61 74 65 6d 65 6e 74 5d 20 6d 61 79 20   statement] may 
27430 73 74 61 72 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  start.</dd>)^.**
27440 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e   </dl>.*/.#defin
27450 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  e SQLITE_LIMIT_L
27460 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20  ENGTH           
27470 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69           0.#defi
27480 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
27490 53 51 4c 5f 4c 45 4e 47 54 48 20 20 20 20 20 20  SQL_LENGTH      
274a0 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66            1.#def
274b0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
274c0 5f 43 4f 4c 55 4d 4e 20 20 20 20 20 20 20 20 20  _COLUMN         
274d0 20 20 20 20 20 20 20 20 20 20 20 32 0a 23 64 65             2.#de
274e0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
274f0 54 5f 45 58 50 52 5f 44 45 50 54 48 20 20 20 20  T_EXPR_DEPTH    
27500 20 20 20 20 20 20 20 20 20 20 20 20 33 0a 23 64              3.#d
27510 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
27520 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45  IT_COMPOUND_SELE
27530 43 54 20 20 20 20 20 20 20 20 20 20 20 34 0a 23  CT           4.#
27540 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
27550 4d 49 54 5f 56 44 42 45 5f 4f 50 20 20 20 20 20  MIT_VDBE_OP     
27560 20 20 20 20 20 20 20 20 20 20 20 20 20 20 35 0a                5.
27570 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
27580 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52  IMIT_FUNCTION_AR
27590 47 20 20 20 20 20 20 20 20 20 20 20 20 20 20 36  G              6
275a0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
275b0 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 20 20  LIMIT_ATTACHED  
275c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
275d0 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  7.#define SQLITE
275e0 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54  _LIMIT_LIKE_PATT
275f0 45 52 4e 5f 4c 45 4e 47 54 48 20 20 20 20 20 20  ERN_LENGTH      
27600 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   8.#define SQLIT
27610 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45  E_LIMIT_VARIABLE
27620 5f 4e 55 4d 42 45 52 20 20 20 20 20 20 20 20 20  _NUMBER         
27630 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    9.#define SQLI
27640 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52  TE_LIMIT_TRIGGER
27650 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20  _DEPTH          
27660 20 20 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c    10.#define SQL
27670 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52  ITE_LIMIT_WORKER
27680 5f 54 48 52 45 41 44 53 20 20 20 20 20 20 20 20  _THREADS        
27690 20 20 20 31 31 0a 0a 2f 2a 0a 2a 2a 20 43 41 50     11../*.** CAP
276a0 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67  I3REF: Compiling
276b0 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e   An SQL Statemen
276c0 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  t.** KEYWORDS: {
276d0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f  SQL statement co
276e0 6d 70 69 6c 65 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f  mpiler}.**.** To
276f0 20 65 78 65 63 75 74 65 20 61 6e 20 53 51 4c 20   execute an SQL 
27700 71 75 65 72 79 2c 20 69 74 20 6d 75 73 74 20 66  query, it must f
27710 69 72 73 74 20 62 65 20 63 6f 6d 70 69 6c 65 64  irst be compiled
27720 20 69 6e 74 6f 20 61 20 62 79 74 65 2d 63 6f 64   into a byte-cod
27730 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 69  e.** program usi
27740 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20  ng one of these 
27750 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20  routines..**.** 
27760 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
27770 6e 74 2c 20 22 64 62 22 2c 20 69 73 20 61 20 5b  nt, "db", is a [
27780 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
27790 69 6f 6e 5d 20 6f 62 74 61 69 6e 65 64 20 66 72  ion] obtained fr
277a0 6f 6d 20 61 0a 2a 2a 20 70 72 69 6f 72 20 73 75  om a.** prior su
277b0 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f  ccessful call to
277c0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
277d0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ], [sqlite3_open
277e0 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  _v2()] or.** [sq
277f0 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e  lite3_open16()].
27800 20 20 54 68 65 20 64 61 74 61 62 61 73 65 20 63    The database c
27810 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e  onnection must n
27820 6f 74 20 68 61 76 65 20 62 65 65 6e 20 63 6c 6f  ot have been clo
27830 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  sed..**.** The s
27840 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20  econd argument, 
27850 22 7a 53 71 6c 22 2c 20 69 73 20 74 68 65 20 73  "zSql", is the s
27860 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63  tatement to be c
27870 6f 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64  ompiled, encoded
27880 0a 2a 2a 20 61 73 20 65 69 74 68 65 72 20 55 54  .** as either UT
27890 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e 20 20  F-8 or UTF-16.  
278a0 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70  The sqlite3_prep
278b0 61 72 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  are() and sqlite
278c0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 0a 2a  3_prepare_v2().*
278d0 2a 20 69 6e 74 65 72 66 61 63 65 73 20 75 73 65  * interfaces use
278e0 20 55 54 46 2d 38 2c 20 61 6e 64 20 73 71 6c 69   UTF-8, and sqli
278f0 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 20  te3_prepare16() 
27900 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70  and sqlite3_prep
27910 61 72 65 31 36 5f 76 32 28 29 0a 2a 2a 20 75 73  are16_v2().** us
27920 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20  e UTF-16..**.** 
27930 5e 49 66 20 74 68 65 20 6e 42 79 74 65 20 61 72  ^If the nByte ar
27940 67 75 6d 65 6e 74 20 69 73 20 6c 65 73 73 20 74  gument is less t
27950 68 61 6e 20 7a 65 72 6f 2c 20 74 68 65 6e 20 7a  han zero, then z
27960 53 71 6c 20 69 73 20 72 65 61 64 20 75 70 20 74  Sql is read up t
27970 6f 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 7a  o the.** first z
27980 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20  ero terminator. 
27990 5e 49 66 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e  ^If nByte is non
279a0 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20  -negative, then 
279b0 69 74 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75  it is the maximu
279c0 6d 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 20  m.** number of  
279d0 62 79 74 65 73 20 72 65 61 64 20 66 72 6f 6d 20  bytes read from 
279e0 7a 53 71 6c 2e 20 20 5e 57 68 65 6e 20 6e 42 79  zSql.  ^When nBy
279f0 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69  te is non-negati
27a00 76 65 2c 20 74 68 65 0a 2a 2a 20 7a 53 71 6c 20  ve, the.** zSql 
27a10 73 74 72 69 6e 67 20 65 6e 64 73 20 61 74 20 65  string ends at e
27a20 69 74 68 65 72 20 74 68 65 20 66 69 72 73 74 20  ither the first 
27a30 27 5c 30 30 30 27 20 6f 72 20 27 5c 75 30 30 30  '\000' or '\u000
27a40 30 27 20 63 68 61 72 61 63 74 65 72 20 6f 72 0a  0' character or.
27a50 2a 2a 20 74 68 65 20 6e 42 79 74 65 2d 74 68 20  ** the nByte-th 
27a60 62 79 74 65 2c 20 77 68 69 63 68 65 76 65 72 20  byte, whichever 
27a70 63 6f 6d 65 73 20 66 69 72 73 74 2e 20 49 66 20  comes first. If 
27a80 74 68 65 20 63 61 6c 6c 65 72 20 6b 6e 6f 77 73  the caller knows
27a90 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 73 75 70  .** that the sup
27aa0 70 6c 69 65 64 20 73 74 72 69 6e 67 20 69 73 20  plied string is 
27ab0 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c 20  nul-terminated, 
27ac0 74 68 65 6e 20 74 68 65 72 65 20 69 73 20 61 20  then there is a 
27ad0 73 6d 61 6c 6c 0a 2a 2a 20 70 65 72 66 6f 72 6d  small.** perform
27ae0 61 6e 63 65 20 61 64 76 61 6e 74 61 67 65 20 74  ance advantage t
27af0 6f 20 62 65 20 67 61 69 6e 65 64 20 62 79 20 70  o be gained by p
27b00 61 73 73 69 6e 67 20 61 6e 20 6e 42 79 74 65 20  assing an nByte 
27b10 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 0a 2a  parameter that.*
27b20 2a 20 69 73 20 65 71 75 61 6c 20 74 6f 20 74 68  * is equal to th
27b30 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
27b40 73 20 69 6e 20 74 68 65 20 69 6e 70 75 74 20 73  s in the input s
27b50 74 72 69 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 69  tring <i>includi
27b60 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e 75  ng</i>.** the nu
27b70 6c 2d 74 65 72 6d 69 6e 61 74 6f 72 20 62 79 74  l-terminator byt
27b80 65 73 20 61 73 20 74 68 69 73 20 73 61 76 65 73  es as this saves
27b90 20 53 51 4c 69 74 65 20 66 72 6f 6d 20 68 61 76   SQLite from hav
27ba0 69 6e 67 20 74 6f 0a 2a 2a 20 6d 61 6b 65 20 61  ing to.** make a
27bb0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 69 6e 70   copy of the inp
27bc0 75 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  ut string..**.**
27bd0 20 5e 49 66 20 70 7a 54 61 69 6c 20 69 73 20 6e   ^If pzTail is n
27be0 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 2a 70 7a  ot NULL then *pz
27bf0 54 61 69 6c 20 69 73 20 6d 61 64 65 20 74 6f 20  Tail is made to 
27c00 70 6f 69 6e 74 20 74 6f 20 74 68 65 20 66 69 72  point to the fir
27c10 73 74 20 62 79 74 65 0a 2a 2a 20 70 61 73 74 20  st byte.** past 
27c20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 66  the end of the f
27c30 69 72 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65  irst SQL stateme
27c40 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65  nt in zSql.  The
27c50 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79  se routines only
27c60 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 68 65 20  .** compile the 
27c70 66 69 72 73 74 20 73 74 61 74 65 6d 65 6e 74 20  first statement 
27c80 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54  in zSql, so *pzT
27c90 61 69 6c 20 69 73 20 6c 65 66 74 20 70 6f 69 6e  ail is left poin
27ca0 74 69 6e 67 20 74 6f 0a 2a 2a 20 77 68 61 74 20  ting to.** what 
27cb0 72 65 6d 61 69 6e 73 20 75 6e 63 6f 6d 70 69 6c  remains uncompil
27cc0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70 53 74  ed..**.** ^*ppSt
27cd0 6d 74 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74  mt is left point
27ce0 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65  ing to a compile
27cf0 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
27d00 65 6d 65 6e 74 5d 20 74 68 61 74 20 63 61 6e 20  ement] that can 
27d10 62 65 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 75  be.** executed u
27d20 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74  sing [sqlite3_st
27d30 65 70 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 72  ep()].  ^If ther
27d40 65 20 69 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a  e is an error, *
27d50 70 70 53 74 6d 74 20 69 73 20 73 65 74 0a 2a 2a  ppStmt is set.**
27d60 20 74 6f 20 4e 55 4c 4c 2e 20 20 5e 49 66 20 74   to NULL.  ^If t
27d70 68 65 20 69 6e 70 75 74 20 74 65 78 74 20 63 6f  he input text co
27d80 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20 28 69  ntains no SQL (i
27d90 66 20 74 68 65 20 69 6e 70 75 74 20 69 73 20 61  f the input is a
27da0 6e 20 65 6d 70 74 79 0a 2a 2a 20 73 74 72 69 6e  n empty.** strin
27db0 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20  g or a comment) 
27dc0 74 68 65 6e 20 2a 70 70 53 74 6d 74 20 69 73 20  then *ppStmt is 
27dd0 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20  set to NULL..** 
27de0 54 68 65 20 63 61 6c 6c 69 6e 67 20 70 72 6f 63  The calling proc
27df0 65 64 75 72 65 20 69 73 20 72 65 73 70 6f 6e 73  edure is respons
27e00 69 62 6c 65 20 66 6f 72 20 64 65 6c 65 74 69 6e  ible for deletin
27e10 67 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 0a 2a  g the compiled.*
27e20 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  * SQL statement 
27e30 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66  using [sqlite3_f
27e40 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66 74 65 72  inalize()] after
27e50 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65 64   it has finished
27e60 20 77 69 74 68 20 69 74 2e 0a 2a 2a 20 70 70 53   with it..** ppS
27e70 74 6d 74 20 6d 61 79 20 6e 6f 74 20 62 65 20 4e  tmt may not be N
27e80 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73  ULL..**.** ^On s
27e90 75 63 63 65 73 73 2c 20 74 68 65 20 73 71 6c 69  uccess, the sqli
27ea0 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 66 61  te3_prepare() fa
27eb0 6d 69 6c 79 20 6f 66 20 72 6f 75 74 69 6e 65 73  mily of routines
27ec0 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
27ed0 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68 65 72 77 69 73  OK];.** otherwis
27ee0 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65  e an [error code
27ef0 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  ] is returned..*
27f00 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
27f10 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 61 6e  _prepare_v2() an
27f20 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  d sqlite3_prepar
27f30 65 31 36 5f 76 32 28 29 20 69 6e 74 65 72 66 61  e16_v2() interfa
27f40 63 65 73 20 61 72 65 0a 2a 2a 20 72 65 63 6f 6d  ces are.** recom
27f50 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e  mended for all n
27f60 65 77 20 70 72 6f 67 72 61 6d 73 2e 20 54 68 65  ew programs. The
27f70 20 74 77 6f 20 6f 6c 64 65 72 20 69 6e 74 65 72   two older inter
27f80 66 61 63 65 73 20 61 72 65 20 72 65 74 61 69 6e  faces are retain
27f90 65 64 0a 2a 2a 20 66 6f 72 20 62 61 63 6b 77 61  ed.** for backwa
27fa0 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
27fb0 79 2c 20 62 75 74 20 74 68 65 69 72 20 75 73 65  y, but their use
27fc0 20 69 73 20 64 69 73 63 6f 75 72 61 67 65 64 2e   is discouraged.
27fd0 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 22 76 32 22  .** ^In the "v2"
27fe0 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65   interfaces, the
27ff0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
28000 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73 20 72  ent.** that is r
28010 65 74 75 72 6e 65 64 20 28 74 68 65 20 5b 73 71  eturned (the [sq
28020 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65  lite3_stmt] obje
28030 63 74 29 20 63 6f 6e 74 61 69 6e 73 20 61 20 63  ct) contains a c
28040 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 72  opy of the.** or
28050 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e  iginal SQL text.
28060 20 54 68 69 73 20 63 61 75 73 65 73 20 74 68 65   This causes the
28070 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
28080 5d 20 69 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a  ] interface to.*
28090 2a 20 62 65 68 61 76 65 20 64 69 66 66 65 72 65  * behave differe
280a0 6e 74 6c 79 20 69 6e 20 74 68 72 65 65 20 77 61  ntly in three wa
280b0 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a  ys:.**.** <ol>.*
280c0 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68  * <li>.** ^If th
280d0 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d  e database schem
280e0 61 20 63 68 61 6e 67 65 73 2c 20 69 6e 73 74 65  a changes, inste
280f0 61 64 20 6f 66 20 72 65 74 75 72 6e 69 6e 67 20  ad of returning 
28100 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20  [SQLITE_SCHEMA] 
28110 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20  as it.** always 
28120 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c  used to do, [sql
28130 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c  ite3_step()] wil
28140 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  l automatically 
28150 72 65 63 6f 6d 70 69 6c 65 20 74 68 65 20 53 51  recompile the SQ
28160 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61  L.** statement a
28170 6e 64 20 74 72 79 20 74 6f 20 72 75 6e 20 69 74  nd try to run it
28180 20 61 67 61 69 6e 2e 20 41 73 20 6d 61 6e 79 20   again. As many 
28190 61 73 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 53  as [SQLITE_MAX_S
281a0 43 48 45 4d 41 5f 52 45 54 52 59 5d 0a 2a 2a 20  CHEMA_RETRY].** 
281b0 72 65 74 72 69 65 73 20 77 69 6c 6c 20 6f 63 63  retries will occ
281c0 75 72 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65  ur before sqlite
281d0 33 5f 73 74 65 70 28 29 20 67 69 76 65 73 20 75  3_step() gives u
281e0 70 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 6e  p and returns an
281f0 20 65 72 72 6f 72 2e 0a 2a 2a 20 3c 2f 6c 69 3e   error..** </li>
28200 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e  .**.** <li>.** ^
28210 57 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63  When an error oc
28220 63 75 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f 73  curs, [sqlite3_s
28230 74 65 70 28 29 5d 20 77 69 6c 6c 20 72 65 74 75  tep()] will retu
28240 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 65  rn one of the de
28250 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f 72  tailed.** [error
28260 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74 65   codes] or [exte
28270 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 73  nded error codes
28280 5d 2e 20 20 5e 54 68 65 20 6c 65 67 61 63 79 20  ].  ^The legacy 
28290 62 65 68 61 76 69 6f 72 20 77 61 73 20 74 68 61  behavior was tha
282a0 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74  t.** [sqlite3_st
282b0 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79  ep()] would only
282c0 20 72 65 74 75 72 6e 20 61 20 67 65 6e 65 72 69   return a generi
282d0 63 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  c [SQLITE_ERROR]
282e0 20 72 65 73 75 6c 74 20 63 6f 64 65 0a 2a 2a 20   result code.** 
282f0 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 74  and the applicat
28300 69 6f 6e 20 77 6f 75 6c 64 20 68 61 76 65 20 74  ion would have t
28310 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64 20  o make a second 
28320 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
28330 5f 72 65 73 65 74 28 29 5d 0a 2a 2a 20 69 6e 20  _reset()].** in 
28340 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 74 68  order to find th
28350 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 63 61 75  e underlying cau
28360 73 65 20 6f 66 20 74 68 65 20 70 72 6f 62 6c 65  se of the proble
28370 6d 2e 20 57 69 74 68 20 74 68 65 20 22 76 32 22  m. With the "v2"
28380 20 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e 74 65   prepare.** inte
28390 72 66 61 63 65 73 2c 20 74 68 65 20 75 6e 64 65  rfaces, the unde
283a0 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20 66 6f  rlying reason fo
283b0 72 20 74 68 65 20 65 72 72 6f 72 20 69 73 20 72  r the error is r
283c0 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74  eturned immediat
283d0 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a  ely..** </li>.**
283e0 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20  .** <li>.** ^If 
283f0 74 68 65 20 73 70 65 63 69 66 69 63 20 76 61 6c  the specific val
28400 75 65 20 62 6f 75 6e 64 20 74 6f 20 5b 70 61 72  ue bound to [par
28410 61 6d 65 74 65 72 20 7c 20 68 6f 73 74 20 70 61  ameter | host pa
28420 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20  rameter] in the 
28430 0a 2a 2a 20 57 48 45 52 45 20 63 6c 61 75 73 65  .** WHERE clause
28440 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65   might influence
28450 20 74 68 65 20 63 68 6f 69 63 65 20 6f 66 20 71   the choice of q
28460 75 65 72 79 20 70 6c 61 6e 20 66 6f 72 20 61 20  uery plan for a 
28470 73 74 61 74 65 6d 65 6e 74 2c 0a 2a 2a 20 74 68  statement,.** th
28480 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  en the statement
28490 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74   will be automat
284a0 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65  ically recompile
284b0 64 2c 20 61 73 20 69 66 20 74 68 65 72 65 20 68  d, as if there h
284c0 61 64 20 62 65 65 6e 20 0a 2a 2a 20 61 20 73 63  ad been .** a sc
284d0 68 65 6d 61 20 63 68 61 6e 67 65 2c 20 6f 6e 20  hema change, on 
284e0 74 68 65 20 66 69 72 73 74 20 20 5b 73 71 6c 69  the first  [sqli
284f0 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c  te3_step()] call
28500 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 20 63   following any c
28510 68 61 6e 67 65 0a 2a 2a 20 74 6f 20 74 68 65 20  hange.** to the 
28520 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65  [sqlite3_bind_te
28530 78 74 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f  xt | bindings] o
28540 66 20 74 68 61 74 20 5b 70 61 72 61 6d 65 74 65  f that [paramete
28550 72 5d 2e 20 0a 2a 2a 20 5e 54 68 65 20 73 70 65  r]. .** ^The spe
28560 63 69 66 69 63 20 76 61 6c 75 65 20 6f 66 20 57  cific value of W
28570 48 45 52 45 2d 63 6c 61 75 73 65 20 5b 70 61 72  HERE-clause [par
28580 61 6d 65 74 65 72 5d 20 6d 69 67 68 74 20 69 6e  ameter] might in
28590 66 6c 75 65 6e 63 65 20 74 68 65 20 0a 2a 2a 20  fluence the .** 
285a0 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20  choice of query 
285b0 70 6c 61 6e 20 69 66 20 74 68 65 20 70 61 72 61  plan if the para
285c0 6d 65 74 65 72 20 69 73 20 74 68 65 20 6c 65 66  meter is the lef
285d0 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20 61  t-hand side of a
285e0 20 5b 4c 49 4b 45 5d 0a 2a 2a 20 6f 72 20 5b 47   [LIKE].** or [G
285f0 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 20 6f 72  LOB] operator or
28600 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   if the paramete
28610 72 20 69 73 20 63 6f 6d 70 61 72 65 64 20 74 6f  r is compared to
28620 20 61 6e 20 69 6e 64 65 78 65 64 20 63 6f 6c 75   an indexed colu
28630 6d 6e 0a 2a 2a 20 61 6e 64 20 74 68 65 20 5b 53  mn.** and the [S
28640 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 54 41  QLITE_ENABLE_STA
28650 54 33 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  T3] compile-time
28660 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c   option is enabl
28670 65 64 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20  ed..** </li>.** 
28680 3c 2f 6f 6c 3e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  </ol>.*/.SQLITE_
28690 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
286a0 70 72 65 70 61 72 65 28 0a 20 20 73 71 6c 69 74  prepare(.  sqlit
286b0 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
286c0 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68     /* Database h
286d0 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
286e0 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20   char *zSql,    
286f0 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d     /* SQL statem
28700 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64  ent, UTF-8 encod
28710 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74  ed */.  int nByt
28720 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  e,              
28730 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  /* Maximum lengt
28740 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74  h of zSql in byt
28750 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  es. */.  sqlite3
28760 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20  _stmt **ppStmt, 
28770 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65   /* OUT: Stateme
28780 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  nt handle */.  c
28790 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61  onst char **pzTa
287a0 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50  il     /* OUT: P
287b0 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64  ointer to unused
287c0 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c   portion of zSql
287d0 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50   */.);.SQLITE_AP
287e0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72  I int sqlite3_pr
287f0 65 70 61 72 65 5f 76 32 28 0a 20 20 73 71 6c 69  epare_v2(.  sqli
28800 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
28810 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
28820 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
28830 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20  t char *zSql,   
28840 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65      /* SQL state
28850 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f  ment, UTF-8 enco
28860 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79  ded */.  int nBy
28870 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  te,             
28880 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67   /* Maximum leng
28890 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79  th of zSql in by
288a0 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65  tes. */.  sqlite
288b0 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c  3_stmt **ppStmt,
288c0 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d    /* OUT: Statem
288d0 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ent handle */.  
288e0 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54  const char **pzT
288f0 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20  ail     /* OUT: 
28900 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65  Pointer to unuse
28910 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71  d portion of zSq
28920 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41  l */.);.SQLITE_A
28930 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 70  PI int sqlite3_p
28940 72 65 70 61 72 65 31 36 28 0a 20 20 73 71 6c 69  repare16(.  sqli
28950 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
28960 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
28970 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
28980 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20  t void *zSql,   
28990 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65      /* SQL state
289a0 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63  ment, UTF-16 enc
289b0 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42  oded */.  int nB
289c0 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20  yte,            
289d0 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e    /* Maximum len
289e0 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62  gth of zSql in b
289f0 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74  ytes. */.  sqlit
28a00 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74  e3_stmt **ppStmt
28a10 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65  ,  /* OUT: State
28a20 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  ment handle */. 
28a30 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a   const void **pz
28a40 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a  Tail     /* OUT:
28a50 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73   Pointer to unus
28a60 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53  ed portion of zS
28a70 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f  ql */.);.SQLITE_
28a80 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
28a90 70 72 65 70 61 72 65 31 36 5f 76 32 28 0a 20 20  prepare16_v2(.  
28aa0 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
28ab0 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
28ac0 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ase handle */.  
28ad0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c  const void *zSql
28ae0 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73  ,       /* SQL s
28af0 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36  tatement, UTF-16
28b00 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e   encoded */.  in
28b10 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20  t nByte,        
28b20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
28b30 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20   length of zSql 
28b40 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73  in bytes. */.  s
28b50 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70  qlite3_stmt **pp
28b60 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53  Stmt,  /* OUT: S
28b70 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
28b80 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
28b90 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20  **pzTail     /* 
28ba0 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20  OUT: Pointer to 
28bb0 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f  unused portion o
28bc0 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a  f zSql */.);../*
28bd0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
28be0 74 72 69 65 76 69 6e 67 20 53 74 61 74 65 6d 65  trieving Stateme
28bf0 6e 74 20 53 51 4c 0a 2a 2a 0a 2a 2a 20 5e 54 68  nt SQL.**.** ^Th
28c00 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e  is interface can
28c10 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 74 72   be used to retr
28c20 69 65 76 65 20 61 20 73 61 76 65 64 20 63 6f 70  ieve a saved cop
28c30 79 20 6f 66 20 74 68 65 20 6f 72 69 67 69 6e 61  y of the origina
28c40 6c 0a 2a 2a 20 53 51 4c 20 74 65 78 74 20 75 73  l.** SQL text us
28c50 65 64 20 74 6f 20 63 72 65 61 74 65 20 61 20 5b  ed to create a [
28c60 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
28c70 6e 74 5d 20 69 66 20 74 68 61 74 20 73 74 61 74  nt] if that stat
28c80 65 6d 65 6e 74 20 77 61 73 0a 2a 2a 20 63 6f 6d  ement was.** com
28c90 70 69 6c 65 64 20 75 73 69 6e 67 20 65 69 74 68  piled using eith
28ca0 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  er [sqlite3_prep
28cb0 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71  are_v2()] or [sq
28cc0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
28cd0 76 32 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45  v2()]..*/.SQLITE
28ce0 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20  _API const char 
28cf0 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c  *sqlite3_sql(sql
28d00 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
28d10 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
28d20 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66  EF: Determine If
28d30 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e   An SQL Statemen
28d40 74 20 57 72 69 74 65 73 20 54 68 65 20 44 61 74  t Writes The Dat
28d50 61 62 61 73 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  abase.**.** ^The
28d60 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65   sqlite3_stmt_re
28d70 61 64 6f 6e 6c 79 28 58 29 20 69 6e 74 65 72 66  adonly(X) interf
28d80 61 63 65 20 72 65 74 75 72 6e 73 20 74 72 75 65  ace returns true
28d90 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 0a 2a   (non-zero) if.*
28da0 2a 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68  * and only if th
28db0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
28dc0 65 6d 65 6e 74 5d 20 58 20 6d 61 6b 65 73 20 6e  ement] X makes n
28dd0 6f 20 64 69 72 65 63 74 20 63 68 61 6e 67 65 73  o direct changes
28de0 20 74 6f 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65   to.** the conte
28df0 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  nt of the databa
28e00 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e  se file..**.** N
28e10 6f 74 65 20 74 68 61 74 20 5b 61 70 70 6c 69 63  ote that [applic
28e20 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
28e30 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 6f 72 0a  L functions] or.
28e40 2a 2a 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c  ** [virtual tabl
28e50 65 73 5d 20 6d 69 67 68 74 20 63 68 61 6e 67 65  es] might change
28e60 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 6e   the database in
28e70 64 69 72 65 63 74 6c 79 20 61 73 20 61 20 73 69  directly as a si
28e80 64 65 20 65 66 66 65 63 74 2e 20 20 0a 2a 2a 20  de effect.  .** 
28e90 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69  ^(For example, i
28ea0 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  f an application
28eb0 20 64 65 66 69 6e 65 73 20 61 20 66 75 6e 63 74   defines a funct
28ec0 69 6f 6e 20 22 65 76 61 6c 28 29 22 20 74 68 61  ion "eval()" tha
28ed0 74 20 0a 2a 2a 20 63 61 6c 6c 73 20 5b 73 71 6c  t .** calls [sql
28ee0 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 74 68  ite3_exec()], th
28ef0 65 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  en the following
28f00 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77   SQL statement w
28f10 6f 75 6c 64 0a 2a 2a 20 63 68 61 6e 67 65 20 74  ould.** change t
28f20 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
28f30 20 74 68 72 6f 75 67 68 20 73 69 64 65 2d 65 66   through side-ef
28f40 66 65 63 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  fects:.**.** <bl
28f50 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
28f60 2a 20 20 20 20 53 45 4c 45 43 54 20 65 76 61 6c  *    SELECT eval
28f70 28 27 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 31  ('DELETE FROM t1
28f80 27 29 20 46 52 4f 4d 20 74 32 3b 0a 2a 2a 20 3c  ') FROM t2;.** <
28f90 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
28fa0 65 3e 0a 2a 2a 0a 2a 2a 20 42 75 74 20 62 65 63  e>.**.** But bec
28fb0 61 75 73 65 20 74 68 65 20 5b 53 45 4c 45 43 54  ause the [SELECT
28fc0 5d 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73  ] statement does
28fd0 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20   not change the 
28fe0 64 61 74 61 62 61 73 65 20 66 69 6c 65 0a 2a 2a  database file.**
28ff0 20 64 69 72 65 63 74 6c 79 2c 20 73 71 6c 69 74   directly, sqlit
29000 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79  e3_stmt_readonly
29010 28 29 20 77 6f 75 6c 64 20 73 74 69 6c 6c 20 72  () would still r
29020 65 74 75 72 6e 20 74 72 75 65 2e 29 5e 0a 2a 2a  eturn true.)^.**
29030 0a 2a 2a 20 5e 54 72 61 6e 73 61 63 74 69 6f 6e  .** ^Transaction
29040 20 63 6f 6e 74 72 6f 6c 20 73 74 61 74 65 6d 65   control stateme
29050 6e 74 73 20 73 75 63 68 20 61 73 20 5b 42 45 47  nts such as [BEG
29060 49 4e 5d 2c 20 5b 43 4f 4d 4d 49 54 5d 2c 20 5b  IN], [COMMIT], [
29070 52 4f 4c 4c 42 41 43 4b 5d 2c 0a 2a 2a 20 5b 53  ROLLBACK],.** [S
29080 41 56 45 50 4f 49 4e 54 5d 2c 20 61 6e 64 20 5b  AVEPOINT], and [
29090 52 45 4c 45 41 53 45 5d 20 63 61 75 73 65 20 73  RELEASE] cause s
290a0 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64  qlite3_stmt_read
290b0 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e  only() to return
290c0 20 74 72 75 65 2c 0a 2a 2a 20 73 69 6e 63 65 20   true,.** since 
290d0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 73 20 74  the statements t
290e0 68 65 6d 73 65 6c 76 65 73 20 64 6f 20 6e 6f 74  hemselves do not
290f0 20 61 63 74 75 61 6c 6c 79 20 6d 6f 64 69 66 79   actually modify
29100 20 74 68 65 20 64 61 74 61 62 61 73 65 20 62 75   the database bu
29110 74 0a 2a 2a 20 72 61 74 68 65 72 20 74 68 65 79  t.** rather they
29120 20 63 6f 6e 74 72 6f 6c 20 74 68 65 20 74 69 6d   control the tim
29130 69 6e 67 20 6f 66 20 77 68 65 6e 20 6f 74 68 65  ing of when othe
29140 72 20 73 74 61 74 65 6d 65 6e 74 73 20 6d 6f 64  r statements mod
29150 69 66 79 20 74 68 65 20 0a 2a 2a 20 64 61 74 61  ify the .** data
29160 62 61 73 65 2e 20 20 5e 54 68 65 20 5b 41 54 54  base.  ^The [ATT
29170 41 43 48 5d 20 61 6e 64 20 5b 44 45 54 41 43 48  ACH] and [DETACH
29180 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 61 6c 73  ] statements als
29190 6f 20 63 61 75 73 65 0a 2a 2a 20 73 71 6c 69 74  o cause.** sqlit
291a0 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79  e3_stmt_readonly
291b0 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75  () to return tru
291c0 65 20 73 69 6e 63 65 2c 20 77 68 69 6c 65 20 74  e since, while t
291d0 68 6f 73 65 20 73 74 61 74 65 6d 65 6e 74 73 0a  hose statements.
291e0 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 63 6f  ** change the co
291f0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 66 20 61  nfiguration of a
29200 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
29210 74 69 6f 6e 2c 20 74 68 65 79 20 64 6f 20 6e 6f  tion, they do no
29220 74 20 6d 61 6b 65 20 0a 2a 2a 20 63 68 61 6e 67  t make .** chang
29230 65 73 20 74 6f 20 74 68 65 20 63 6f 6e 74 65 6e  es to the conten
29240 74 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  t of the databas
29250 65 20 66 69 6c 65 73 20 6f 6e 20 64 69 73 6b 2e  e files on disk.
29260 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
29270 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  nt sqlite3_stmt_
29280 72 65 61 64 6f 6e 6c 79 28 73 71 6c 69 74 65 33  readonly(sqlite3
29290 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
292a0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
292b0 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 20 50  Determine If A P
292c0 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
292d0 74 20 48 61 73 20 42 65 65 6e 20 52 65 73 65 74  t Has Been Reset
292e0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
292f0 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29  te3_stmt_busy(S)
29300 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
29310 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72  ns true (non-zer
29320 6f 29 20 69 66 20 74 68 65 0a 2a 2a 20 5b 70 72  o) if the.** [pr
29330 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
29340 5d 20 53 20 68 61 73 20 62 65 65 6e 20 73 74 65  ] S has been ste
29350 70 70 65 64 20 61 74 20 6c 65 61 73 74 20 6f 6e  pped at least on
29360 63 65 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71  ce using .** [sq
29370 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 62  lite3_step(S)] b
29380 75 74 20 68 61 73 20 6e 6f 74 20 72 75 6e 20 74  ut has not run t
29390 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 6e 64  o completion and
293a0 2f 6f 72 20 68 61 73 20 6e 6f 74 20 0a 2a 2a 20  /or has not .** 
293b0 62 65 65 6e 20 72 65 73 65 74 20 75 73 69 6e 67  been reset using
293c0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
293d0 53 29 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  S)].  ^The sqlit
293e0 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 0a  e3_stmt_busy(S).
293f0 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  ** interface ret
29400 75 72 6e 73 20 66 61 6c 73 65 20 69 66 20 53 20  urns false if S 
29410 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
29420 72 2e 20 20 49 66 20 53 20 69 73 20 6e 6f 74 20  r.  If S is not 
29430 61 20 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74  a .** NULL point
29440 65 72 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20  er and is not a 
29450 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 76 61 6c  pointer to a val
29460 69 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  id [prepared sta
29470 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63  tement].** objec
29480 74 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  t, then the beha
29490 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65  vior is undefine
294a0 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 75  d and probably u
294b0 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2a 0a 2a  ndesirable..**.*
294c0 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65  * This interface
294d0 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e 20   can be used in 
294e0 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 5b 73 71 6c  combination [sql
294f0 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 29  ite3_next_stmt()
29500 5d 0a 2a 2a 20 74 6f 20 6c 6f 63 61 74 65 20 61  ].** to locate a
29510 6c 6c 20 70 72 65 70 61 72 65 64 20 73 74 61 74  ll prepared stat
29520 65 6d 65 6e 74 73 20 61 73 73 6f 63 69 61 74 65  ements associate
29530 64 20 77 69 74 68 20 61 20 64 61 74 61 62 61 73  d with a databas
29540 65 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  e .** connection
29550 20 74 68 61 74 20 61 72 65 20 69 6e 20 6e 65 65   that are in nee
29560 64 20 6f 66 20 62 65 69 6e 67 20 72 65 73 65 74  d of being reset
29570 2e 20 20 54 68 69 73 20 63 61 6e 20 62 65 20 75  .  This can be u
29580 73 65 64 2c 0a 2a 2a 20 66 6f 72 20 65 78 61 6d  sed,.** for exam
29590 70 6c 65 2c 20 69 6e 20 64 69 61 67 6e 6f 73 74  ple, in diagnost
295a0 69 63 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 73  ic routines to s
295b0 65 61 72 63 68 20 66 6f 72 20 70 72 65 70 61 72  earch for prepar
295c0 65 64 20 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  ed .** statement
295d0 73 20 74 68 61 74 20 61 72 65 20 68 6f 6c 64 69  s that are holdi
295e0 6e 67 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e  ng a transaction
295f0 20 6f 70 65 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45   open..*/.SQLITE
29600 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
29610 5f 73 74 6d 74 5f 62 75 73 79 28 73 71 6c 69 74  _stmt_busy(sqlit
29620 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a  e3_stmt*);../*.*
29630 2a 20 43 41 50 49 33 52 45 46 3a 20 44 79 6e 61  * CAPI3REF: Dyna
29640 6d 69 63 61 6c 6c 79 20 54 79 70 65 64 20 56 61  mically Typed Va
29650 6c 75 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45  lue Object.** KE
29660 59 57 4f 52 44 53 3a 20 7b 70 72 6f 74 65 63 74  YWORDS: {protect
29670 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
29680 7d 20 7b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  } {unprotected s
29690 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a  qlite3_value}.**
296a0 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20  .** SQLite uses 
296b0 74 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  the sqlite3_valu
296c0 65 20 6f 62 6a 65 63 74 20 74 6f 20 72 65 70 72  e object to repr
296d0 65 73 65 6e 74 20 61 6c 6c 20 76 61 6c 75 65 73  esent all values
296e0 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20  .** that can be 
296f0 73 74 6f 72 65 64 20 69 6e 20 61 20 64 61 74 61  stored in a data
29700 62 61 73 65 20 74 61 62 6c 65 2e 20 53 51 4c 69  base table. SQLi
29710 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20  te uses dynamic 
29720 74 79 70 69 6e 67 0a 2a 2a 20 66 6f 72 20 74 68  typing.** for th
29730 65 20 76 61 6c 75 65 73 20 69 74 20 73 74 6f 72  e values it stor
29740 65 73 2e 20 20 5e 56 61 6c 75 65 73 20 73 74 6f  es.  ^Values sto
29750 72 65 64 20 69 6e 20 73 71 6c 69 74 65 33 5f 76  red in sqlite3_v
29760 61 6c 75 65 20 6f 62 6a 65 63 74 73 0a 2a 2a 20  alue objects.** 
29770 63 61 6e 20 62 65 20 69 6e 74 65 67 65 72 73 2c  can be integers,
29780 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
29790 76 61 6c 75 65 73 2c 20 73 74 72 69 6e 67 73 2c  values, strings,
297a0 20 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e   BLOBs, or NULL.
297b0 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 74 65  .**.** An sqlite
297c0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d  3_value object m
297d0 61 79 20 62 65 20 65 69 74 68 65 72 20 22 70 72  ay be either "pr
297e0 6f 74 65 63 74 65 64 22 20 6f 72 20 22 75 6e 70  otected" or "unp
297f0 72 6f 74 65 63 74 65 64 22 2e 0a 2a 2a 20 53 6f  rotected"..** So
29800 6d 65 20 69 6e 74 65 72 66 61 63 65 73 20 72 65  me interfaces re
29810 71 75 69 72 65 20 61 20 70 72 6f 74 65 63 74 65  quire a protecte
29820 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e  d sqlite3_value.
29830 20 20 4f 74 68 65 72 20 69 6e 74 65 72 66 61 63    Other interfac
29840 65 73 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 65 70  es.** will accep
29850 74 20 65 69 74 68 65 72 20 61 20 70 72 6f 74 65  t either a prote
29860 63 74 65 64 20 6f 72 20 61 6e 20 75 6e 70 72 6f  cted or an unpro
29870 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
29880 61 6c 75 65 2e 0a 2a 2a 20 45 76 65 72 79 20 69  alue..** Every i
29890 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 61 63  nterface that ac
298a0 63 65 70 74 73 20 73 71 6c 69 74 65 33 5f 76 61  cepts sqlite3_va
298b0 6c 75 65 20 61 72 67 75 6d 65 6e 74 73 20 73 70  lue arguments sp
298c0 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 65 74 68  ecifies.** wheth
298d0 65 72 20 6f 72 20 6e 6f 74 20 69 74 20 72 65 71  er or not it req
298e0 75 69 72 65 73 20 61 20 70 72 6f 74 65 63 74 65  uires a protecte
298f0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e  d sqlite3_value.
29900 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73  .**.** The terms
29910 20 22 70 72 6f 74 65 63 74 65 64 22 20 61 6e 64   "protected" and
29920 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 20 72   "unprotected" r
29930 65 66 65 72 20 74 6f 20 77 68 65 74 68 65 72 20  efer to whether 
29940 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65  or not.** a mute
29950 78 20 69 73 20 68 65 6c 64 2e 20 20 41 6e 20 69  x is held.  An i
29960 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78 20 69 73  nternal mutex is
29970 20 68 65 6c 64 20 66 6f 72 20 61 20 70 72 6f 74   held for a prot
29980 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ected.** sqlite3
29990 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 62 75  _value object bu
299a0 74 20 6e 6f 20 6d 75 74 65 78 20 69 73 20 68 65  t no mutex is he
299b0 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74  ld for an unprot
299c0 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ected.** sqlite3
299d0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20  _value object.  
299e0 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
299f0 70 69 6c 65 64 20 74 6f 20 62 65 20 73 69 6e 67  piled to be sing
29a00 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 28  le-threaded.** (
29a10 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 54 48 52  with [SQLITE_THR
29a20 45 41 44 53 41 46 45 3d 30 5d 20 61 6e 64 20 77  EADSAFE=0] and w
29a30 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 74 68 72  ith [sqlite3_thr
29a40 65 61 64 73 61 66 65 28 29 5d 20 72 65 74 75 72  eadsafe()] retur
29a50 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69 66  ning 0).** or if
29a60 20 53 51 4c 69 74 65 20 69 73 20 72 75 6e 20 69   SQLite is run i
29a70 6e 20 6f 6e 65 20 6f 66 20 72 65 64 75 63 65 64  n one of reduced
29a80 20 6d 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a 2a   mutex modes .**
29a90 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
29aa0 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f 72  SINGLETHREAD] or
29ab0 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
29ac0 4d 55 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a 20  MULTITHREAD].** 
29ad0 74 68 65 6e 20 74 68 65 72 65 20 69 73 20 6e 6f  then there is no
29ae0 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74   distinction bet
29af0 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61  ween protected a
29b00 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a  nd unprotected.*
29b10 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  * sqlite3_value 
29b20 6f 62 6a 65 63 74 73 20 61 6e 64 20 74 68 65 79  objects and they
29b30 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e 74   can be used int
29b40 65 72 63 68 61 6e 67 65 61 62 6c 79 2e 20 20 48  erchangeably.  H
29b50 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d  owever,.** for m
29b60 61 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74  aximum code port
29b70 61 62 69 6c 69 74 79 20 69 74 20 69 73 20 72 65  ability it is re
29b80 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61  commended that a
29b90 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73  pplications.** s
29ba0 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64 69  till make the di
29bb0 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65  stinction betwee
29bc0 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20  n protected and 
29bd0 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  unprotected.** s
29be0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
29bf0 65 63 74 73 20 65 76 65 6e 20 77 68 65 6e 20 6e  ects even when n
29c00 6f 74 20 73 74 72 69 63 74 6c 79 20 72 65 71 75  ot strictly requ
29c10 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ired..**.** ^The
29c20 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
29c30 62 6a 65 63 74 73 20 74 68 61 74 20 61 72 65 20  bjects that are 
29c40 70 61 73 73 65 64 20 61 73 20 70 61 72 61 6d 65  passed as parame
29c50 74 65 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a  ters into the.**
29c60 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
29c70 6f 66 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  of [application-
29c80 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
29c90 74 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74 65  tions] are prote
29ca0 63 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  cted..** ^The sq
29cb0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
29cc0 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  ct returned by.*
29cd0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
29ce0 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 6e  n_value()] is un
29cf0 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e  protected..** Un
29d00 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
29d10 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20  3_value objects 
29d20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64  may only be used
29d30 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65   with.** [sqlite
29d40 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29  3_result_value()
29d50 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62  ] and [sqlite3_b
29d60 69 6e 64 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a  ind_value()]..**
29d70 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   The [sqlite3_va
29d80 6c 75 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74  lue_blob | sqlit
29d90 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 29 5d  e3_value_type()]
29da0 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e   family of.** in
29db0 74 65 72 66 61 63 65 73 20 72 65 71 75 69 72 65  terfaces require
29dc0 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74   protected sqlit
29dd0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
29de0 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
29df0 75 63 74 20 4d 65 6d 20 73 71 6c 69 74 65 33 5f  uct Mem sqlite3_
29e00 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  value;../*.** CA
29e10 50 49 33 52 45 46 3a 20 53 51 4c 20 46 75 6e 63  PI3REF: SQL Func
29e20 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a  tion Context Obj
29e30 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f  ect.**.** The co
29e40 6e 74 65 78 74 20 69 6e 20 77 68 69 63 68 20 61  ntext in which a
29e50 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65  n SQL function e
29e60 78 65 63 75 74 65 73 20 69 73 20 73 74 6f 72 65  xecutes is store
29e70 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74  d in an.** sqlit
29e80 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63  e3_context objec
29e90 74 2e 20 20 5e 41 20 70 6f 69 6e 74 65 72 20 74  t.  ^A pointer t
29ea0 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e  o an sqlite3_con
29eb0 74 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69  text object.** i
29ec0 73 20 61 6c 77 61 79 73 20 66 69 72 73 74 20 70  s always first p
29ed0 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 61 70 70  arameter to [app
29ee0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
29ef0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e   SQL functions].
29f00 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
29f10 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
29f20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65  function impleme
29f30 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73  ntation will pas
29f40 73 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65  s this.** pointe
29f50 72 20 74 68 72 6f 75 67 68 20 69 6e 74 6f 20 63  r through into c
29f60 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
29f70 5f 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71  _result_int | sq
29f80 6c 69 74 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c  lite3_result()],
29f90 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67 67  .** [sqlite3_agg
29fa0 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29  regate_context()
29fb0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72  ], [sqlite3_user
29fc0 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71  _data()],.** [sq
29fd0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62  lite3_context_db
29fe0 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c  _handle()], [sql
29ff0 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
2a000 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b  ()],.** and/or [
2a010 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
2a020 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64  ata()]..*/.typed
2a030 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
2a040 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69 74 65  3_context sqlite
2a050 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a  3_context;../*.*
2a060 2a 20 43 41 50 49 33 52 45 46 3a 20 42 69 6e 64  * CAPI3REF: Bind
2a070 69 6e 67 20 56 61 6c 75 65 73 20 54 6f 20 50 72  ing Values To Pr
2a080 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
2a090 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  s.** KEYWORDS: {
2a0a0 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 7d 20  host parameter} 
2a0b0 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73  {host parameters
2a0c0 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65  } {host paramete
2a0d0 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f  r name}.** KEYWO
2a0e0 52 44 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65  RDS: {SQL parame
2a0f0 74 65 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65  ter} {SQL parame
2a100 74 65 72 73 7d 20 7b 70 61 72 61 6d 65 74 65 72  ters} {parameter
2a110 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a 20   binding}.**.** 
2a120 5e 28 49 6e 20 74 68 65 20 53 51 4c 20 73 74 61  ^(In the SQL sta
2a130 74 65 6d 65 6e 74 20 74 65 78 74 20 69 6e 70 75  tement text inpu
2a140 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72  t to [sqlite3_pr
2a150 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20  epare_v2()] and 
2a160 69 74 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a 2a  its variants,.**
2a170 20 6c 69 74 65 72 61 6c 73 20 6d 61 79 20 62 65   literals may be
2a180 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 5b   replaced by a [
2a190 70 61 72 61 6d 65 74 65 72 5d 20 74 68 61 74 20  parameter] that 
2a1a0 6d 61 74 63 68 65 73 20 6f 6e 65 20 6f 66 20 66  matches one of f
2a1b0 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d 70  ollowing.** temp
2a1c0 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  lates:.**.** <ul
2a1d0 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20  >.** <li>  ?.** 
2a1e0 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c  <li>  ?NNN.** <l
2a1f0 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e  i>  :VVV.** <li>
2a200 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20    @VVV.** <li>  
2a210 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  $VVV.** </ul>.**
2a220 0a 2a 2a 20 49 6e 20 74 68 65 20 74 65 6d 70 6c  .** In the templ
2a230 61 74 65 73 20 61 62 6f 76 65 2c 20 4e 4e 4e 20  ates above, NNN 
2a240 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 69 6e  represents an in
2a250 74 65 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a  teger literal,.*
2a260 2a 20 61 6e 64 20 56 56 56 20 72 65 70 72 65 73  * and VVV repres
2a270 65 6e 74 73 20 61 6e 20 61 6c 70 68 61 6e 75 6d  ents an alphanum
2a280 65 72 69 63 20 69 64 65 6e 74 69 66 69 65 72 2e  eric identifier.
2a290 29 5e 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20  )^  ^The values 
2a2a0 6f 66 20 74 68 65 73 65 0a 2a 2a 20 70 61 72 61  of these.** para
2a2b0 6d 65 74 65 72 73 20 28 61 6c 73 6f 20 63 61 6c  meters (also cal
2a2c0 6c 65 64 20 22 68 6f 73 74 20 70 61 72 61 6d 65  led "host parame
2a2d0 74 65 72 20 6e 61 6d 65 73 22 20 6f 72 20 22 53  ter names" or "S
2a2e0 51 4c 20 70 61 72 61 6d 65 74 65 72 73 22 29 0a  QL parameters").
2a2f0 2a 2a 20 63 61 6e 20 62 65 20 73 65 74 20 75 73  ** can be set us
2a300 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ing the sqlite3_
2a310 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65  bind_*() routine
2a320 73 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 0a  s defined here..
2a330 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
2a340 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
2a350 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
2a360 29 20 72 6f 75 74 69 6e 65 73 20 69 73 20 61 6c  ) routines is al
2a370 77 61 79 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65  ways.** a pointe
2a380 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  r to the [sqlite
2a390 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72  3_stmt] object r
2a3a0 65 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20  eturned from.** 
2a3b0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2a3c0 5f 76 32 28 29 5d 20 6f 72 20 69 74 73 20 76 61  _v2()] or its va
2a3d0 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  riants..**.** ^T
2a3e0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
2a3f0 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20  nt is the index 
2a400 6f 66 20 74 68 65 20 53 51 4c 20 70 61 72 61 6d  of the SQL param
2a410 65 74 65 72 20 74 6f 20 62 65 20 73 65 74 2e 0a  eter to be set..
2a420 2a 2a 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74  ** ^The leftmost
2a430 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 68   SQL parameter h
2a440 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31  as an index of 1
2a450 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 73 61 6d  .  ^When the sam
2a460 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c 20 70  e named.** SQL p
2a470 61 72 61 6d 65 74 65 72 20 69 73 20 75 73 65 64  arameter is used
2a480 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c   more than once,
2a490 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73   second and subs
2a4a0 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72  equent.** occurr
2a4b0 65 6e 63 65 73 20 68 61 76 65 20 74 68 65 20 73  ences have the s
2a4c0 61 6d 65 20 69 6e 64 65 78 20 61 73 20 74 68 65  ame index as the
2a4d0 20 66 69 72 73 74 20 6f 63 63 75 72 72 65 6e 63   first occurrenc
2a4e0 65 2e 0a 2a 2a 20 5e 54 68 65 20 69 6e 64 65 78  e..** ^The index
2a4f0 20 66 6f 72 20 6e 61 6d 65 64 20 70 61 72 61 6d   for named param
2a500 65 74 65 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f  eters can be loo
2a510 6b 65 64 20 75 70 20 75 73 69 6e 67 20 74 68 65  ked up using the
2a520 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
2a530 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
2a540 78 28 29 5d 20 41 50 49 20 69 66 20 64 65 73 69  x()] API if desi
2a550 72 65 64 2e 20 20 5e 54 68 65 20 69 6e 64 65 78  red.  ^The index
2a560 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70  .** for "?NNN" p
2a570 61 72 61 6d 65 74 65 72 73 20 69 73 20 74 68 65  arameters is the
2a580 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a   value of NNN..*
2a590 2a 20 5e 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65  * ^The NNN value
2a5a0 20 6d 75 73 74 20 62 65 20 62 65 74 77 65 65 6e   must be between
2a5b0 20 31 20 61 6e 64 20 74 68 65 20 5b 73 71 6c 69   1 and the [sqli
2a5c0 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20  te3_limit()].** 
2a5d0 70 61 72 61 6d 65 74 65 72 20 5b 53 51 4c 49 54  parameter [SQLIT
2a5e0 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45  E_LIMIT_VARIABLE
2a5f0 5f 4e 55 4d 42 45 52 5d 20 28 64 65 66 61 75 6c  _NUMBER] (defaul
2a600 74 20 76 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a  t value: 999)..*
2a610 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20  *.** ^The third 
2a620 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
2a630 76 61 6c 75 65 20 74 6f 20 62 69 6e 64 20 74 6f  value to bind to
2a640 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a   the parameter..
2a650 2a 2a 20 5e 49 66 20 74 68 65 20 74 68 69 72 64  ** ^If the third
2a660 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
2a670 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
2a680 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e  ) or sqlite3_bin
2a690 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 6f 72  d_text16().** or
2a6a0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c   sqlite3_bind_bl
2a6b0 6f 62 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70  ob() is a NULL p
2a6c0 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68 65 20  ointer then the 
2a6d0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
2a6e0 0a 2a 2a 20 69 73 20 69 67 6e 6f 72 65 64 20 61  .** is ignored a
2a6f0 6e 64 20 74 68 65 20 65 6e 64 20 72 65 73 75 6c  nd the end resul
2a700 74 20 69 73 20 74 68 65 20 73 61 6d 65 20 61 73  t is the same as
2a710 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75   sqlite3_bind_nu
2a720 6c 6c 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e  ll()..**.** ^(In
2a730 20 74 68 6f 73 65 20 72 6f 75 74 69 6e 65 73 20   those routines 
2a740 74 68 61 74 20 68 61 76 65 20 61 20 66 6f 75 72  that have a four
2a750 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 69 74 73  th argument, its
2a760 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a   value is the.**
2a770 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
2a780 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65   in the paramete
2a790 72 2e 20 20 54 6f 20 62 65 20 63 6c 65 61 72 3a  r.  To be clear:
2a7a0 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 74 68   the value is th
2a7b0 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 3c  e.** number of <
2a7c0 75 3e 62 79 74 65 73 3c 2f 75 3e 20 69 6e 20 74  u>bytes</u> in t
2a7d0 68 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68  he value, not th
2a7e0 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72  e number of char
2a7f0 61 63 74 65 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66  acters.)^.** ^If
2a800 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
2a810 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
2a820 5f 62 69 6e 64 5f 74 65 78 74 28 29 20 6f 72 20  _bind_text() or 
2a830 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
2a840 74 31 36 28 29 0a 2a 2a 20 69 73 20 6e 65 67 61  t16().** is nega
2a850 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 20 6c  tive, then the l
2a860 65 6e 67 74 68 20 6f 66 20 74 68 65 20 73 74 72  ength of the str
2a870 69 6e 67 20 69 73 0a 2a 2a 20 74 68 65 20 6e 75  ing is.** the nu
2a880 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 75 70  mber of bytes up
2a890 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65   to the first ze
2a8a0 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a  ro terminator..*
2a8b0 2a 20 49 66 20 74 68 65 20 66 6f 75 72 74 68 20  * If the fourth 
2a8c0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
2a8d0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29  ite3_bind_blob()
2a8e0 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
2a8f0 65 6e 0a 2a 2a 20 74 68 65 20 62 65 68 61 76 69  en.** the behavi
2a900 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  or is undefined.
2a910 0a 2a 2a 20 49 66 20 61 20 6e 6f 6e 2d 6e 65 67  .** If a non-neg
2a920 61 74 69 76 65 20 66 6f 75 72 74 68 20 70 61 72  ative fourth par
2a930 61 6d 65 74 65 72 20 69 73 20 70 72 6f 76 69 64  ameter is provid
2a940 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  ed to sqlite3_bi
2a950 6e 64 5f 74 65 78 74 28 29 0a 2a 2a 20 6f 72 20  nd_text().** or 
2a960 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
2a970 74 31 36 28 29 20 6f 72 20 73 71 6c 69 74 65 33  t16() or sqlite3
2a980 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 29 20 74  _bind_text64() t
2a990 68 65 6e 0a 2a 2a 20 74 68 61 74 20 70 61 72 61  hen.** that para
2a9a0 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20 74 68  meter must be th
2a9b0 65 20 62 79 74 65 20 6f 66 66 73 65 74 0a 2a 2a  e byte offset.**
2a9c0 20 77 68 65 72 65 20 74 68 65 20 4e 55 4c 20 74   where the NUL t
2a9d0 65 72 6d 69 6e 61 74 6f 72 20 77 6f 75 6c 64 20  erminator would 
2a9e0 6f 63 63 75 72 20 61 73 73 75 6d 69 6e 67 20 74  occur assuming t
2a9f0 68 65 20 73 74 72 69 6e 67 20 77 65 72 65 20 4e  he string were N
2aa00 55 4c 0a 2a 2a 20 74 65 72 6d 69 6e 61 74 65 64  UL.** terminated
2aa10 2e 20 20 49 66 20 61 6e 79 20 4e 55 4c 20 63 68  .  If any NUL ch
2aa20 61 72 61 63 74 65 72 73 20 6f 63 63 75 72 20 61  aracters occur a
2aa30 74 20 62 79 74 65 20 6f 66 66 73 65 74 73 20 6c  t byte offsets l
2aa40 65 73 73 20 74 68 61 6e 20 0a 2a 2a 20 74 68 65  ess than .** the
2aa50 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 66 6f   value of the fo
2aa60 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
2aa70 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 69 6e  hen the resultin
2aa80 67 20 73 74 72 69 6e 67 20 76 61 6c 75 65 20 77  g string value w
2aa90 69 6c 6c 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 65  ill.** contain e
2aaa0 6d 62 65 64 64 65 64 20 4e 55 4c 73 2e 20 20 54  mbedded NULs.  T
2aab0 68 65 20 72 65 73 75 6c 74 20 6f 66 20 65 78 70  he result of exp
2aac0 72 65 73 73 69 6f 6e 73 20 69 6e 76 6f 6c 76 69  ressions involvi
2aad0 6e 67 20 73 74 72 69 6e 67 73 0a 2a 2a 20 77 69  ng strings.** wi
2aae0 74 68 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73  th embedded NULs
2aaf0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
2ab00 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74 68 20  *.** ^The fifth 
2ab10 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
2ab20 42 4c 4f 42 20 61 6e 64 20 73 74 72 69 6e 67 20  BLOB and string 
2ab30 62 69 6e 64 69 6e 67 20 69 6e 74 65 72 66 61 63  binding interfac
2ab40 65 73 0a 2a 2a 20 69 73 20 61 20 64 65 73 74 72  es.** is a destr
2ab50 75 63 74 6f 72 20 75 73 65 64 20 74 6f 20 64 69  uctor used to di
2ab60 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f  spose of the BLO
2ab70 42 20 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20 61  B or.** string a
2ab80 66 74 65 72 20 53 51 4c 69 74 65 20 68 61 73 20  fter SQLite has 
2ab90 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 74  finished with it
2aba0 2e 20 20 5e 54 68 65 20 64 65 73 74 72 75 63 74  .  ^The destruct
2abb0 6f 72 20 69 73 20 63 61 6c 6c 65 64 0a 2a 2a 20  or is called.** 
2abc0 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68  to dispose of th
2abd0 65 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67  e BLOB or string
2abe0 20 65 76 65 6e 20 69 66 20 74 68 65 20 63 61 6c   even if the cal
2abf0 6c 20 74 6f 20 62 69 6e 64 20 41 50 49 20 66 61  l to bind API fa
2ac00 69 6c 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ils..** ^If the 
2ac10 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 69  fifth argument i
2ac20 73 0a 2a 2a 20 74 68 65 20 73 70 65 63 69 61 6c  s.** the special
2ac30 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53   value [SQLITE_S
2ac40 54 41 54 49 43 5d 2c 20 74 68 65 6e 20 53 51 4c  TATIC], then SQL
2ac50 69 74 65 20 61 73 73 75 6d 65 73 20 74 68 61 74  ite assumes that
2ac60 20 74 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74   the.** informat
2ac70 69 6f 6e 20 69 73 20 69 6e 20 73 74 61 74 69 63  ion is in static
2ac80 2c 20 75 6e 6d 61 6e 61 67 65 64 20 73 70 61 63  , unmanaged spac
2ac90 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e  e and does not n
2aca0 65 65 64 20 74 6f 20 62 65 20 66 72 65 65 64 2e  eed to be freed.
2acb0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74  .** ^If the fift
2acc0 68 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20 74  h argument has t
2acd0 68 65 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45  he value [SQLITE
2ace0 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65  _TRANSIENT], the
2acf0 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65  n.** SQLite make
2ad00 73 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74  s its own privat
2ad10 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 64 61  e copy of the da
2ad20 74 61 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20  ta immediately, 
2ad30 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 20 73 71  before.** the sq
2ad40 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72  lite3_bind_*() r
2ad50 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a  outine returns..
2ad60 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74 68  **.** ^The sixth
2ad70 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
2ad80 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34  ite3_bind_text64
2ad90 28 29 20 6d 75 73 74 20 62 65 20 6f 6e 65 20 6f  () must be one o
2ada0 66 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46  f.** [SQLITE_UTF
2adb0 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  8], [SQLITE_UTF1
2adc0 36 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  6], [SQLITE_UTF1
2add0 36 42 45 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  6BE], or [SQLITE
2ade0 5f 55 54 46 31 36 4c 45 5d 0a 2a 2a 20 74 6f 20  _UTF16LE].** to 
2adf0 73 70 65 63 69 66 79 20 74 68 65 20 65 6e 63 6f  specify the enco
2ae00 64 69 6e 67 20 6f 66 20 74 68 65 20 74 65 78 74  ding of the text
2ae10 20 69 6e 20 74 68 65 20 74 68 69 72 64 20 70 61   in the third pa
2ae20 72 61 6d 65 74 65 72 2e 20 20 49 66 0a 2a 2a 20  rameter.  If.** 
2ae30 74 68 65 20 73 69 78 74 68 20 61 72 67 75 6d 65  the sixth argume
2ae40 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  nt to sqlite3_bi
2ae50 6e 64 5f 74 65 78 74 36 34 28 29 20 69 73 20 6e  nd_text64() is n
2ae60 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a  ot one of the.**
2ae70 20 61 6c 6c 6f 77 65 64 20 76 61 6c 75 65 73 20   allowed values 
2ae80 73 68 6f 77 6e 20 61 62 6f 76 65 2c 20 6f 72 20  shown above, or 
2ae90 69 66 20 74 68 65 20 74 65 78 74 20 65 6e 63 6f  if the text enco
2aea0 64 69 6e 67 20 69 73 20 64 69 66 66 65 72 65 6e  ding is differen
2aeb0 74 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 65 6e  t.** from the en
2aec0 63 6f 64 69 6e 67 20 73 70 65 63 69 66 69 65 64  coding specified
2aed0 20 62 79 20 74 68 65 20 73 69 78 74 68 20 70 61   by the sixth pa
2aee0 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 20 74 68  rameter, then th
2aef0 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 69 73  e behavior.** is
2af00 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
2af10 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62  * ^The sqlite3_b
2af20 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 72  ind_zeroblob() r
2af30 6f 75 74 69 6e 65 20 62 69 6e 64 73 20 61 20 42  outine binds a B
2af40 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 68 20 4e 20  LOB of length N 
2af50 74 68 61 74 0a 2a 2a 20 69 73 20 66 69 6c 6c 65  that.** is fille
2af60 64 20 77 69 74 68 20 7a 65 72 6f 65 73 2e 20 20  d with zeroes.  
2af70 5e 41 20 7a 65 72 6f 62 6c 6f 62 20 75 73 65 73  ^A zeroblob uses
2af80 20 61 20 66 69 78 65 64 20 61 6d 6f 75 6e 74 20   a fixed amount 
2af90 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75  of memory.** (ju
2afa0 73 74 20 61 6e 20 69 6e 74 65 67 65 72 20 74 6f  st an integer to
2afb0 20 68 6f 6c 64 20 69 74 73 20 73 69 7a 65 29 20   hold its size) 
2afc0 77 68 69 6c 65 20 69 74 20 69 73 20 62 65 69 6e  while it is bein
2afd0 67 20 70 72 6f 63 65 73 73 65 64 2e 0a 2a 2a 20  g processed..** 
2afe0 5a 65 72 6f 62 6c 6f 62 73 20 61 72 65 20 69 6e  Zeroblobs are in
2aff0 74 65 6e 64 65 64 20 74 6f 20 73 65 72 76 65 20  tended to serve 
2b000 61 73 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20  as placeholders 
2b010 66 6f 72 20 42 4c 4f 42 73 20 77 68 6f 73 65 0a  for BLOBs whose.
2b020 2a 2a 20 63 6f 6e 74 65 6e 74 20 69 73 20 6c 61  ** content is la
2b030 74 65 72 20 77 72 69 74 74 65 6e 20 75 73 69 6e  ter written usin
2b040 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c  g.** [sqlite3_bl
2b050 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d  ob_open | increm
2b060 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20  ental BLOB I/O] 
2b070 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 5e 41 20  routines..** ^A 
2b080 6e 65 67 61 74 69 76 65 20 76 61 6c 75 65 20 66  negative value f
2b090 6f 72 20 74 68 65 20 7a 65 72 6f 62 6c 6f 62 20  or the zeroblob 
2b0a0 72 65 73 75 6c 74 73 20 69 6e 20 61 20 7a 65 72  results in a zer
2b0b0 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a  o-length BLOB..*
2b0c0 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79 20 6f 66 20  *.** ^If any of 
2b0d0 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
2b0e0 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 61 72  _*() routines ar
2b0f0 65 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20  e called with a 
2b100 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  NULL pointer.** 
2b110 66 6f 72 20 74 68 65 20 5b 70 72 65 70 61 72 65  for the [prepare
2b120 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 72 20  d statement] or 
2b130 77 69 74 68 20 61 20 70 72 65 70 61 72 65 64 20  with a prepared 
2b140 73 74 61 74 65 6d 65 6e 74 20 66 6f 72 20 77 68  statement for wh
2b150 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ich.** [sqlite3_
2b160 73 74 65 70 28 29 5d 20 68 61 73 20 62 65 65 6e  step()] has been
2b170 20 63 61 6c 6c 65 64 20 6d 6f 72 65 20 72 65 63   called more rec
2b180 65 6e 74 6c 79 20 74 68 61 6e 20 5b 73 71 6c 69  ently than [sqli
2b190 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 0a 2a 2a  te3_reset()],.**
2b1a0 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 20 77   then the call w
2b1b0 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  ill return [SQLI
2b1c0 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 49 66 20  TE_MISUSE].  If 
2b1d0 61 6e 79 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  any sqlite3_bind
2b1e0 5f 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 69  _().** routine i
2b1f0 73 20 70 61 73 73 65 64 20 61 20 5b 70 72 65 70  s passed a [prep
2b200 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2b210 74 68 61 74 20 68 61 73 20 62 65 65 6e 20 66 69  that has been fi
2b220 6e 61 6c 69 7a 65 64 2c 20 74 68 65 0a 2a 2a 20  nalized, the.** 
2b230 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69  result is undefi
2b240 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79  ned and probably
2b250 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20   harmful..**.** 
2b260 5e 42 69 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f  ^Bindings are no
2b270 74 20 63 6c 65 61 72 65 64 20 62 79 20 74 68 65  t cleared by the
2b280 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2b290 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 5e  )] routine..** ^
2b2a0 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65  Unbound paramete
2b2b0 72 73 20 61 72 65 20 69 6e 74 65 72 70 72 65 74  rs are interpret
2b2c0 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  ed as NULL..**.*
2b2d0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62  * ^The sqlite3_b
2b2e0 69 6e 64 5f 2a 20 72 6f 75 74 69 6e 65 73 20 72  ind_* routines r
2b2f0 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b  eturn [SQLITE_OK
2b300 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 6f 72 20  ] on success or 
2b310 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64  an.** [error cod
2b320 65 5d 20 69 66 20 61 6e 79 74 68 69 6e 67 20 67  e] if anything g
2b330 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b  oes wrong..** ^[
2b340 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 5d 20 6d  SQLITE_TOOBIG] m
2b350 69 67 68 74 20 62 65 20 72 65 74 75 72 6e 65 64  ight be returned
2b360 20 69 66 20 74 68 65 20 73 69 7a 65 20 6f 66 20   if the size of 
2b370 61 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42  a string or BLOB
2b380 0a 2a 2a 20 65 78 63 65 65 64 73 20 6c 69 6d 69  .** exceeds limi
2b390 74 73 20 69 6d 70 6f 73 65 64 20 62 79 20 5b 73  ts imposed by [s
2b3a0 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53  qlite3_limit]([S
2b3b0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47  QLITE_LIMIT_LENG
2b3c0 54 48 5d 29 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49  TH]) or.** [SQLI
2b3d0 54 45 5f 4d 41 58 5f 4c 45 4e 47 54 48 5d 2e 0a  TE_MAX_LENGTH]..
2b3e0 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 52 41 4e 47  ** ^[SQLITE_RANG
2b3f0 45 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69  E] is returned i
2b400 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 0a  f the parameter.
2b410 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20  ** index is out 
2b420 6f 66 20 72 61 6e 67 65 2e 20 20 5e 5b 53 51 4c  of range.  ^[SQL
2b430 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65  ITE_NOMEM] is re
2b440 74 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63  turned if malloc
2b450 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20  () fails..**.** 
2b460 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
2b470 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
2b480 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b  r_count()],.** [
2b490 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
2b4a0 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20  ameter_name()], 
2b4b0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  and [sqlite3_bin
2b4c0 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
2b4d0 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  x()]..*/.SQLITE_
2b4e0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
2b4f0 62 69 6e 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65  bind_blob(sqlite
2b500 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f  3_stmt*, int, co
2b510 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e  nst void*, int n
2b520 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
2b530 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
2b540 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62  t sqlite3_bind_b
2b550 6c 6f 62 36 34 28 73 71 6c 69 74 65 33 5f 73 74  lob64(sqlite3_st
2b560 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
2b570 76 6f 69 64 2a 2c 20 73 71 6c 69 74 65 33 5f 75  void*, sqlite3_u
2b580 69 6e 74 36 34 2c 0a 20 20 20 20 20 20 20 20 20  int64,.         
2b590 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76                 v
2b5a0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
2b5b0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
2b5c0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62  qlite3_bind_doub
2b5d0 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  le(sqlite3_stmt*
2b5e0 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a  , int, double);.
2b5f0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
2b600 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 28  qlite3_bind_int(
2b610 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2b620 6e 74 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45  nt, int);.SQLITE
2b630 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
2b640 5f 62 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69  _bind_int64(sqli
2b650 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
2b660 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a  sqlite3_int64);.
2b670 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
2b680 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c  qlite3_bind_null
2b690 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2b6a0 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  int);.SQLITE_API
2b6b0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e   int sqlite3_bin
2b6c0 64 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73  d_text(sqlite3_s
2b6d0 74 6d 74 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63  tmt*,int,const c
2b6e0 68 61 72 2a 2c 69 6e 74 2c 76 6f 69 64 28 2a 29  har*,int,void(*)
2b6f0 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45  (void*));.SQLITE
2b700 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
2b710 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 73 71 6c  _bind_text16(sql
2b720 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
2b730 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
2b740 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  t, void(*)(void*
2b750 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  ));.SQLITE_API i
2b760 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
2b770 74 65 78 74 36 34 28 73 71 6c 69 74 65 33 5f 73  text64(sqlite3_s
2b780 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
2b790 20 63 68 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f   char*, sqlite3_
2b7a0 75 69 6e 74 36 34 2c 0a 20 20 20 20 20 20 20 20  uint64,.        
2b7b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2b7c0 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 2c   void(*)(void*),
2b7d0 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 65   unsigned char e
2b7e0 6e 63 6f 64 69 6e 67 29 3b 0a 53 51 4c 49 54 45  ncoding);.SQLITE
2b7f0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
2b800 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69  _bind_value(sqli
2b810 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
2b820 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61  const sqlite3_va
2b830 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  lue*);.SQLITE_AP
2b840 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  I int sqlite3_bi
2b850 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69  nd_zeroblob(sqli
2b860 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
2b870 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  int n);../*.** C
2b880 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20  API3REF: Number 
2b890 4f 66 20 53 51 4c 20 50 61 72 61 6d 65 74 65 72  Of SQL Parameter
2b8a0 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f  s.**.** ^This ro
2b8b0 75 74 69 6e 65 20 63 61 6e 20 62 65 20 75 73 65  utine can be use
2b8c0 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75  d to find the nu
2b8d0 6d 62 65 72 20 6f 66 20 5b 53 51 4c 20 70 61 72  mber of [SQL par
2b8e0 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 6e 20 61  ameters].** in a
2b8f0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2b900 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 70 61 72 61  ment].  SQL para
2b910 6d 65 74 65 72 73 20 61 72 65 20 74 6f 6b 65 6e  meters are token
2b920 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d  s of the.** form
2b930 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a   "?", "?NNN", ":
2b940 41 41 41 22 2c 20 22 24 41 41 41 22 2c 20 6f 72  AAA", "$AAA", or
2b950 20 22 40 41 41 41 22 20 74 68 61 74 20 73 65 72   "@AAA" that ser
2b960 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65 68 6f  ve as.** placeho
2b970 6c 64 65 72 73 20 66 6f 72 20 76 61 6c 75 65 73  lders for values
2b980 20 74 68 61 74 20 61 72 65 20 5b 73 71 6c 69 74   that are [sqlit
2b990 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62  e3_bind_blob | b
2b9a0 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20  ound].** to the 
2b9b0 70 61 72 61 6d 65 74 65 72 73 20 61 74 20 61 20  parameters at a 
2b9c0 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a  later time..**.*
2b9d0 2a 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65  * ^(This routine
2b9e0 20 61 63 74 75 61 6c 6c 79 20 72 65 74 75 72 6e   actually return
2b9f0 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74  s the index of t
2ba00 68 65 20 6c 61 72 67 65 73 74 20 28 72 69 67 68  he largest (righ
2ba10 74 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 61 6d 65  tmost).** parame
2ba20 74 65 72 2e 20 46 6f 72 20 61 6c 6c 20 66 6f 72  ter. For all for
2ba30 6d 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20  ms except ?NNN, 
2ba40 74 68 69 73 20 77 69 6c 6c 20 63 6f 72 72 65 73  this will corres
2ba50 70 6f 6e 64 20 74 6f 20 74 68 65 0a 2a 2a 20 6e  pond to the.** n
2ba60 75 6d 62 65 72 20 6f 66 20 75 6e 69 71 75 65 20  umber of unique 
2ba70 70 61 72 61 6d 65 74 65 72 73 2e 20 20 49 66 20  parameters.  If 
2ba80 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68  parameters of th
2ba90 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61 72 65 20  e ?NNN form are 
2baa0 75 73 65 64 2c 0a 2a 2a 20 74 68 65 72 65 20 6d  used,.** there m
2bab0 61 79 20 62 65 20 67 61 70 73 20 69 6e 20 74 68  ay be gaps in th
2bac0 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20  e list.)^.**.** 
2bad0 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
2bae0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c  e3_bind_blob|sql
2baf0 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a  ite3_bind()],.**
2bb00 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
2bb10 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d  arameter_name()]
2bb20 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  , and.** [sqlite
2bb30 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
2bb40 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51  _index()]..*/.SQ
2bb50 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
2bb60 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
2bb70 74 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65  ter_count(sqlite
2bb80 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  3_stmt*);../*.**
2bb90 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20   CAPI3REF: Name 
2bba0 4f 66 20 41 20 48 6f 73 74 20 50 61 72 61 6d 65  Of A Host Parame
2bbb0 74 65 72 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ter.**.** ^The s
2bbc0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2bbd0 6d 65 74 65 72 5f 6e 61 6d 65 28 50 2c 4e 29 20  meter_name(P,N) 
2bbe0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
2bbf0 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66  s.** the name of
2bc00 20 74 68 65 20 4e 2d 74 68 20 5b 53 51 4c 20 70   the N-th [SQL p
2bc10 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65  arameter] in the
2bc20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2bc30 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53 51  ment] P..** ^(SQ
2bc40 4c 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20  L parameters of 
2bc50 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20  the form "?NNN" 
2bc60 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41  or ":AAA" or "@A
2bc70 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a  AA" or "$AAA".**
2bc80 20 68 61 76 65 20 61 20 6e 61 6d 65 20 77 68 69   have a name whi
2bc90 63 68 20 69 73 20 74 68 65 20 73 74 72 69 6e 67  ch is the string
2bca0 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41   "?NNN" or ":AAA
2bcb0 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22  " or "@AAA" or "
2bcc0 24 41 41 41 22 0a 2a 2a 20 72 65 73 70 65 63 74  $AAA".** respect
2bcd0 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68  ively..** In oth
2bce0 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 69 6e  er words, the in
2bcf0 69 74 69 61 6c 20 22 3a 22 20 6f 72 20 22 24 22  itial ":" or "$"
2bd00 20 6f 72 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a   or "@" or "?".*
2bd10 2a 20 69 73 20 69 6e 63 6c 75 64 65 64 20 61 73  * is included as
2bd20 20 70 61 72 74 20 6f 66 20 74 68 65 20 6e 61 6d   part of the nam
2bd30 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65 74  e.)^.** ^Paramet
2bd40 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20  ers of the form 
2bd50 22 3f 22 20 77 69 74 68 6f 75 74 20 61 20 66 6f  "?" without a fo
2bd60 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65 72 20  llowing integer 
2bd70 68 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20  have no name.** 
2bd80 61 6e 64 20 61 72 65 20 72 65 66 65 72 72 65 64  and are referred
2bd90 20 74 6f 20 61 73 20 22 6e 61 6d 65 6c 65 73 73   to as "nameless
2bda0 22 20 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75 73 20  " or "anonymous 
2bdb0 70 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a  parameters"..**.
2bdc0 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 68 6f  ** ^The first ho
2bdd0 73 74 20 70 61 72 61 6d 65 74 65 72 20 68 61 73  st parameter has
2bde0 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c 20   an index of 1, 
2bdf0 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  not 0..**.** ^If
2be00 20 74 68 65 20 76 61 6c 75 65 20 4e 20 69 73 20   the value N is 
2be10 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 6f 72 20  out of range or 
2be20 69 66 20 74 68 65 20 4e 2d 74 68 20 70 61 72 61  if the N-th para
2be30 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65  meter is.** name
2be40 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20  less, then NULL 
2be50 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 5e 54  is returned.  ^T
2be60 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69  he returned stri
2be70 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73 20  ng is.** always 
2be80 69 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e  in UTF-8 encodin
2be90 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 6e 61  g even if the na
2bea0 6d 65 64 20 70 61 72 61 6d 65 74 65 72 20 77 61  med parameter wa
2beb0 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 20  s.** originally 
2bec0 73 70 65 63 69 66 69 65 64 20 61 73 20 55 54 46  specified as UTF
2bed0 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f  -16 in [sqlite3_
2bee0 70 72 65 70 61 72 65 31 36 28 29 5d 20 6f 72 0a  prepare16()] or.
2bef0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
2bf00 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a  are16_v2()]..**.
2bf10 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
2bf20 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
2bf30 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c  sqlite3_bind()],
2bf40 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
2bf50 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e  d_parameter_coun
2bf60 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71  t()], and.** [sq
2bf70 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
2bf80 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a  eter_index()]..*
2bf90 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  /.SQLITE_API con
2bfa0 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
2bfb0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
2bfc0 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
2bfd0 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  t*, int);../*.**
2bfe0 20 43 41 50 49 33 52 45 46 3a 20 49 6e 64 65 78   CAPI3REF: Index
2bff0 20 4f 66 20 41 20 50 61 72 61 6d 65 74 65 72 20   Of A Parameter 
2c000 57 69 74 68 20 41 20 47 69 76 65 6e 20 4e 61 6d  With A Given Nam
2c010 65 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20  e.**.** ^Return 
2c020 74 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20  the index of an 
2c030 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 67 69  SQL parameter gi
2c040 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20 5e  ven its name.  ^
2c050 54 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c  The.** index val
2c060 75 65 20 72 65 74 75 72 6e 65 64 20 69 73 20 73  ue returned is s
2c070 75 69 74 61 62 6c 65 20 66 6f 72 20 75 73 65 20  uitable for use 
2c080 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a  as the second.**
2c090 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
2c0a0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
2c0b0 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d  |sqlite3_bind()]
2c0c0 2e 20 20 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69 73  .  ^A zero.** is
2c0d0 20 72 65 74 75 72 6e 65 64 20 69 66 20 6e 6f 20   returned if no 
2c0e0 6d 61 74 63 68 69 6e 67 20 70 61 72 61 6d 65 74  matching paramet
2c0f0 65 72 20 69 73 20 66 6f 75 6e 64 2e 20 20 5e 54  er is found.  ^T
2c100 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  he parameter.** 
2c110 6e 61 6d 65 20 6d 75 73 74 20 62 65 20 67 69 76  name must be giv
2c120 65 6e 20 69 6e 20 55 54 46 2d 38 20 65 76 65 6e  en in UTF-8 even
2c130 20 69 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c   if the original
2c140 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61   statement.** wa
2c150 73 20 70 72 65 70 61 72 65 64 20 66 72 6f 6d 20  s prepared from 
2c160 55 54 46 2d 31 36 20 74 65 78 74 20 75 73 69 6e  UTF-16 text usin
2c170 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  g [sqlite3_prepa
2c180 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a  re16_v2()]..**.*
2c190 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
2c1a0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73  ite3_bind_blob|s
2c1b0 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a  qlite3_bind()],.
2c1c0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
2c1d0 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74  _parameter_count
2c1e0 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
2c1f0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
2c200 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f  ter_index()]..*/
2c210 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
2c220 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
2c230 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 73 71 6c  ameter_index(sql
2c240 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73  ite3_stmt*, cons
2c250 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a  t char *zName);.
2c260 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2c270 20 52 65 73 65 74 20 41 6c 6c 20 42 69 6e 64 69   Reset All Bindi
2c280 6e 67 73 20 4f 6e 20 41 20 50 72 65 70 61 72 65  ngs On A Prepare
2c290 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a  d Statement.**.*
2c2a0 2a 20 5e 43 6f 6e 74 72 61 72 79 20 74 6f 20 74  * ^Contrary to t
2c2b0 68 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66 20  he intuition of 
2c2c0 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f 72  many, [sqlite3_r
2c2d0 65 73 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f 74  eset()] does not
2c2e0 20 72 65 73 65 74 0a 2a 2a 20 74 68 65 20 5b 73   reset.** the [s
2c2f0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
2c300 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20   | bindings] on 
2c310 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
2c320 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 65 20  ement]..** ^Use 
2c330 74 68 69 73 20 72 6f 75 74 69 6e 65 20 74 6f 20  this routine to 
2c340 72 65 73 65 74 20 61 6c 6c 20 68 6f 73 74 20 70  reset all host p
2c350 61 72 61 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c  arameters to NUL
2c360 4c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  L..*/.SQLITE_API
2c370 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 65   int sqlite3_cle
2c380 61 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69  ar_bindings(sqli
2c390 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a  te3_stmt*);../*.
2c3a0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d  ** CAPI3REF: Num
2c3b0 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49  ber Of Columns I
2c3c0 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a  n A Result Set.*
2c3d0 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65  *.** ^Return the
2c3e0 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
2c3f0 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74  ns in the result
2c400 20 73 65 74 20 72 65 74 75 72 6e 65 64 20 62 79   set returned by
2c410 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
2c420 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e 54  d statement]. ^T
2c430 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75  his routine retu
2c440 72 6e 73 20 30 20 69 66 20 70 53 74 6d 74 20 69  rns 0 if pStmt i
2c450 73 20 61 6e 20 53 51 4c 0a 2a 2a 20 73 74 61 74  s an SQL.** stat
2c460 65 6d 65 6e 74 20 74 68 61 74 20 64 6f 65 73 20  ement that does 
2c470 6e 6f 74 20 72 65 74 75 72 6e 20 64 61 74 61 20  not return data 
2c480 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 61 6e 20  (for example an 
2c490 5b 55 50 44 41 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a  [UPDATE])..**.**
2c4a0 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
2c4b0 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 29  te3_data_count()
2c4c0 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ].*/.SQLITE_API 
2c4d0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
2c4e0 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33  mn_count(sqlite3
2c4f0 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
2c500 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2c510 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20  Column Names In 
2c520 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a  A Result Set.**.
2c530 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
2c540 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61  es return the na
2c550 6d 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20 61  me assigned to a
2c560 20 70 61 72 74 69 63 75 6c 61 72 20 63 6f 6c 75   particular colu
2c570 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65 73  mn.** in the res
2c580 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45  ult set of a [SE
2c590 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e  LECT] statement.
2c5a0 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63    ^The sqlite3_c
2c5b0 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20  olumn_name().** 
2c5c0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
2c5d0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
2c5e0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
2c5f0 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a   UTF-8 string.**
2c600 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
2c610 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65 74  umn_name16() ret
2c620 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
2c630 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  o a zero-termina
2c640 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74  ted.** UTF-16 st
2c650 72 69 6e 67 2e 20 20 5e 54 68 65 20 66 69 72 73  ring.  ^The firs
2c660 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  t parameter is t
2c670 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
2c680 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20  tement].** that 
2c690 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b  implements the [
2c6a0 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
2c6b0 74 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70  t. ^The second p
2c6c0 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a  arameter is the.
2c6d0 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72  ** column number
2c6e0 2e 20 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74  .  ^The leftmost
2c6f0 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65   column is numbe
2c700 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  r 0..**.** ^The 
2c710 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20  returned string 
2c720 70 6f 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64  pointer is valid
2c730 20 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68   until either th
2c740 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
2c750 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73  ement].** is des
2c760 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74  troyed by [sqlit
2c770 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f  e3_finalize()] o
2c780 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74  r until the stat
2c790 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74  ement is automat
2c7a0 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70  ically.** reprep
2c7b0 61 72 65 64 20 62 79 20 74 68 65 20 66 69 72 73  ared by the firs
2c7c0 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  t call to [sqlit
2c7d0 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61  e3_step()] for a
2c7e0 20 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a   particular run.
2c7f0 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20  ** or until the 
2c800 6e 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  next call to.** 
2c810 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
2c820 61 6d 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ame() or sqlite3
2c830 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29  _column_name16()
2c840 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 63 6f 6c   on the same col
2c850 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73  umn..**.** ^If s
2c860 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
2c870 66 61 69 6c 73 20 64 75 72 69 6e 67 20 74 68 65  fails during the
2c880 20 70 72 6f 63 65 73 73 69 6e 67 20 6f 66 20 65   processing of e
2c890 69 74 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a  ither routine.**
2c8a0 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 64 75   (for example du
2c8b0 72 69 6e 67 20 61 20 63 6f 6e 76 65 72 73 69 6f  ring a conversio
2c8c0 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20  n from UTF-8 to 
2c8d0 55 54 46 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a  UTF-16) then a.*
2c8e0 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  * NULL pointer i
2c8f0 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
2c900 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 61  * ^The name of a
2c910 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69   result column i
2c920 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  s the value of t
2c930 68 65 20 22 41 53 22 20 63 6c 61 75 73 65 20 66  he "AS" clause f
2c940 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d  or.** that colum
2c950 6e 2c 20 69 66 20 74 68 65 72 65 20 69 73 20 61  n, if there is a
2c960 6e 20 41 53 20 63 6c 61 75 73 65 2e 20 20 49 66  n AS clause.  If
2c970 20 74 68 65 72 65 20 69 73 20 6e 6f 20 41 53 20   there is no AS 
2c980 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74  clause.** then t
2c990 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63  he name of the c
2c9a0 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65 63 69  olumn is unspeci
2c9b0 66 69 65 64 20 61 6e 64 20 6d 61 79 20 63 68 61  fied and may cha
2c9c0 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20  nge from.** one 
2c9d0 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74  release of SQLit
2c9e0 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a  e to the next..*
2c9f0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  /.SQLITE_API con
2ca00 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
2ca10 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c  _column_name(sql
2ca20 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
2ca30 4e 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  N);.SQLITE_API c
2ca40 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
2ca50 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36  e3_column_name16
2ca60 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2ca70 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  int N);../*.** C
2ca80 41 50 49 33 52 45 46 3a 20 53 6f 75 72 63 65 20  API3REF: Source 
2ca90 4f 66 20 44 61 74 61 20 49 6e 20 41 20 51 75 65  Of Data In A Que
2caa0 72 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20  ry Result.**.** 
2cab0 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
2cac0 70 72 6f 76 69 64 65 20 61 20 6d 65 61 6e 73 20  provide a means 
2cad0 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65  to determine the
2cae0 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65   database, table
2caf0 2c 20 61 6e 64 0a 2a 2a 20 74 61 62 6c 65 20 63  , and.** table c
2cb00 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73 20 74 68  olumn that is th
2cb10 65 20 6f 72 69 67 69 6e 20 6f 66 20 61 20 70 61  e origin of a pa
2cb20 72 74 69 63 75 6c 61 72 20 72 65 73 75 6c 74 20  rticular result 
2cb30 63 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 5b 53 45  column in.** [SE
2cb40 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e  LECT] statement.
2cb50 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66  .** ^The name of
2cb60 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 72   the database or
2cb70 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e   table or column
2cb80 20 63 61 6e 20 62 65 20 72 65 74 75 72 6e 65 64   can be returned
2cb90 20 61 73 0a 2a 2a 20 65 69 74 68 65 72 20 61 20   as.** either a 
2cba0 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20  UTF-8 or UTF-16 
2cbb0 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 5f 64  string.  ^The _d
2cbc0 61 74 61 62 61 73 65 5f 20 72 6f 75 74 69 6e 65  atabase_ routine
2cbd0 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20  s return.** the 
2cbe0 64 61 74 61 62 61 73 65 20 6e 61 6d 65 2c 20 74  database name, t
2cbf0 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69  he _table_ routi
2cc00 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 74  nes return the t
2cc10 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a  able name, and.*
2cc20 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f  * the origin_ ro
2cc30 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68  utines return th
2cc40 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a  e column name..*
2cc50 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20  * ^The returned 
2cc60 73 74 72 69 6e 67 20 69 73 20 76 61 6c 69 64 20  string is valid 
2cc70 75 6e 74 69 6c 20 74 68 65 20 5b 70 72 65 70 61  until the [prepa
2cc80 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69  red statement] i
2cc90 73 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20 75  s destroyed.** u
2cca0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69  sing [sqlite3_fi
2ccb0 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74  nalize()] or unt
2ccc0 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  il the statement
2ccd0 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c   is automaticall
2cce0 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64 20  y.** reprepared 
2ccf0 62 79 20 74 68 65 20 66 69 72 73 74 20 63 61 6c  by the first cal
2cd00 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  l to [sqlite3_st
2cd10 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72 74  ep()] for a part
2cd20 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72  icular run.** or
2cd30 20 75 6e 74 69 6c 20 74 68 65 20 73 61 6d 65 20   until the same 
2cd40 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72  information is r
2cd50 65 71 75 65 73 74 65 64 0a 2a 2a 20 61 67 61 69  equested.** agai
2cd60 6e 20 69 6e 20 61 20 64 69 66 66 65 72 65 6e 74  n in a different
2cd70 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a   encoding..**.**
2cd80 20 5e 54 68 65 20 6e 61 6d 65 73 20 72 65 74 75   ^The names retu
2cd90 72 6e 65 64 20 61 72 65 20 74 68 65 20 6f 72 69  rned are the ori
2cda0 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65 64  ginal un-aliased
2cdb0 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a   names of the.**
2cdc0 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65   database, table
2cdd0 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a  , and column..**
2cde0 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61  .** ^The first a
2cdf0 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 73 65  rgument to these
2ce00 20 69 6e 74 65 72 66 61 63 65 73 20 69 73 20 61   interfaces is a
2ce10 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2ce20 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 65 73 65  ment]..** ^These
2ce30 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72   functions retur
2ce40 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62  n information ab
2ce50 6f 75 74 20 74 68 65 20 4e 74 68 20 72 65 73 75  out the Nth resu
2ce60 6c 74 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e  lt column return
2ce70 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 73 74 61  ed by.** the sta
2ce80 74 65 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e 20  tement, where N 
2ce90 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75  is the second fu
2cea0 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e  nction argument.
2ceb0 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 2d 6d 6f  .** ^The left-mo
2cec0 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 63 6f 6c  st column is col
2ced0 75 6d 6e 20 30 20 66 6f 72 20 74 68 65 73 65 20  umn 0 for these 
2cee0 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20  routines..**.** 
2cef0 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75  ^If the Nth colu
2cf00 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  mn returned by t
2cf10 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
2cf20 61 6e 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72  an expression or
2cf30 0a 2a 2a 20 73 75 62 71 75 65 72 79 20 61 6e 64  .** subquery and
2cf40 20 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e   is not a column
2cf50 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c 6c   value, then all
2cf60 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 69   of these functi
2cf70 6f 6e 73 20 72 65 74 75 72 6e 0a 2a 2a 20 4e 55  ons return.** NU
2cf80 4c 4c 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74  LL.  ^These rout
2cf90 69 6e 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 72  ine might also r
2cfa0 65 74 75 72 6e 20 4e 55 4c 4c 20 69 66 20 61 20  eturn NULL if a 
2cfb0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
2cfc0 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f 63 63 75 72  n error.** occur
2cfd0 73 2e 20 20 5e 4f 74 68 65 72 77 69 73 65 2c 20  s.  ^Otherwise, 
2cfe0 74 68 65 79 20 72 65 74 75 72 6e 20 74 68 65 20  they return the 
2cff0 6e 61 6d 65 20 6f 66 20 74 68 65 20 61 74 74 61  name of the atta
2d000 63 68 65 64 20 64 61 74 61 62 61 73 65 2c 20 74  ched database, t
2d010 61 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6c 75  able,.** or colu
2d020 6d 6e 20 74 68 61 74 20 71 75 65 72 79 20 72 65  mn that query re
2d030 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 61 73 20  sult column was 
2d040 65 78 74 72 61 63 74 65 64 20 66 72 6f 6d 2e 0a  extracted from..
2d050 2a 2a 0a 2a 2a 20 5e 41 73 20 77 69 74 68 20 61  **.** ^As with a
2d060 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  ll other SQLite 
2d070 41 50 49 73 2c 20 74 68 6f 73 65 20 77 68 6f 73  APIs, those whos
2d080 65 20 6e 61 6d 65 73 20 65 6e 64 20 77 69 74 68  e names end with
2d090 20 22 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20   "16" return.** 
2d0a0 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 73  UTF-16 encoded s
2d0b0 74 72 69 6e 67 73 20 61 6e 64 20 74 68 65 20 6f  trings and the o
2d0c0 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 73 20 72  ther functions r
2d0d0 65 74 75 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a  eturn UTF-8..**.
2d0e0 2a 2a 20 5e 54 68 65 73 65 20 41 50 49 73 20 61  ** ^These APIs a
2d0f0 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c  re only availabl
2d100 65 20 69 66 20 74 68 65 20 6c 69 62 72 61 72 79  e if the library
2d110 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69   was compiled wi
2d120 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  th the.** [SQLIT
2d130 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f  E_ENABLE_COLUMN_
2d140 4d 45 54 41 44 41 54 41 5d 20 43 2d 70 72 65 70  METADATA] C-prep
2d150 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 2e  rocessor symbol.
2d160 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72  .**.** If two or
2d170 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61   more threads ca
2d180 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f  ll one or more o
2d190 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
2d1a0 20 61 67 61 69 6e 73 74 20 74 68 65 20 73 61 6d   against the sam
2d1b0 65 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74  e.** prepared st
2d1c0 61 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75  atement and colu
2d1d0 6d 6e 20 61 74 20 74 68 65 20 73 61 6d 65 20 74  mn at the same t
2d1e0 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73  ime then the res
2d1f0 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64 65  ults are.** unde
2d200 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  fined..**.** If 
2d210 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65  two or more thre
2d220 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20  ads call one or 
2d230 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  more.** [sqlite3
2d240 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65  _column_database
2d250 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d  _name | column m
2d260 65 74 61 64 61 74 61 20 69 6e 74 65 72 66 61 63  etadata interfac
2d270 65 73 5d 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73  es].** for the s
2d280 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  ame [prepared st
2d290 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65 73  atement] and res
2d2a0 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74  ult column.** at
2d2b0 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74   the same time t
2d2c0 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20  hen the results 
2d2d0 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  are undefined..*
2d2e0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  /.SQLITE_API con
2d2f0 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
2d300 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65  _column_database
2d310 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
2d320 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45  mt*,int);.SQLITE
2d330 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20  _API const void 
2d340 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
2d350 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 31 36 28  database_name16(
2d360 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
2d370 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  t);.SQLITE_API c
2d380 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
2d390 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f  e3_column_table_
2d3a0 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
2d3b0 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f  t*,int);.SQLITE_
2d3c0 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  API const void *
2d3d0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2d3e0 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69  able_name16(sqli
2d3f0 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
2d400 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
2d410 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
2d420 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d  olumn_origin_nam
2d430 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
2d440 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  int);.SQLITE_API
2d450 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c   const void *sql
2d460 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67  ite3_column_orig
2d470 69 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65  in_name16(sqlite
2d480 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f  3_stmt*,int);../
2d490 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
2d4a0 65 63 6c 61 72 65 64 20 44 61 74 61 74 79 70 65  eclared Datatype
2d4b0 20 4f 66 20 41 20 51 75 65 72 79 20 52 65 73 75   Of A Query Resu
2d4c0 6c 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66  lt.**.** ^(The f
2d4d0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69  irst parameter i
2d4e0 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  s a [prepared st
2d4f0 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20  atement]..** If 
2d500 74 68 69 73 20 73 74 61 74 65 6d 65 6e 74 20 69  this statement i
2d510 73 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  s a [SELECT] sta
2d520 74 65 6d 65 6e 74 20 61 6e 64 20 74 68 65 20 4e  tement and the N
2d530 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65  th column of the
2d540 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 72 65 73  .** returned res
2d550 75 6c 74 20 73 65 74 20 6f 66 20 74 68 61 74 20  ult set of that 
2d560 5b 53 45 4c 45 43 54 5d 20 69 73 20 61 20 74 61  [SELECT] is a ta
2d570 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20  ble column (not 
2d580 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e  an.** expression
2d590 20 6f 72 20 73 75 62 71 75 65 72 79 29 20 74 68   or subquery) th
2d5a0 65 6e 20 74 68 65 20 64 65 63 6c 61 72 65 64 20  en the declared 
2d5b0 74 79 70 65 20 6f 66 20 74 68 65 20 74 61 62 6c  type of the tabl
2d5c0 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 20 72  e.** column is r
2d5d0 65 74 75 72 6e 65 64 2e 29 5e 20 20 5e 49 66 20  eturned.)^  ^If 
2d5e0 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f  the Nth column o
2d5f0 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
2d600 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73   is an.** expres
2d610 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79  sion or subquery
2d620 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f  , then a NULL po
2d630 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65  inter is returne
2d640 64 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72  d..** ^The retur
2d650 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 61 6c  ned string is al
2d660 77 61 79 73 20 55 54 46 2d 38 20 65 6e 63 6f 64  ways UTF-8 encod
2d670 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20  ed..**.** ^(For 
2d680 65 78 61 6d 70 6c 65 2c 20 67 69 76 65 6e 20 74  example, given t
2d690 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65  he database sche
2d6a0 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45  ma:.**.** CREATE
2d6b0 20 54 41 42 4c 45 20 74 31 28 63 31 20 56 41 52   TABLE t1(c1 VAR
2d6c0 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64  IANT);.**.** and
2d6d0 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73   the following s
2d6e0 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63  tatement to be c
2d6f0 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53  ompiled:.**.** S
2d700 45 4c 45 43 54 20 63 31 20 2b 20 31 2c 20 63 31  ELECT c1 + 1, c1
2d710 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20   FROM t1;.**.** 
2d720 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 6f 75  this routine wou
2d730 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 73 74  ld return the st
2d740 72 69 6e 67 20 22 56 41 52 49 41 4e 54 22 20 66  ring "VARIANT" f
2d750 6f 72 20 74 68 65 20 73 65 63 6f 6e 64 20 72 65  or the second re
2d760 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28  sult.** column (
2d770 69 3d 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c  i==1), and a NUL
2d780 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68  L pointer for th
2d790 65 20 66 69 72 73 74 20 72 65 73 75 6c 74 20 63  e first result c
2d7a0 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e 29 5e 0a  olumn (i==0).)^.
2d7b0 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73  **.** ^SQLite us
2d7c0 65 73 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d 74  es dynamic run-t
2d7d0 69 6d 65 20 74 79 70 69 6e 67 2e 20 20 5e 53 6f  ime typing.  ^So
2d7e0 20 6a 75 73 74 20 62 65 63 61 75 73 65 20 61 20   just because a 
2d7f0 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63  column.** is dec
2d800 6c 61 72 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e  lared to contain
2d810 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 74 79   a particular ty
2d820 70 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e  pe does not mean
2d830 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 64 61 74   that the.** dat
2d840 61 20 73 74 6f 72 65 64 20 69 6e 20 74 68 61 74  a stored in that
2d850 20 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68   column is of th
2d860 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 2e  e declared type.
2d870 20 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73    SQLite is.** s
2d880 74 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c 20 62  trongly typed, b
2d890 75 74 20 74 68 65 20 74 79 70 69 6e 67 20 69 73  ut the typing is
2d8a0 20 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61   dynamic not sta
2d8b0 74 69 63 2e 20 20 5e 54 79 70 65 0a 2a 2a 20 69  tic.  ^Type.** i
2d8c0 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  s associated wit
2d8d0 68 20 69 6e 64 69 76 69 64 75 61 6c 20 76 61 6c  h individual val
2d8e0 75 65 73 2c 20 6e 6f 74 20 77 69 74 68 20 74 68  ues, not with th
2d8f0 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a 20  e containers.** 
2d900 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 74 68 6f  used to hold tho
2d910 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a 53 51  se values..*/.SQ
2d920 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63  LITE_API const c
2d930 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
2d940 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73 71 6c  umn_decltype(sql
2d950 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
2d960 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
2d970 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
2d980 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31  column_decltype1
2d990 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
2d9a0 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
2d9b0 49 33 52 45 46 3a 20 45 76 61 6c 75 61 74 65 20  I3REF: Evaluate 
2d9c0 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  An SQL Statement
2d9d0 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b  .**.** After a [
2d9e0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2d9f0 6e 74 5d 20 68 61 73 20 62 65 65 6e 20 70 72 65  nt] has been pre
2da00 70 61 72 65 64 20 75 73 69 6e 67 20 65 69 74 68  pared using eith
2da10 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  er.** [sqlite3_p
2da20 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
2da30 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2da40 31 36 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20  16_v2()] or one 
2da50 6f 66 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a  of the legacy.**
2da60 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c   interfaces [sql
2da70 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
2da80 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
2da90 61 72 65 31 36 28 29 5d 2c 20 74 68 69 73 20 66  are16()], this f
2daa0 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20  unction.** must 
2dab0 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72  be called one or
2dac0 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 65   more times to e
2dad0 76 61 6c 75 61 74 65 20 74 68 65 20 73 74 61 74  valuate the stat
2dae0 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ement..**.** The
2daf0 20 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20   details of the 
2db00 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 65 20  behavior of the 
2db10 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69  sqlite3_step() i
2db20 6e 74 65 72 66 61 63 65 20 64 65 70 65 6e 64 0a  nterface depend.
2db30 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 74 68  ** on whether th
2db40 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20  e statement was 
2db50 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 74  prepared using t
2db60 68 65 20 6e 65 77 65 72 20 22 76 32 22 20 69 6e  he newer "v2" in
2db70 74 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69  terface.** [sqli
2db80 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
2db90 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70  ] and [sqlite3_p
2dba0 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f  repare16_v2()] o
2dbb0 72 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 67 61  r the older lega
2dbc0 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  cy.** interface 
2dbd0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2dbe0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
2dbf0 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2e 20 20  _prepare16()].  
2dc00 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 0a 2a  The use of the.*
2dc10 2a 20 6e 65 77 20 22 76 32 22 20 69 6e 74 65 72  * new "v2" inter
2dc20 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e  face is recommen
2dc30 64 65 64 20 66 6f 72 20 6e 65 77 20 61 70 70 6c  ded for new appl
2dc40 69 63 61 74 69 6f 6e 73 20 62 75 74 20 74 68 65  ications but the
2dc50 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72   legacy.** inter
2dc60 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e  face will contin
2dc70 75 65 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74  ue to be support
2dc80 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68  ed..**.** ^In th
2dc90 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61  e legacy interfa
2dca0 63 65 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76  ce, the return v
2dcb0 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 65 69 74  alue will be eit
2dcc0 68 65 72 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  her [SQLITE_BUSY
2dcd0 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f  ],.** [SQLITE_DO
2dce0 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57  NE], [SQLITE_ROW
2dcf0 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ], [SQLITE_ERROR
2dd00 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49  ], or [SQLITE_MI
2dd10 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20  SUSE]..** ^With 
2dd20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
2dd30 63 65 2c 20 61 6e 79 20 6f 66 20 74 68 65 20 6f  ce, any of the o
2dd40 74 68 65 72 20 5b 72 65 73 75 6c 74 20 63 6f 64  ther [result cod
2dd50 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e  es] or.** [exten
2dd60 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
2dd70 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72  ] might be retur
2dd80 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a  ned as well..**.
2dd90 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 42 55 53 59  ** ^[SQLITE_BUSY
2dda0 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  ] means that the
2ddb0 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65   database engine
2ddc0 20 77 61 73 20 75 6e 61 62 6c 65 20 74 6f 20 61   was unable to a
2ddd0 63 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 64 61  cquire the.** da
2dde0 74 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 74 20  tabase locks it 
2ddf0 6e 65 65 64 73 20 74 6f 20 64 6f 20 69 74 73 20  needs to do its 
2de00 6a 6f 62 2e 20 20 5e 49 66 20 74 68 65 20 73 74  job.  ^If the st
2de10 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f  atement is a [CO
2de20 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75  MMIT].** or occu
2de30 72 73 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e  rs outside of an
2de40 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61   explicit transa
2de50 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20  ction, then you 
2de60 63 61 6e 20 72 65 74 72 79 20 74 68 65 0a 2a 2a  can retry the.**
2de70 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20   statement.  If 
2de80 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
2de90 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20   not a [COMMIT] 
2dea0 61 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68 69  and occurs withi
2deb0 6e 20 61 6e 0a 2a 2a 20 65 78 70 6c 69 63 69 74  n an.** explicit
2dec0 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65   transaction the
2ded0 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c  n you should rol
2dee0 6c 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61  lback the transa
2def0 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20  ction before.** 
2df00 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a  continuing..**.*
2df10 2a 20 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  * ^[SQLITE_DONE]
2df20 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
2df30 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69  statement has fi
2df40 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67  nished executing
2df50 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79  .** successfully
2df60 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  .  sqlite3_step(
2df70 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20  ) should not be 
2df80 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20  called again on 
2df90 74 68 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20  this virtual.** 
2dfa0 6d 61 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20  machine without 
2dfb0 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73  first calling [s
2dfc0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
2dfd0 74 6f 20 72 65 73 65 74 20 74 68 65 20 76 69 72  to reset the vir
2dfe0 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20  tual.** machine 
2dff0 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74  back to its init
2e000 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a  ial state..**.**
2e010 20 5e 49 66 20 74 68 65 20 53 51 4c 20 73 74 61   ^If the SQL sta
2e020 74 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 65  tement being exe
2e030 63 75 74 65 64 20 72 65 74 75 72 6e 73 20 61 6e  cuted returns an
2e040 79 20 64 61 74 61 2c 20 74 68 65 6e 20 5b 53 51  y data, then [SQ
2e050 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20  LITE_ROW].** is 
2e060 72 65 74 75 72 6e 65 64 20 65 61 63 68 20 74 69  returned each ti
2e070 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 20  me a new row of 
2e080 64 61 74 61 20 69 73 20 72 65 61 64 79 20 66 6f  data is ready fo
2e090 72 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79 20  r processing by 
2e0a0 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54  the.** caller. T
2e0b0 68 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65  he values may be
2e0c0 20 61 63 63 65 73 73 65 64 20 75 73 69 6e 67 20   accessed using 
2e0d0 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65  the [column acce
2e0e0 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a  ss functions]..*
2e0f0 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  * sqlite3_step()
2e100 20 69 73 20 63 61 6c 6c 65 64 20 61 67 61 69 6e   is called again
2e110 20 74 6f 20 72 65 74 72 69 65 76 65 20 74 68 65   to retrieve the
2e120 20 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 61 74   next row of dat
2e130 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54  a..**.** ^[SQLIT
2e140 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74  E_ERROR] means t
2e150 68 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 65  hat a run-time e
2e160 72 72 6f 72 20 28 73 75 63 68 20 61 73 20 61 20  rror (such as a 
2e170 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69  constraint.** vi
2e180 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 63  olation) has occ
2e190 75 72 72 65 64 2e 20 20 73 71 6c 69 74 65 33 5f  urred.  sqlite3_
2e1a0 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f  step() should no
2e1b0 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69  t be called agai
2e1c0 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20  n on.** the VM. 
2e1d0 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  More information
2e1e0 20 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 62 79   may be found by
2e1f0 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
2e200 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20  3_errmsg()]..** 
2e210 5e 57 69 74 68 20 74 68 65 20 6c 65 67 61 63 79  ^With the legacy
2e220 20 69 6e 74 65 72 66 61 63 65 2c 20 61 20 6d 6f   interface, a mo
2e230 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f  re specific erro
2e240 72 20 63 6f 64 65 20 28 66 6f 72 20 65 78 61 6d  r code (for exam
2e250 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ple,.** [SQLITE_
2e260 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c  INTERRUPT], [SQL
2e270 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51  ITE_SCHEMA], [SQ
2e280 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61  LITE_CORRUPT], a
2e290 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20  nd so forth).** 
2e2a0 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20  can be obtained 
2e2b0 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  by calling [sqli
2e2c0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20  te3_reset()] on 
2e2d0 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
2e2e0 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e 49   statement].  ^I
2e2f0 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  n the "v2" inter
2e300 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72  face,.** the mor
2e310 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72  e specific error
2e320 20 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65   code is returne
2e330 64 20 64 69 72 65 63 74 6c 79 20 62 79 20 73 71  d directly by sq
2e340 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a  lite3_step()..**
2e350 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  .** [SQLITE_MISU
2e360 53 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74  SE] means that t
2e370 68 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  he this routine 
2e380 77 61 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70  was called inapp
2e390 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50  ropriately..** P
2e3a0 65 72 68 61 70 73 20 69 74 20 77 61 73 20 63 61  erhaps it was ca
2e3b0 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65 70 61  lled on a [prepa
2e3c0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74  red statement] t
2e3d0 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61  hat has.** alrea
2e3e0 64 79 20 62 65 65 6e 20 5b 73 71 6c 69 74 65 33  dy been [sqlite3
2e3f0 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61  _finalize | fina
2e400 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65  lized] or on one
2e410 20 74 68 61 74 20 68 61 64 0a 2a 2a 20 70 72 65   that had.** pre
2e420 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64  viously returned
2e430 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
2e440 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  or [SQLITE_DONE]
2e450 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a  .  Or it could.*
2e460 2a 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68  * be the case th
2e470 61 74 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  at the same data
2e480 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
2e490 69 73 20 62 65 69 6e 67 20 75 73 65 64 20 62 79  is being used by
2e4a0 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20   two or.** more 
2e4b0 74 68 72 65 61 64 73 20 61 74 20 74 68 65 20 73  threads at the s
2e4c0 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69  ame moment in ti
2e4d0 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c  me..**.** For al
2e4e0 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  l versions of SQ
2e4f0 4c 69 74 65 20 75 70 20 74 6f 20 61 6e 64 20 69  Lite up to and i
2e500 6e 63 6c 75 64 69 6e 67 20 33 2e 36 2e 32 33 2e  ncluding 3.6.23.
2e510 31 2c 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  1, a call to.** 
2e520 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2e530 5d 20 77 61 73 20 72 65 71 75 69 72 65 64 20 61  ] was required a
2e540 66 74 65 72 20 73 71 6c 69 74 65 33 5f 73 74 65  fter sqlite3_ste
2e550 70 28 29 20 72 65 74 75 72 6e 65 64 20 61 6e 79  p() returned any
2e560 74 68 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 74  thing.** other t
2e570 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  han [SQLITE_ROW]
2e580 20 62 65 66 6f 72 65 20 61 6e 79 20 73 75 62 73   before any subs
2e590 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f  equent invocatio
2e5a0 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  n of.** sqlite3_
2e5b0 73 74 65 70 28 29 2e 20 20 46 61 69 6c 75 72 65  step().  Failure
2e5c0 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 70 72   to reset the pr
2e5d0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2e5e0 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69   using .** [sqli
2e5f0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77 6f 75  te3_reset()] wou
2e600 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61 6e 20  ld result in an 
2e610 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20  [SQLITE_MISUSE] 
2e620 72 65 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20 73  return from.** s
2e630 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20  qlite3_step().  
2e640 42 75 74 20 61 66 74 65 72 20 76 65 72 73 69 6f  But after versio
2e650 6e 20 33 2e 36 2e 32 33 2e 31 2c 20 73 71 6c 69  n 3.6.23.1, sqli
2e660 74 65 33 5f 73 74 65 70 28 29 20 62 65 67 61 6e  te3_step() began
2e670 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c  .** calling [sql
2e680 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 61 75  ite3_reset()] au
2e690 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 20 74  tomatically in t
2e6a0 68 69 73 20 63 69 72 63 75 6d 73 74 61 6e 63 65  his circumstance
2e6b0 20 72 61 74 68 65 72 0a 2a 2a 20 74 68 61 6e 20   rather.** than 
2e6c0 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54  returning [SQLIT
2e6d0 45 5f 4d 49 53 55 53 45 5d 2e 20 20 54 68 69 73  E_MISUSE].  This
2e6e0 20 69 73 20 6e 6f 74 20 63 6f 6e 73 69 64 65 72   is not consider
2e6f0 65 64 20 61 20 63 6f 6d 70 61 74 69 62 69 6c 69  ed a compatibili
2e700 74 79 0a 2a 2a 20 62 72 65 61 6b 20 62 65 63 61  ty.** break beca
2e710 75 73 65 20 61 6e 79 20 61 70 70 6c 69 63 61 74  use any applicat
2e720 69 6f 6e 20 74 68 61 74 20 65 76 65 72 20 72 65  ion that ever re
2e730 63 65 69 76 65 73 20 61 6e 20 53 51 4c 49 54 45  ceives an SQLITE
2e740 5f 4d 49 53 55 53 45 20 65 72 72 6f 72 0a 2a 2a  _MISUSE error.**
2e750 20 69 73 20 62 72 6f 6b 65 6e 20 62 79 20 64 65   is broken by de
2e760 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 65 20 5b  finition.  The [
2e770 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f  SQLITE_OMIT_AUTO
2e780 52 45 53 45 54 5d 20 63 6f 6d 70 69 6c 65 2d 74  RESET] compile-t
2e790 69 6d 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61  ime option.** ca
2e7a0 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 73  n be used to res
2e7b0 74 6f 72 65 20 74 68 65 20 6c 65 67 61 63 79 20  tore the legacy 
2e7c0 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20  behavior..**.** 
2e7d0 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66 61  <b>Goofy Interfa
2e7e0 63 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e  ce Alert:</b> In
2e7f0 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65   the legacy inte
2e800 72 66 61 63 65 2c 20 74 68 65 20 73 71 6c 69 74  rface, the sqlit
2e810 65 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50 49  e3_step().** API
2e820 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20   always returns 
2e830 61 20 67 65 6e 65 72 69 63 20 65 72 72 6f 72 20  a generic error 
2e840 63 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52  code, [SQLITE_ER
2e850 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20  ROR], following 
2e860 61 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68  any.** error oth
2e870 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
2e880 42 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54  BUSY] and [SQLIT
2e890 45 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75 20  E_MISUSE].  You 
2e8a0 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71  must call.** [sq
2e8b0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
2e8c0 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  r [sqlite3_final
2e8d0 69 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65 72 20  ize()] in order 
2e8e0 74 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74  to find one of t
2e8f0 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 5b  he.** specific [
2e900 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 74 68 61  error codes] tha
2e910 74 20 62 65 74 74 65 72 20 64 65 73 63 72 69 62  t better describ
2e920 65 73 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a  es the error..**
2e930 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 20 74   We admit that t
2e940 68 69 73 20 69 73 20 61 20 67 6f 6f 66 79 20 64  his is a goofy d
2e950 65 73 69 67 6e 2e 20 20 54 68 65 20 70 72 6f 62  esign.  The prob
2e960 6c 65 6d 20 68 61 73 20 62 65 65 6e 20 66 69 78  lem has been fix
2e970 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 22  ed.** with the "
2e980 76 32 22 20 69 6e 74 65 72 66 61 63 65 2e 20 20  v2" interface.  
2e990 49 66 20 79 6f 75 20 70 72 65 70 61 72 65 20 61  If you prepare a
2e9a0 6c 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c 20 73  ll of your SQL s
2e9b0 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69  tatements.** usi
2e9c0 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74  ng either [sqlit
2e9d0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
2e9e0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
2e9f0 70 61 72 65 31 36 5f 76 32 28 29 5d 20 69 6e 73  pare16_v2()] ins
2ea00 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c  tead.** of the l
2ea10 65 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 70  egacy [sqlite3_p
2ea20 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73  repare()] and [s
2ea30 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2ea40 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 2c 0a  ()] interfaces,.
2ea50 2a 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f 72 65  ** then the more
2ea60 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72   specific [error
2ea70 20 63 6f 64 65 73 5d 20 61 72 65 20 72 65 74 75   codes] are retu
2ea80 72 6e 65 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a  rned directly.**
2ea90 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70   by sqlite3_step
2eaa0 28 29 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20  ().  The use of 
2eab0 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
2eac0 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  ce is recommende
2ead0 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  d..*/.SQLITE_API
2eae0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 65   int sqlite3_ste
2eaf0 70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  p(sqlite3_stmt*)
2eb00 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2eb10 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  F: Number of col
2eb20 75 6d 6e 73 20 69 6e 20 61 20 72 65 73 75 6c 74  umns in a result
2eb30 20 73 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20   set.**.** ^The 
2eb40 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
2eb50 6e 74 28 50 29 20 69 6e 74 65 72 66 61 63 65 20  nt(P) interface 
2eb60 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
2eb70 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
2eb80 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20   the.** current 
2eb90 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c  row of the resul
2eba0 74 20 73 65 74 20 6f 66 20 5b 70 72 65 70 61 72  t set of [prepar
2ebb0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e  ed statement] P.
2ebc0 0a 2a 2a 20 5e 49 66 20 70 72 65 70 61 72 65 64  .** ^If prepared
2ebd0 20 73 74 61 74 65 6d 65 6e 74 20 50 20 64 6f 65   statement P doe
2ebe0 73 20 6e 6f 74 20 68 61 76 65 20 72 65 73 75 6c  s not have resul
2ebf0 74 73 20 72 65 61 64 79 20 74 6f 20 72 65 74 75  ts ready to retu
2ec00 72 6e 0a 2a 2a 20 28 76 69 61 20 63 61 6c 6c 73  rn.** (via calls
2ec10 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
2ec20 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20 73 71  _column_int | sq
2ec30 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 28 29  lite3_column_*()
2ec40 5d 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63  ] of.** interfac
2ec50 65 73 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33  es) then sqlite3
2ec60 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72  _data_count(P) r
2ec70 65 74 75 72 6e 73 20 30 2e 0a 2a 2a 20 5e 54 68  eturns 0..** ^Th
2ec80 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63  e sqlite3_data_c
2ec90 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20  ount(P) routine 
2eca0 61 6c 73 6f 20 72 65 74 75 72 6e 73 20 30 20 69  also returns 0 i
2ecb0 66 20 50 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  f P is a NULL po
2ecc0 69 6e 74 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 73  inter..** ^The s
2ecd0 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
2ece0 74 28 50 29 20 72 6f 75 74 69 6e 65 20 72 65 74  t(P) routine ret
2ecf0 75 72 6e 73 20 30 20 69 66 20 74 68 65 20 70 72  urns 0 if the pr
2ed00 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 0a 2a  evious call to.*
2ed10 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 5d  * [sqlite3_step]
2ed20 28 50 29 20 72 65 74 75 72 6e 65 64 20 5b 53 51  (P) returned [SQ
2ed30 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 5e 54 68  LITE_DONE].  ^Th
2ed40 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63  e sqlite3_data_c
2ed50 6f 75 6e 74 28 50 29 0a 2a 2a 20 77 69 6c 6c 20  ount(P).** will 
2ed60 72 65 74 75 72 6e 20 6e 6f 6e 2d 7a 65 72 6f 20  return non-zero 
2ed70 69 66 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c  if previous call
2ed80 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
2ed90 70 5d 28 50 29 20 72 65 74 75 72 6e 65 64 0a 2a  p](P) returned.*
2eda0 2a 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20  * [SQLITE_ROW], 
2edb0 65 78 63 65 70 74 20 69 6e 20 74 68 65 20 63 61  except in the ca
2edc0 73 65 20 6f 66 20 74 68 65 20 5b 50 52 41 47 4d  se of the [PRAGM
2edd0 41 20 69 6e 63 72 65 6d 65 6e 74 61 6c 5f 76 61  A incremental_va
2ede0 63 75 75 6d 5d 0a 2a 2a 20 77 68 65 72 65 20 69  cuum].** where i
2edf0 74 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73  t always returns
2ee00 20 7a 65 72 6f 20 73 69 6e 63 65 20 65 61 63 68   zero since each
2ee10 20 73 74 65 70 20 6f 66 20 74 68 61 74 20 6d 75   step of that mu
2ee20 6c 74 69 2d 73 74 65 70 0a 2a 2a 20 70 72 61 67  lti-step.** prag
2ee30 6d 61 20 72 65 74 75 72 6e 73 20 30 20 63 6f 6c  ma returns 0 col
2ee40 75 6d 6e 73 20 6f 66 20 64 61 74 61 2e 0a 2a 2a  umns of data..**
2ee50 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
2ee60 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f  qlite3_column_co
2ee70 75 6e 74 28 29 5d 0a 2a 2f 0a 53 51 4c 49 54 45  unt()].*/.SQLITE
2ee80 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
2ee90 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69  _data_count(sqli
2eea0 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
2eeb0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2eec0 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44  F: Fundamental D
2eed0 61 74 61 74 79 70 65 73 0a 2a 2a 20 4b 45 59 57  atatypes.** KEYW
2eee0 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 54 45 58  ORDS: SQLITE_TEX
2eef0 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72 79 20  T.**.** ^(Every 
2ef00 76 61 6c 75 65 20 69 6e 20 53 51 4c 69 74 65 20  value in SQLite 
2ef10 68 61 73 20 6f 6e 65 20 6f 66 20 66 69 76 65 20  has one of five 
2ef20 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74 61  fundamental data
2ef30 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  types:.**.** <ul
2ef40 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74  >.** <li> 64-bit
2ef50 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a   signed integer.
2ef60 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49  ** <li> 64-bit I
2ef70 45 45 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  EEE floating poi
2ef80 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69  nt number.** <li
2ef90 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e  > string.** <li>
2efa0 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55   BLOB.** <li> NU
2efb0 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a  LL.** </ul>)^.**
2efc0 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
2efd0 6e 74 73 20 61 72 65 20 63 6f 64 65 73 20 66 6f  nts are codes fo
2efe0 72 20 65 61 63 68 20 6f 66 20 74 68 6f 73 65 20  r each of those 
2eff0 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74  types..**.** Not
2f000 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 49 54  e that the SQLIT
2f010 45 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e 74 20  E_TEXT constant 
2f020 77 61 73 20 61 6c 73 6f 20 75 73 65 64 20 69 6e  was also used in
2f030 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
2f040 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c  2.** for a compl
2f050 65 74 65 6c 79 20 64 69 66 66 65 72 65 6e 74 20  etely different 
2f060 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61  meaning.  Softwa
2f070 72 65 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67  re that links ag
2f080 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51  ainst both.** SQ
2f090 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 20 61  Lite version 2 a
2f0a0 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  nd SQLite versio
2f0b0 6e 20 33 20 73 68 6f 75 6c 64 20 75 73 65 20 53  n 3 should use S
2f0c0 51 4c 49 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74  QLITE3_TEXT, not
2f0d0 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58 54 2e  .** SQLITE_TEXT.
2f0e0 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
2f0f0 54 45 5f 49 4e 54 45 47 45 52 20 20 31 0a 23 64  TE_INTEGER  1.#d
2f100 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f  efine SQLITE_FLO
2f110 41 54 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20  AT    2.#define 
2f120 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20 20  SQLITE_BLOB     
2f130 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
2f140 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69 66 64  _NULL     5.#ifd
2f150 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23  ef SQLITE_TEXT.#
2f160 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 54 45   undef SQLITE_TE
2f170 58 54 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e  XT.#else.# defin
2f180 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 20 20  e SQLITE_TEXT   
2f190 20 20 33 0a 23 65 6e 64 69 66 0a 23 64 65 66 69    3.#endif.#defi
2f1a0 6e 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 20  ne SQLITE3_TEXT 
2f1b0 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50      3../*.** CAP
2f1c0 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20 56 61  I3REF: Result Va
2f1d0 6c 75 65 73 20 46 72 6f 6d 20 41 20 51 75 65 72  lues From A Quer
2f1e0 79 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  y.** KEYWORDS: {
2f1f0 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75  column access fu
2f200 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54  nctions}.**.** T
2f210 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 66 6f  hese routines fo
2f220 72 6d 20 74 68 65 20 22 72 65 73 75 6c 74 20 73  rm the "result s
2f230 65 74 22 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  et" interface..*
2f240 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
2f250 69 6e 65 73 20 72 65 74 75 72 6e 20 69 6e 66 6f  ines return info
2f260 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 61 20  rmation about a 
2f270 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66  single column of
2f280 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20   the current.** 
2f290 72 65 73 75 6c 74 20 72 6f 77 20 6f 66 20 61 20  result row of a 
2f2a0 71 75 65 72 79 2e 20 20 5e 49 6e 20 65 76 65 72  query.  ^In ever
2f2b0 79 20 63 61 73 65 20 74 68 65 20 66 69 72 73 74  y case the first
2f2c0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70   argument is a p
2f2d0 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65  ointer.** to the
2f2e0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2f2f0 6d 65 6e 74 5d 20 74 68 61 74 20 69 73 20 62 65  ment] that is be
2f300 69 6e 67 20 65 76 61 6c 75 61 74 65 64 20 28 74  ing evaluated (t
2f310 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74  he [sqlite3_stmt
2f320 2a 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 72  *].** that was r
2f330 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71  eturned from [sq
2f340 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
2f350 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74  ()] or one of it
2f360 73 20 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20 61  s variants).** a
2f370 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  nd the second ar
2f380 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e  gument is the in
2f390 64 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d  dex of the colum
2f3a0 6e 20 66 6f 72 20 77 68 69 63 68 20 69 6e 66 6f  n for which info
2f3b0 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c  rmation.** shoul
2f3c0 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 5e  d be returned. ^
2f3d0 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c  The leftmost col
2f3e0 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c  umn of the resul
2f3f0 74 20 73 65 74 20 68 61 73 20 74 68 65 20 69 6e  t set has the in
2f400 64 65 78 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 6e  dex 0..** ^The n
2f410 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
2f420 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 63   in the result c
2f430 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64  an be determined
2f440 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
2f450 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28  e3_column_count(
2f460 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  )]..**.** If the
2f470 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64   SQL statement d
2f480 6f 65 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c  oes not currentl
2f490 79 20 70 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c  y point to a val
2f4a0 69 64 20 72 6f 77 2c 20 6f 72 20 69 66 20 74 68  id row, or if th
2f4b0 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 65  e.** column inde
2f4c0 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  x is out of rang
2f4d0 65 2c 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  e, the result is
2f4e0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54   undefined..** T
2f4f0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 61  hese routines ma
2f500 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64  y only be called
2f510 20 77 68 65 6e 20 74 68 65 20 6d 6f 73 74 20 72   when the most r
2f520 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a  ecent call to.**
2f530 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2f540 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 20 5b  ] has returned [
2f550 53 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20  SQLITE_ROW] and 
2f560 6e 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69  neither.** [sqli
2f570 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72  te3_reset()] nor
2f580 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
2f590 7a 65 28 29 5d 20 68 61 76 65 20 62 65 65 6e 20  ze()] have been 
2f5a0 63 61 6c 6c 65 64 20 73 75 62 73 65 71 75 65 6e  called subsequen
2f5b0 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f  tly..** If any o
2f5c0 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
2f5d0 20 61 72 65 20 63 61 6c 6c 65 64 20 61 66 74 65   are called afte
2f5e0 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  r [sqlite3_reset
2f5f0 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
2f600 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f  e3_finalize()] o
2f610 72 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33  r after [sqlite3
2f620 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74  _step()] has ret
2f630 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69  urned.** somethi
2f640 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  ng other than [S
2f650 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20  QLITE_ROW], the 
2f660 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
2f670 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71  fined..** If [sq
2f680 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72  lite3_step()] or
2f690 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2f6a0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66  )] or [sqlite3_f
2f6b0 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72  inalize()].** ar
2f6c0 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20  e called from a 
2f6d0 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64  different thread
2f6e0 20 77 68 69 6c 65 20 61 6e 79 20 6f 66 20 74 68   while any of th
2f6f0 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20  ese routines.** 
2f700 61 72 65 20 70 65 6e 64 69 6e 67 2c 20 74 68 65  are pending, the
2f710 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  n the results ar
2f720 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  e undefined..**.
2f730 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2f740 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f  column_type() ro
2f750 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
2f760 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54  e.** [SQLITE_INT
2f770 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 20  EGER | datatype 
2f780 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 69 6e  code] for the in
2f790 69 74 69 61 6c 20 64 61 74 61 20 74 79 70 65 0a  itial data type.
2f7a0 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  ** of the result
2f7b0 20 63 6f 6c 75 6d 6e 2e 20 20 5e 54 68 65 20 72   column.  ^The r
2f7c0 65 74 75 72 6e 65 64 20 76 61 6c 75 65 20 69 73  eturned value is
2f7d0 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f   one of [SQLITE_
2f7e0 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51  INTEGER],.** [SQ
2f7f0 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51  LITE_FLOAT], [SQ
2f800 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c  LITE_TEXT], [SQL
2f810 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53  ITE_BLOB], or [S
2f820 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68  QLITE_NULL].  Th
2f830 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72  e value.** retur
2f840 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  ned by sqlite3_c
2f850 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20  olumn_type() is 
2f860 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20  only meaningful 
2f870 69 66 20 6e 6f 20 74 79 70 65 0a 2a 2a 20 63 6f  if no type.** co
2f880 6e 76 65 72 73 69 6f 6e 73 20 68 61 76 65 20 6f  nversions have o
2f890 63 63 75 72 72 65 64 20 61 73 20 64 65 73 63 72  ccurred as descr
2f8a0 69 62 65 64 20 62 65 6c 6f 77 2e 20 20 41 66 74  ibed below.  Aft
2f8b0 65 72 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72  er a type conver
2f8c0 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76 61 6c  sion,.** the val
2f8d0 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ue returned by s
2f8e0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
2f8f0 70 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65  pe() is undefine
2f900 64 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20 76 65  d.  Future.** ve
2f910 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
2f920 20 6d 61 79 20 63 68 61 6e 67 65 20 74 68 65 20   may change the 
2f930 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69  behavior of sqli
2f940 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
2f950 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  ).** following a
2f960 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   type conversion
2f970 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
2f980 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42  result is a BLOB
2f990 20 6f 72 20 55 54 46 2d 38 20 73 74 72 69 6e 67   or UTF-8 string
2f9a0 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65   then the sqlite
2f9b0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
2f9c0 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75  .** routine retu
2f9d0 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
2f9e0 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20  f bytes in that 
2f9f0 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a  BLOB or string..
2fa00 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
2fa10 74 20 69 73 20 61 20 55 54 46 2d 31 36 20 73 74  t is a UTF-16 st
2fa20 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74  ring, then sqlit
2fa30 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
2fa40 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68  ) converts.** th
2fa50 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d  e string to UTF-
2fa60 38 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72  8 and then retur
2fa70 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
2fa80 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74   bytes..** ^If t
2fa90 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e  he result is a n
2faa0 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68 65  umeric value the
2fab0 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  n sqlite3_column
2fac0 5f 62 79 74 65 73 28 29 20 75 73 65 73 0a 2a 2a  _bytes() uses.**
2fad0 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e   [sqlite3_snprin
2fae0 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74  tf()] to convert
2faf0 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61   that value to a
2fb00 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 61 6e   UTF-8 string an
2fb10 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65  d returns.** the
2fb20 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
2fb30 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e   in that string.
2fb40 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
2fb50 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  lt is NULL, then
2fb60 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2fb70 62 79 74 65 73 28 29 20 72 65 74 75 72 6e 73 20  bytes() returns 
2fb80 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  zero..**.** ^If 
2fb90 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
2fba0 42 4c 4f 42 20 6f 72 20 55 54 46 2d 31 36 20 73  BLOB or UTF-16 s
2fbb0 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73  tring then the s
2fbc0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2fbd0 74 65 73 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69  tes16().** routi
2fbe0 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ne returns the n
2fbf0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
2fc00 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73  n that BLOB or s
2fc10 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68  tring..** ^If th
2fc20 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 55 54  e result is a UT
2fc30 46 2d 38 20 73 74 72 69 6e 67 2c 20 74 68 65 6e  F-8 string, then
2fc40 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2fc50 62 79 74 65 73 31 36 28 29 20 63 6f 6e 76 65 72  bytes16() conver
2fc60 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67  ts.** the string
2fc70 20 74 6f 20 55 54 46 2d 31 36 20 61 6e 64 20 74   to UTF-16 and t
2fc80 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  hen returns the 
2fc90 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e  number of bytes.
2fca0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
2fcb0 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20  lt is a numeric 
2fcc0 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74  value then sqlit
2fcd0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
2fce0 36 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c  6() uses.** [sql
2fcf0 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d  ite3_snprintf()]
2fd00 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74   to convert that
2fd10 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d   value to a UTF-
2fd20 31 36 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65  16 string and re
2fd30 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d  turns.** the num
2fd40 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
2fd50 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20  that string..** 
2fd60 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
2fd70 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c  s NULL, then sql
2fd80 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2fd90 73 31 36 28 29 20 72 65 74 75 72 6e 73 20 7a 65  s16() returns ze
2fda0 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 76  ro..**.** ^The v
2fdb0 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62  alues returned b
2fdc0 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  y [sqlite3_colum
2fdd0 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 20 0a  n_bytes()] and .
2fde0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
2fdf0 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20 64 6f  mn_bytes16()] do
2fe00 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74 68 65   not include the
2fe10 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
2fe20 73 20 61 74 20 74 68 65 20 65 6e 64 0a 2a 2a 20  s at the end.** 
2fe30 6f 66 20 74 68 65 20 73 74 72 69 6e 67 2e 20 20  of the string.  
2fe40 5e 46 6f 72 20 63 6c 61 72 69 74 79 3a 20 74 68  ^For clarity: th
2fe50 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65  e values returne
2fe60 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  d by.** [sqlite3
2fe70 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d  _column_bytes()]
2fe80 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f   and [sqlite3_co
2fe90 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20  lumn_bytes16()] 
2fea0 61 72 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  are the number o
2feb0 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20 74 68  f.** bytes in th
2fec0 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74 68  e string, not th
2fed0 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72  e number of char
2fee0 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53  acters..**.** ^S
2fef0 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20  trings returned 
2ff00 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
2ff10 6e 5f 74 65 78 74 28 29 20 61 6e 64 20 73 71 6c  n_text() and sql
2ff20 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2ff30 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d  16(),.** even em
2ff40 70 74 79 20 73 74 72 69 6e 67 73 2c 20 61 72 65  pty strings, are
2ff50 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72   always zero-ter
2ff60 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 72  minated.  ^The r
2ff70 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 66  eturn.** value f
2ff80 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  rom sqlite3_colu
2ff90 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 20 61 20  mn_blob() for a 
2ffa0 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42  zero-length BLOB
2ffb0 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
2ffc0 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f  er..**.** ^The o
2ffd0 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62  bject returned b
2ffe0 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  y [sqlite3_colum
2fff0 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 61 6e  n_value()] is an
30000 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64  .** [unprotected
30010 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
30020 6f 62 6a 65 63 74 2e 20 20 41 6e 20 75 6e 70 72  object.  An unpr
30030 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
30040 76 61 6c 75 65 20 6f 62 6a 65 63 74 0a 2a 2a 20  value object.** 
30050 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64  may only be used
30060 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 62   with [sqlite3_b
30070 69 6e 64 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64  ind_value()] and
30080 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
30090 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66  _value()]..** If
300a0 20 74 68 65 20 5b 75 6e 70 72 6f 74 65 63 74 65   the [unprotecte
300b0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
300c0 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64   object returned
300d0 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   by.** [sqlite3_
300e0 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20  column_value()] 
300f0 69 73 20 75 73 65 64 20 69 6e 20 61 6e 79 20 6f  is used in any o
30100 74 68 65 72 20 77 61 79 2c 20 69 6e 63 6c 75 64  ther way, includ
30110 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20  ing calls.** to 
30120 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73  routines like [s
30130 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74  qlite3_value_int
30140 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61  ()], [sqlite3_va
30150 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20  lue_text()],.** 
30160 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  or [sqlite3_valu
30170 65 5f 62 79 74 65 73 28 29 5d 2c 20 74 68 65 6e  e_bytes()], then
30180 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
30190 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
301a0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
301b0 20 61 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76   attempt to conv
301c0 65 72 74 20 74 68 65 20 76 61 6c 75 65 20 77 68  ert the value wh
301d0 65 72 65 20 61 70 70 72 6f 70 72 69 61 74 65 2e  ere appropriate.
301e0 20 20 5e 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c    ^For.** exampl
301f0 65 2c 20 69 66 20 74 68 65 20 69 6e 74 65 72 6e  e, if the intern
30200 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f  al representatio
30210 6e 20 69 73 20 46 4c 4f 41 54 20 61 6e 64 20 61  n is FLOAT and a
30220 20 74 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20   text result.** 
30230 69 73 20 72 65 71 75 65 73 74 65 64 2c 20 5b 73  is requested, [s
30240 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
30250 29 5d 20 69 73 20 75 73 65 64 20 69 6e 74 65 72  )] is used inter
30260 6e 61 6c 6c 79 20 74 6f 20 70 65 72 66 6f 72 6d  nally to perform
30270 20 74 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69   the.** conversi
30280 6f 6e 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  on automatically
30290 2e 20 20 5e 28 54 68 65 20 66 6f 6c 6c 6f 77 69  .  ^(The followi
302a0 6e 67 20 74 61 62 6c 65 20 64 65 74 61 69 6c 73  ng table details
302b0 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73   the conversions
302c0 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 61 70 70  .** that are app
302d0 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lied:.**.** <blo
302e0 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62  ckquote>.** <tab
302f0 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a  le border="1">.*
30300 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72  * <tr><th> Inter
30310 6e 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e  nal<br>Type <th>
30320 20 52 65 71 75 65 73 74 65 64 3c 62 72 3e 54 79   Requested<br>Ty
30330 70 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73  pe <th>  Convers
30340 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74  ion.**.** <tr><t
30350 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e  d>  NULL    <td>
30360 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20   INTEGER   <td> 
30370 52 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c  Result is 0.** <
30380 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20  tr><td>  NULL   
30390 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20   <td>  FLOAT    
303a0 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30  <td> Result is 0
303b0 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  .0.** <tr><td>  
303c0 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 54  NULL    <td>   T
303d0 45 58 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75  EXT    <td> Resu
303e0 6c 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  lt is a NULL poi
303f0 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  nter.** <tr><td>
30400 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20    NULL    <td>  
30410 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52 65   BLOB    <td> Re
30420 73 75 6c 74 20 69 73 20 61 20 4e 55 4c 4c 20 70  sult is a NULL p
30430 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74  ointer.** <tr><t
30440 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e  d> INTEGER  <td>
30450 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20    FLOAT    <td> 
30460 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e 74  Convert from int
30470 65 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a  eger to float.**
30480 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45   <tr><td> INTEGE
30490 52 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20  R  <td>   TEXT  
304a0 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e    <td> ASCII ren
304b0 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 69 6e  dering of the in
304c0 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64  teger.** <tr><td
304d0 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20  > INTEGER  <td> 
304e0 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53    BLOB    <td> S
304f0 61 6d 65 20 61 73 20 49 4e 54 45 47 45 52 2d 3e  ame as INTEGER->
30500 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  TEXT.** <tr><td>
30510 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49    FLOAT   <td> I
30520 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43  NTEGER   <td> [C
30530 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a  AST] to INTEGER.
30540 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f  ** <tr><td>  FLO
30550 41 54 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54  AT   <td>   TEXT
30560 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72      <td> ASCII r
30570 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20  endering of the 
30580 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64  float.** <tr><td
30590 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20  >  FLOAT   <td> 
305a0 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 5b    BLOB    <td> [
305b0 43 41 53 54 5d 20 74 6f 20 42 4c 4f 42 0a 2a 2a  CAST] to BLOB.**
305c0 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20   <tr><td>  TEXT 
305d0 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20     <td> INTEGER 
305e0 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f    <td> [CAST] to
305f0 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e   INTEGER.** <tr>
30600 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74  <td>  TEXT    <t
30610 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64  d>  FLOAT    <td
30620 3e 20 5b 43 41 53 54 5d 20 74 6f 20 52 45 41 4c  > [CAST] to REAL
30630 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45  .** <tr><td>  TE
30640 58 54 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f  XT    <td>   BLO
30650 42 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61  B    <td> No cha
30660 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  nge.** <tr><td> 
30670 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e   BLOB    <td> IN
30680 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 41  TEGER   <td> [CA
30690 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a  ST] to INTEGER.*
306a0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42  * <tr><td>  BLOB
306b0 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20      <td>  FLOAT 
306c0 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74     <td> [CAST] t
306d0 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74  o REAL.** <tr><t
306e0 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  d>  BLOB    <td>
306f0 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20     TEXT    <td> 
30700 41 64 64 20 61 20 7a 65 72 6f 20 74 65 72 6d 69  Add a zero termi
30710 6e 61 74 6f 72 20 69 66 20 6e 65 65 64 65 64 0a  nator if needed.
30720 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c  ** </table>.** <
30730 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a  /blockquote>)^.*
30740 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 61  *.** The table a
30750 62 6f 76 65 20 6d 61 6b 65 73 20 72 65 66 65 72  bove makes refer
30760 65 6e 63 65 20 74 6f 20 73 74 61 6e 64 61 72 64  ence to standard
30770 20 43 20 6c 69 62 72 61 72 79 20 66 75 6e 63 74   C library funct
30780 69 6f 6e 73 20 61 74 6f 69 28 29 0a 2a 2a 20 61  ions atoi().** a
30790 6e 64 20 61 74 6f 66 28 29 2e 20 20 53 51 4c 69  nd atof().  SQLi
307a0 74 65 20 64 6f 65 73 20 6e 6f 74 20 72 65 61 6c  te does not real
307b0 6c 79 20 75 73 65 20 74 68 65 73 65 20 66 75 6e  ly use these fun
307c0 63 74 69 6f 6e 73 2e 20 20 49 74 20 68 61 73 20  ctions.  It has 
307d0 69 74 73 0a 2a 2a 20 6f 77 6e 20 65 71 75 69 76  its.** own equiv
307e0 61 6c 65 6e 74 20 69 6e 74 65 72 6e 61 6c 20 72  alent internal r
307f0 6f 75 74 69 6e 65 73 2e 20 20 54 68 65 20 61 74  outines.  The at
30800 6f 69 28 29 20 61 6e 64 20 61 74 6f 66 28 29 20  oi() and atof() 
30810 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 75 73 65  names are.** use
30820 64 20 69 6e 20 74 68 65 20 74 61 62 6c 65 20 66  d in the table f
30830 6f 72 20 62 72 65 76 69 74 79 20 61 6e 64 20 62  or brevity and b
30840 65 63 61 75 73 65 20 74 68 65 79 20 61 72 65 20  ecause they are 
30850 66 61 6d 69 6c 69 61 72 20 74 6f 20 6d 6f 73 74  familiar to most
30860 0a 2a 2a 20 43 20 70 72 6f 67 72 61 6d 6d 65 72  .** C programmer
30870 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68  s..**.** Note th
30880 61 74 20 77 68 65 6e 20 74 79 70 65 20 63 6f 6e  at when type con
30890 76 65 72 73 69 6f 6e 73 20 6f 63 63 75 72 2c 20  versions occur, 
308a0 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65  pointers returne
308b0 64 20 62 79 20 70 72 69 6f 72 0a 2a 2a 20 63 61  d by prior.** ca
308c0 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  lls to sqlite3_c
308d0 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 71  olumn_blob(), sq
308e0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
308f0 74 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73  t(), and/or.** s
30900 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
30910 78 74 31 36 28 29 20 6d 61 79 20 62 65 20 69 6e  xt16() may be in
30920 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 20 54 79  validated..** Ty
30930 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 61  pe conversions a
30940 6e 64 20 70 6f 69 6e 74 65 72 20 69 6e 76 61 6c  nd pointer inval
30950 69 64 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6f  idations might o
30960 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 66  ccur.** in the f
30970 6f 6c 6c 6f 77 69 6e 67 20 63 61 73 65 73 3a 0a  ollowing cases:.
30980 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
30990 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63  i> The initial c
309a0 6f 6e 74 65 6e 74 20 69 73 20 61 20 42 4c 4f 42  ontent is a BLOB
309b0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
309c0 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 0a 2a 2a  umn_text() or.**
309d0 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f        sqlite3_co
309e0 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73  lumn_text16() is
309f0 20 63 61 6c 6c 65 64 2e 20 20 41 20 7a 65 72 6f   called.  A zero
30a00 2d 74 65 72 6d 69 6e 61 74 6f 72 20 6d 69 67 68  -terminator migh
30a10 74 0a 2a 2a 20 20 20 20 20 20 6e 65 65 64 20 74  t.**      need t
30a20 6f 20 62 65 20 61 64 64 65 64 20 74 6f 20 74 68  o be added to th
30a30 65 20 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a  e string.</li>.*
30a40 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69  * <li> The initi
30a50 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54  al content is UT
30a60 46 2d 38 20 74 65 78 74 20 61 6e 64 20 73 71 6c  F-8 text and sql
30a70 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
30a80 73 31 36 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20  s16() or.**     
30a90 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
30aa0 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c  text16() is call
30ab0 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74  ed.  The content
30ac0 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74   must be convert
30ad0 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54  ed.**      to UT
30ae0 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c  F-16.</li>.** <l
30af0 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63  i> The initial c
30b00 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 31 36  ontent is UTF-16
30b10 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65   text and sqlite
30b20 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
30b30 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69   or.**      sqli
30b40 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
30b50 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68  ) is called.  Th
30b60 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62  e content must b
30b70 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20  e converted.**  
30b80 20 20 20 20 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c      to UTF-8.</l
30b90 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  i>.** </ul>.**.*
30ba0 2a 20 5e 43 6f 6e 76 65 72 73 69 6f 6e 73 20 62  * ^Conversions b
30bb0 65 74 77 65 65 6e 20 55 54 46 2d 31 36 62 65 20  etween UTF-16be 
30bc0 61 6e 64 20 55 54 46 2d 31 36 6c 65 20 61 72 65  and UTF-16le are
30bd0 20 61 6c 77 61 79 73 20 64 6f 6e 65 20 69 6e 20   always done in 
30be0 70 6c 61 63 65 20 61 6e 64 20 64 6f 0a 2a 2a 20  place and do.** 
30bf0 6e 6f 74 20 69 6e 76 61 6c 69 64 61 74 65 20 61  not invalidate a
30c00 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 2c 20   prior pointer, 
30c10 74 68 6f 75 67 68 20 6f 66 20 63 6f 75 72 73 65  though of course
30c20 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
30c30 74 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 74 68  the buffer.** th
30c40 61 74 20 74 68 65 20 70 72 69 6f 72 20 70 6f 69  at the prior poi
30c50 6e 74 65 72 20 72 65 66 65 72 65 6e 63 65 73 20  nter references 
30c60 77 69 6c 6c 20 68 61 76 65 20 62 65 65 6e 20 6d  will have been m
30c70 6f 64 69 66 69 65 64 2e 20 20 4f 74 68 65 72 20  odified.  Other 
30c80 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76  kinds.** of conv
30c90 65 72 73 69 6f 6e 20 61 72 65 20 64 6f 6e 65 20  ersion are done 
30ca0 69 6e 20 70 6c 61 63 65 20 77 68 65 6e 20 69 74  in place when it
30cb0 20 69 73 20 70 6f 73 73 69 62 6c 65 2c 20 62 75   is possible, bu
30cc0 74 20 73 6f 6d 65 74 69 6d 65 73 20 74 68 65 79  t sometimes they
30cd0 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 70 6f 73 73  .** are not poss
30ce0 69 62 6c 65 20 61 6e 64 20 69 6e 20 74 68 6f 73  ible and in thos
30cf0 65 20 63 61 73 65 73 20 70 72 69 6f 72 20 70 6f  e cases prior po
30d00 69 6e 74 65 72 73 20 61 72 65 20 69 6e 76 61 6c  inters are inval
30d10 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  idated..**.** Th
30d20 65 20 73 61 66 65 73 74 20 61 6e 64 20 65 61 73  e safest and eas
30d30 69 65 73 74 20 74 6f 20 72 65 6d 65 6d 62 65 72  iest to remember
30d40 20 70 6f 6c 69 63 79 20 69 73 20 74 6f 20 69 6e   policy is to in
30d50 76 6f 6b 65 20 74 68 65 73 65 20 72 6f 75 74 69  voke these routi
30d60 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66  nes.** in one of
30d70 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 77   the following w
30d80 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ays:.**.** <ul>.
30d90 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f  **  <li>sqlite3_
30da0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 66 6f  column_text() fo
30db0 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65  llowed by sqlite
30dc0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
30dd0 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71  </li>.**  <li>sq
30de0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
30df0 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  b() followed by 
30e00 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
30e10 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20  ytes()</li>.**  
30e20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75  <li>sqlite3_colu
30e30 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 6f 6c 6c  mn_text16() foll
30e40 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  owed by sqlite3_
30e50 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
30e60 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  </li>.** </ul>.*
30e70 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f  *.** In other wo
30e80 72 64 73 2c 20 79 6f 75 20 73 68 6f 75 6c 64 20  rds, you should 
30e90 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c  call sqlite3_col
30ea0 75 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a 20 73  umn_text(),.** s
30eb0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
30ec0 6f 62 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33  ob(), or sqlite3
30ed0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
30ee0 20 66 69 72 73 74 20 74 6f 20 66 6f 72 63 65 20   first to force 
30ef0 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e  the result.** in
30f00 74 6f 20 74 68 65 20 64 65 73 69 72 65 64 20 66  to the desired f
30f10 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69 6e 76 6f  ormat, then invo
30f20 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ke sqlite3_colum
30f30 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20  n_bytes() or.** 
30f40 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
30f50 79 74 65 73 31 36 28 29 20 74 6f 20 66 69 6e 64  ytes16() to find
30f60 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
30f70 20 72 65 73 75 6c 74 2e 20 20 44 6f 20 6e 6f 74   result.  Do not
30f80 20 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f   mix calls.** to
30f90 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
30fa0 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65  text() or sqlite
30fb0 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20  3_column_blob() 
30fc0 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  with calls to.**
30fd0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
30fe0 62 79 74 65 73 31 36 28 29 2c 20 61 6e 64 20 64  bytes16(), and d
30ff0 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 20  o not mix calls 
31000 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  to sqlite3_colum
31010 6e 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 77 69  n_text16().** wi
31020 74 68 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  th calls to sqli
31030 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
31040 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70  ()..**.** ^The p
31050 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64  ointers returned
31060 20 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c   are valid until
31070 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69   a type conversi
31080 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a 2a 2a 20  on occurs as.** 
31090 64 65 73 63 72 69 62 65 64 20 61 62 6f 76 65 2c  described above,
310a0 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74   or until [sqlit
310b0 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73  e3_step()] or [s
310c0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
310d0 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  or.** [sqlite3_f
310e0 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 63 61  inalize()] is ca
310f0 6c 6c 65 64 2e 20 20 5e 54 68 65 20 6d 65 6d 6f  lled.  ^The memo
31100 72 79 20 73 70 61 63 65 20 75 73 65 64 20 74 6f  ry space used to
31110 20 68 6f 6c 64 20 73 74 72 69 6e 67 73 0a 2a 2a   hold strings.**
31120 20 61 6e 64 20 42 4c 4f 42 73 20 69 73 20 66 72   and BLOBs is fr
31130 65 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  eed automaticall
31140 79 2e 20 20 44 6f 20 3c 62 3e 6e 6f 74 3c 2f 62  y.  Do <b>not</b
31150 3e 20 70 61 73 73 20 74 68 65 20 70 6f 69 6e 74  > pass the point
31160 65 72 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  ers returned.** 
31170 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f  from [sqlite3_co
31180 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73  lumn_blob()], [s
31190 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
311a0 78 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f  xt()], etc. into
311b0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  .** [sqlite3_fre
311c0 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66  e()]..**.** ^(If
311d0 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
311e0 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  tion error occur
311f0 73 20 64 75 72 69 6e 67 20 74 68 65 20 65 76 61  s during the eva
31200 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a  luation of any.*
31210 2a 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  * of these routi
31220 6e 65 73 2c 20 61 20 64 65 66 61 75 6c 74 20 76  nes, a default v
31230 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65 64  alue is returned
31240 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 76  .  The default v
31250 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74 68 65  alue.** is eithe
31260 72 20 74 68 65 20 69 6e 74 65 67 65 72 20 30 2c  r the integer 0,
31270 20 74 68 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f   the floating po
31280 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20  int number 0.0, 
31290 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69  or a NULL.** poi
312a0 6e 74 65 72 2e 20 20 53 75 62 73 65 71 75 65 6e  nter.  Subsequen
312b0 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  t calls to [sqli
312c0 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 77  te3_errcode()] w
312d0 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53  ill return.** [S
312e0 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e 0a  QLITE_NOMEM].)^.
312f0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  */.SQLITE_API co
31300 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
31310 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71  3_column_blob(sq
31320 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
31330 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41   iCol);.SQLITE_A
31340 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  PI int sqlite3_c
31350 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69  olumn_bytes(sqli
31360 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
31370 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  Col);.SQLITE_API
31380 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c   int sqlite3_col
31390 75 6d 6e 5f 62 79 74 65 73 31 36 28 73 71 6c 69  umn_bytes16(sqli
313a0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
313b0 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  Col);.SQLITE_API
313c0 20 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f   double sqlite3_
313d0 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 71  column_double(sq
313e0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
313f0 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41   iCol);.SQLITE_A
31400 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  PI int sqlite3_c
31410 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65  olumn_int(sqlite
31420 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
31430 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73  l);.SQLITE_API s
31440 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
31450 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36  ite3_column_int6
31460 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  4(sqlite3_stmt*,
31470 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49   int iCol);.SQLI
31480 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 75 6e 73  TE_API const uns
31490 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69  igned char *sqli
314a0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
314b0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
314c0 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45  nt iCol);.SQLITE
314d0 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20  _API const void 
314e0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
314f0 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73  text16(sqlite3_s
31500 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
31510 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
31520 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
31530 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ype(sqlite3_stmt
31540 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51  *, int iCol);.SQ
31550 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33  LITE_API sqlite3
31560 5f 76 61 6c 75 65 20 2a 73 71 6c 69 74 65 33 5f  _value *sqlite3_
31570 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 73 71 6c  column_value(sql
31580 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
31590 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  iCol);../*.** CA
315a0 50 49 33 52 45 46 3a 20 44 65 73 74 72 6f 79 20  PI3REF: Destroy 
315b0 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
315c0 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a  ment Object.**.*
315d0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66  * ^The sqlite3_f
315e0 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63 74 69  inalize() functi
315f0 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20  on is called to 
31600 64 65 6c 65 74 65 20 61 20 5b 70 72 65 70 61 72  delete a [prepar
31610 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
31620 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72  * ^If the most r
31630 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e  ecent evaluation
31640 20 6f 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e   of the statemen
31650 74 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 6e 6f  t encountered no
31660 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 72 20 69 66   errors.** or if
31670 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
31680 73 20 6e 65 76 65 72 20 62 65 65 6e 20 65 76 61  s never been eva
31690 6c 75 61 74 65 64 2c 20 74 68 65 6e 20 73 71 6c  luated, then sql
316a0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20  ite3_finalize() 
316b0 72 65 74 75 72 6e 73 0a 2a 2a 20 53 51 4c 49 54  returns.** SQLIT
316c0 45 5f 4f 4b 2e 20 20 5e 49 66 20 74 68 65 20 6d  E_OK.  ^If the m
316d0 6f 73 74 20 72 65 63 65 6e 74 20 65 76 61 6c 75  ost recent evalu
316e0 61 74 69 6f 6e 20 6f 66 20 73 74 61 74 65 6d 65  ation of stateme
316f0 6e 74 20 53 20 66 61 69 6c 65 64 2c 20 74 68 65  nt S failed, the
31700 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 69 6e  n.** sqlite3_fin
31710 61 6c 69 7a 65 28 53 29 20 72 65 74 75 72 6e 73  alize(S) returns
31720 20 74 68 65 20 61 70 70 72 6f 70 72 69 61 74 65   the appropriate
31730 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72   [error code] or
31740 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 65 72  .** [extended er
31750 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a  ror code]..**.**
31760 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69   ^The sqlite3_fi
31770 6e 61 6c 69 7a 65 28 53 29 20 72 6f 75 74 69 6e  nalize(S) routin
31780 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20  e can be called 
31790 61 74 20 61 6e 79 20 70 6f 69 6e 74 20 64 75 72  at any point dur
317a0 69 6e 67 0a 2a 2a 20 74 68 65 20 6c 69 66 65 20  ing.** the life 
317b0 63 79 63 6c 65 20 6f 66 20 5b 70 72 65 70 61 72  cycle of [prepar
317c0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 3a  ed statement] S:
317d0 0a 2a 2a 20 62 65 66 6f 72 65 20 73 74 61 74 65  .** before state
317e0 6d 65 6e 74 20 53 20 69 73 20 65 76 65 72 20 65  ment S is ever e
317f0 76 61 6c 75 61 74 65 64 2c 20 61 66 74 65 72 0a  valuated, after.
31800 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 63  ** one or more c
31810 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
31820 5f 72 65 73 65 74 28 29 5d 2c 20 6f 72 20 61 66  _reset()], or af
31830 74 65 72 20 61 6e 79 20 63 61 6c 6c 0a 2a 2a 20  ter any call.** 
31840 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
31850 28 29 5d 20 72 65 67 61 72 64 6c 65 73 73 20 6f  ()] regardless o
31860 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
31870 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68   the statement h
31880 61 73 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20  as.** completed 
31890 65 78 65 63 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  execution..**.**
318a0 20 5e 49 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74   ^Invoking sqlit
318b0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 6f 6e  e3_finalize() on
318c0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
318d0 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f  is a harmless no
318e0 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61  -op..**.** The a
318f0 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
31900 66 69 6e 61 6c 69 7a 65 20 65 76 65 72 79 20 5b  finalize every [
31910 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
31920 6e 74 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  nt] in order to 
31930 61 76 6f 69 64 0a 2a 2a 20 72 65 73 6f 75 72 63  avoid.** resourc
31940 65 20 6c 65 61 6b 73 2e 20 20 49 74 20 69 73 20  e leaks.  It is 
31950 61 20 67 72 69 65 76 6f 75 73 20 65 72 72 6f 72  a grievous error
31960 20 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61   for the applica
31970 74 69 6f 6e 20 74 6f 20 74 72 79 20 74 6f 20 75  tion to try to u
31980 73 65 0a 2a 2a 20 61 20 70 72 65 70 61 72 65 64  se.** a prepared
31990 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72   statement after
319a0 20 69 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e   it has been fin
319b0 61 6c 69 7a 65 64 2e 20 20 41 6e 79 20 75 73 65  alized.  Any use
319c0 20 6f 66 20 61 20 70 72 65 70 61 72 65 64 0a 2a   of a prepared.*
319d0 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65  * statement afte
319e0 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 66 69  r it has been fi
319f0 6e 61 6c 69 7a 65 64 20 63 61 6e 20 72 65 73 75  nalized can resu
31a00 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20  lt in undefined 
31a10 61 6e 64 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62  and.** undesirab
31a20 6c 65 20 62 65 68 61 76 69 6f 72 20 73 75 63 68  le behavior such
31a30 20 61 73 20 73 65 67 66 61 75 6c 74 73 20 61 6e   as segfaults an
31a40 64 20 68 65 61 70 20 63 6f 72 72 75 70 74 69 6f  d heap corruptio
31a50 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  n..*/.SQLITE_API
31a60 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 66 69 6e   int sqlite3_fin
31a70 61 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f 73 74  alize(sqlite3_st
31a80 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
31a90 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73  ** CAPI3REF: Res
31aa0 65 74 20 41 20 50 72 65 70 61 72 65 64 20 53 74  et A Prepared St
31ab0 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a  atement Object.*
31ac0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
31ad0 5f 72 65 73 65 74 28 29 20 66 75 6e 63 74 69 6f  _reset() functio
31ae0 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 72  n is called to r
31af0 65 73 65 74 20 61 20 5b 70 72 65 70 61 72 65 64  eset a [prepared
31b00 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f   statement].** o
31b10 62 6a 65 63 74 20 62 61 63 6b 20 74 6f 20 69 74  bject back to it
31b20 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2c  s initial state,
31b30 20 72 65 61 64 79 20 74 6f 20 62 65 20 72 65 2d   ready to be re-
31b40 65 78 65 63 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e  executed..** ^An
31b50 79 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  y SQL statement 
31b60 76 61 72 69 61 62 6c 65 73 20 74 68 61 74 20 68  variables that h
31b70 61 64 20 76 61 6c 75 65 73 20 62 6f 75 6e 64 20  ad values bound 
31b80 74 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a  to them using.**
31b90 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69   the [sqlite3_bi
31ba0 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65  nd_blob | sqlite
31bb0 33 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20  3_bind_*() API] 
31bc0 72 65 74 61 69 6e 20 74 68 65 69 72 20 76 61 6c  retain their val
31bd0 75 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c  ues..** Use [sql
31be0 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69  ite3_clear_bindi
31bf0 6e 67 73 28 29 5d 20 74 6f 20 72 65 73 65 74 20  ngs()] to reset 
31c00 74 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a  the bindings..**
31c10 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  .** ^The [sqlite
31c20 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65  3_reset(S)] inte
31c30 72 66 61 63 65 20 72 65 73 65 74 73 20 74 68 65  rface resets the
31c40 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
31c50 6d 65 6e 74 5d 20 53 0a 2a 2a 20 62 61 63 6b 20  ment] S.** back 
31c60 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67  to the beginning
31c70 20 6f 66 20 69 74 73 20 70 72 6f 67 72 61 6d 2e   of its program.
31c80 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d  .**.** ^If the m
31c90 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20  ost recent call 
31ca0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
31cb0 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20  (S)] for the.** 
31cc0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
31cd0 65 6e 74 5d 20 53 20 72 65 74 75 72 6e 65 64 20  ent] S returned 
31ce0 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20  [SQLITE_ROW] or 
31cf0 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a  [SQLITE_DONE],.*
31d00 2a 20 6f 72 20 69 66 20 5b 73 71 6c 69 74 65 33  * or if [sqlite3
31d10 5f 73 74 65 70 28 53 29 5d 20 68 61 73 20 6e 65  _step(S)] has ne
31d20 76 65 72 20 62 65 66 6f 72 65 20 62 65 65 6e 20  ver before been 
31d30 63 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20  called on S,.** 
31d40 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65  then [sqlite3_re
31d50 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20  set(S)] returns 
31d60 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a  [SQLITE_OK]..**.
31d70 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20  ** ^If the most 
31d80 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b  recent call to [
31d90 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
31da0 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65   for the.** [pre
31db0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
31dc0 20 53 20 69 6e 64 69 63 61 74 65 64 20 61 6e 20   S indicated an 
31dd0 65 72 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b  error, then.** [
31de0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
31df0 5d 20 72 65 74 75 72 6e 73 20 61 6e 20 61 70 70  ] returns an app
31e00 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20  ropriate [error 
31e10 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  code]..**.** ^Th
31e20 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  e [sqlite3_reset
31e30 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64  (S)] interface d
31e40 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74  oes not change t
31e50 68 65 20 76 61 6c 75 65 73 0a 2a 2a 20 6f 66 20  he values.** of 
31e60 61 6e 79 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  any [sqlite3_bin
31e70 64 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d  d_blob|bindings]
31e80 20 6f 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65   on the [prepare
31e90 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a  d statement] S..
31ea0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
31eb0 74 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28  t sqlite3_reset(
31ec0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
31ed0 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
31ee0 49 33 52 45 46 3a 20 43 72 65 61 74 65 20 4f 72  I3REF: Create Or
31ef0 20 52 65 64 65 66 69 6e 65 20 53 51 4c 20 46 75   Redefine SQL Fu
31f00 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f  nctions.** KEYWO
31f10 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63  RDS: {function c
31f20 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  reation routines
31f30 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  }.** KEYWORDS: {
31f40 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
31f50 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
31f60 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  }.** KEYWORDS: {
31f70 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
31f80 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
31f90 73 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  s}.**.** ^These 
31fa0 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c 6c 65  functions (colle
31fb0 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20 61 73  ctively known as
31fc0 20 22 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74   "function creat
31fd0 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29 0a 2a  ion routines").*
31fe0 2a 20 61 72 65 20 75 73 65 64 20 74 6f 20 61 64  * are used to ad
31ff0 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  d SQL functions 
32000 6f 72 20 61 67 67 72 65 67 61 74 65 73 20 6f 72  or aggregates or
32010 20 74 6f 20 72 65 64 65 66 69 6e 65 20 74 68 65   to redefine the
32020 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20   behavior.** of 
32030 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66 75 6e  existing SQL fun
32040 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67  ctions or aggreg
32050 61 74 65 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20  ates.  The only 
32060 64 69 66 66 65 72 65 6e 63 65 73 20 62 65 74 77  differences betw
32070 65 65 6e 0a 2a 2a 20 74 68 65 73 65 20 72 6f 75  een.** these rou
32080 74 69 6e 65 73 20 61 72 65 20 74 68 65 20 74 65  tines are the te
32090 78 74 20 65 6e 63 6f 64 69 6e 67 20 65 78 70 65  xt encoding expe
320a0 63 74 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20  cted for.** the 
320b0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
320c0 20 28 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68   (the name of th
320d0 65 20 66 75 6e 63 74 69 6f 6e 20 62 65 69 6e 67  e function being
320e0 20 63 72 65 61 74 65 64 29 0a 2a 2a 20 61 6e 64   created).** and
320f0 20 74 68 65 20 70 72 65 73 65 6e 63 65 20 6f 72   the presence or
32100 20 61 62 73 65 6e 63 65 20 6f 66 20 61 20 64 65   absence of a de
32110 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63  structor callbac
32120 6b 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 70 70  k for.** the app
32130 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f  lication data po
32140 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  inter..**.** ^Th
32150 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
32160 72 20 69 73 20 74 68 65 20 5b 64 61 74 61 62 61  r is the [databa
32170 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74  se connection] t
32180 6f 20 77 68 69 63 68 20 74 68 65 20 53 51 4c 0a  o which the SQL.
32190 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74  ** function is t
321a0 6f 20 62 65 20 61 64 64 65 64 2e 20 20 5e 49 66  o be added.  ^If
321b0 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
321c0 75 73 65 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f  uses more than o
321d0 6e 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  ne database.** c
321e0 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 65 6e 20 61  onnection then a
321f0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
32200 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ed SQL functions
32210 20 6d 75 73 74 20 62 65 20 61 64 64 65 64 0a 2a   must be added.*
32220 2a 20 74 6f 20 65 61 63 68 20 64 61 74 61 62 61  * to each databa
32230 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 65  se connection se
32240 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20  parately..**.** 
32250 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61  ^The second para
32260 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d  meter is the nam
32270 65 20 6f 66 20 74 68 65 20 53 51 4c 20 66 75 6e  e of the SQL fun
32280 63 74 69 6f 6e 20 74 6f 20 62 65 20 63 72 65 61  ction to be crea
32290 74 65 64 20 6f 72 0a 2a 2a 20 72 65 64 65 66 69  ted or.** redefi
322a0 6e 65 64 2e 20 20 5e 54 68 65 20 6c 65 6e 67 74  ned.  ^The lengt
322b0 68 20 6f 66 20 74 68 65 20 6e 61 6d 65 20 69 73  h of the name is
322c0 20 6c 69 6d 69 74 65 64 20 74 6f 20 32 35 35 20   limited to 255 
322d0 62 79 74 65 73 20 69 6e 20 61 20 55 54 46 2d 38  bytes in a UTF-8
322e0 0a 2a 2a 20 72 65 70 72 65 73 65 6e 74 61 74 69  .** representati
322f0 6f 6e 2c 20 65 78 63 6c 75 73 69 76 65 20 6f 66  on, exclusive of
32300 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e   the zero-termin
32310 61 74 6f 72 2e 20 20 5e 4e 6f 74 65 20 74 68 61  ator.  ^Note tha
32320 74 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 6c 65  t the name.** le
32330 6e 67 74 68 20 6c 69 6d 69 74 20 69 73 20 69 6e  ngth limit is in
32340 20 55 54 46 2d 38 20 62 79 74 65 73 2c 20 6e 6f   UTF-8 bytes, no
32350 74 20 63 68 61 72 61 63 74 65 72 73 20 6e 6f 72  t characters nor
32360 20 55 54 46 2d 31 36 20 62 79 74 65 73 2e 20 20   UTF-16 bytes.  
32370 0a 2a 2a 20 5e 41 6e 79 20 61 74 74 65 6d 70 74  .** ^Any attempt
32380 20 74 6f 20 63 72 65 61 74 65 20 61 20 66 75 6e   to create a fun
32390 63 74 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f 6e  ction with a lon
323a0 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c  ger name.** will
323b0 20 72 65 73 75 6c 74 20 69 6e 20 5b 53 51 4c 49   result in [SQLI
323c0 54 45 5f 4d 49 53 55 53 45 5d 20 62 65 69 6e 67  TE_MISUSE] being
323d0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
323e0 20 5e 54 68 65 20 74 68 69 72 64 20 70 61 72 61   ^The third para
323f0 6d 65 74 65 72 20 28 6e 41 72 67 29 0a 2a 2a 20  meter (nArg).** 
32400 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
32410 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20   arguments that 
32420 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
32430 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65   or.** aggregate
32440 20 74 61 6b 65 73 2e 20 5e 49 66 20 74 68 69 73   takes. ^If this
32450 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 2d 31   parameter is -1
32460 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20 66  , then the SQL f
32470 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67  unction or.** ag
32480 67 72 65 67 61 74 65 20 6d 61 79 20 74 61 6b 65  gregate may take
32490 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20 61   any number of a
324a0 72 67 75 6d 65 6e 74 73 20 62 65 74 77 65 65 6e  rguments between
324b0 20 30 20 61 6e 64 20 74 68 65 20 6c 69 6d 69 74   0 and the limit
324c0 0a 2a 2a 20 73 65 74 20 62 79 20 5b 73 71 6c 69  .** set by [sqli
324d0 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49  te3_limit]([SQLI
324e0 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f  TE_LIMIT_FUNCTIO
324f0 4e 5f 41 52 47 5d 29 2e 20 20 49 66 20 74 68 65  N_ARG]).  If the
32500 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65   third.** parame
32510 74 65 72 20 69 73 20 6c 65 73 73 20 74 68 61 6e  ter is less than
32520 20 2d 31 20 6f 72 20 67 72 65 61 74 65 72 20 74   -1 or greater t
32530 68 61 6e 20 31 32 37 20 74 68 65 6e 20 74 68 65  han 127 then the
32540 20 62 65 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20   behavior is.** 
32550 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
32560 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61 72   ^The fourth par
32570 61 6d 65 74 65 72 2c 20 65 54 65 78 74 52 65 70  ameter, eTextRep
32580 2c 20 73 70 65 63 69 66 69 65 73 20 77 68 61 74  , specifies what
32590 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38  .** [SQLITE_UTF8
325a0 20 7c 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67   | text encoding
325b0 5d 20 74 68 69 73 20 53 51 4c 20 66 75 6e 63 74  ] this SQL funct
325c0 69 6f 6e 20 70 72 65 66 65 72 73 20 66 6f 72 0a  ion prefers for.
325d0 2a 2a 20 69 74 73 20 70 61 72 61 6d 65 74 65 72  ** its parameter
325e0 73 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74  s.  The applicat
325f0 69 6f 6e 20 73 68 6f 75 6c 64 20 73 65 74 20 74  ion should set t
32600 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f  his parameter to
32610 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  .** [SQLITE_UTF1
32620 36 4c 45 5d 20 69 66 20 74 68 65 20 66 75 6e 63  6LE] if the func
32630 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  tion implementat
32640 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 0a 2a 2a 20  ion invokes .** 
32650 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
32660 65 78 74 31 36 6c 65 28 29 5d 20 6f 6e 20 61 6e  ext16le()] on an
32670 20 69 6e 70 75 74 2c 20 6f 72 20 5b 53 51 4c 49   input, or [SQLI
32680 54 45 5f 55 54 46 31 36 42 45 5d 20 69 66 20 74  TE_UTF16BE] if t
32690 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  he.** implementa
326a0 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 5b 73 71  tion invokes [sq
326b0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
326c0 31 36 62 65 28 29 5d 20 6f 6e 20 61 6e 20 69 6e  16be()] on an in
326d0 70 75 74 2c 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49  put, or.** [SQLI
326e0 54 45 5f 55 54 46 31 36 5d 20 69 66 20 5b 73 71  TE_UTF16] if [sq
326f0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
32700 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20 6f  16()] is used, o
32710 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 0a  r [SQLITE_UTF8].
32720 2a 2a 20 6f 74 68 65 72 77 69 73 65 2e 20 20 5e  ** otherwise.  ^
32730 54 68 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e  The same SQL fun
32740 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 72 65 67  ction may be reg
32750 69 73 74 65 72 65 64 20 6d 75 6c 74 69 70 6c 65  istered multiple
32760 20 74 69 6d 65 73 20 75 73 69 6e 67 0a 2a 2a 20   times using.** 
32770 64 69 66 66 65 72 65 6e 74 20 70 72 65 66 65 72  different prefer
32780 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  red text encodin
32790 67 73 2c 20 77 69 74 68 20 64 69 66 66 65 72 65  gs, with differe
327a0 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  nt implementatio
327b0 6e 73 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 65  ns for.** each e
327c0 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 20 5e 57 68 65  ncoding..** ^Whe
327d0 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65  n multiple imple
327e0 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68  mentations of th
327f0 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20  e same function 
32800 61 72 65 20 61 76 61 69 6c 61 62 6c 65 2c 20 53  are available, S
32810 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 69  QLite.** will pi
32820 63 6b 20 74 68 65 20 6f 6e 65 20 74 68 61 74 20  ck the one that 
32830 69 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c 65 61  involves the lea
32840 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74  st amount of dat
32850 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a  a conversion..**
32860 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20  .** ^The fourth 
32870 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 6f 70  parameter may op
32880 74 69 6f 6e 61 6c 6c 79 20 62 65 20 4f 52 65 64  tionally be ORed
32890 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 44 45   with [SQLITE_DE
328a0 54 45 52 4d 49 4e 49 53 54 49 43 5d 0a 2a 2a 20  TERMINISTIC].** 
328b0 74 6f 20 73 69 67 6e 61 6c 20 74 68 61 74 20 74  to signal that t
328c0 68 65 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c  he function will
328d0 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20 74   always return t
328e0 68 65 20 73 61 6d 65 20 72 65 73 75 6c 74 20 67  he same result g
328f0 69 76 65 6e 0a 2a 2a 20 74 68 65 20 73 61 6d 65  iven.** the same
32900 20 69 6e 70 75 74 73 20 77 69 74 68 69 6e 20 61   inputs within a
32910 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61 74   single SQL stat
32920 65 6d 65 6e 74 2e 20 20 4d 6f 73 74 20 53 51 4c  ement.  Most SQL
32930 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 0a 2a   functions are.*
32940 2a 20 64 65 74 65 72 6d 69 6e 69 73 74 69 63 2e  * deterministic.
32950 20 20 54 68 65 20 62 75 69 6c 74 2d 69 6e 20 5b    The built-in [
32960 72 61 6e 64 6f 6d 28 29 5d 20 53 51 4c 20 66 75  random()] SQL fu
32970 6e 63 74 69 6f 6e 20 69 73 20 61 6e 20 65 78 61  nction is an exa
32980 6d 70 6c 65 20 6f 66 20 61 0a 2a 2a 20 66 75 6e  mple of a.** fun
32990 63 74 69 6f 6e 20 74 68 61 74 20 69 73 20 6e 6f  ction that is no
329a0 74 20 64 65 74 65 72 6d 69 6e 69 73 74 69 63 2e  t deterministic.
329b0 20 20 54 68 65 20 53 51 4c 69 74 65 20 71 75 65    The SQLite que
329c0 72 79 20 70 6c 61 6e 6e 65 72 20 69 73 20 61 62  ry planner is ab
329d0 6c 65 20 74 6f 0a 2a 2a 20 70 65 72 66 6f 72 6d  le to.** perform
329e0 20 61 64 64 69 74 69 6f 6e 61 6c 20 6f 70 74 69   additional opti
329f0 6d 69 7a 61 74 69 6f 6e 73 20 6f 6e 20 64 65 74  mizations on det
32a00 65 72 6d 69 6e 69 73 74 69 63 20 66 75 6e 63 74  erministic funct
32a10 69 6f 6e 73 2c 20 73 6f 20 75 73 65 0a 2a 2a 20  ions, so use.** 
32a20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 44  of the [SQLITE_D
32a30 45 54 45 52 4d 49 4e 49 53 54 49 43 5d 20 66 6c  ETERMINISTIC] fl
32a40 61 67 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  ag is recommende
32a50 64 20 77 68 65 72 65 20 70 6f 73 73 69 62 6c 65  d where possible
32a60 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69  ..**.** ^(The fi
32a70 66 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  fth parameter is
32a80 20 61 6e 20 61 72 62 69 74 72 61 72 79 20 70 6f   an arbitrary po
32a90 69 6e 74 65 72 2e 20 20 54 68 65 20 69 6d 70 6c  inter.  The impl
32aa0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68  ementation of th
32ab0 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 63 61  e.** function ca
32ac0 6e 20 67 61 69 6e 20 61 63 63 65 73 73 20 74 6f  n gain access to
32ad0 20 74 68 69 73 20 70 6f 69 6e 74 65 72 20 75 73   this pointer us
32ae0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 75 73 65  ing [sqlite3_use
32af0 72 5f 64 61 74 61 28 29 5d 2e 29 5e 0a 2a 2a 0a  r_data()].)^.**.
32b00 2a 2a 20 5e 54 68 65 20 73 69 78 74 68 2c 20 73  ** ^The sixth, s
32b10 65 76 65 6e 74 68 20 61 6e 64 20 65 69 67 68 74  eventh and eight
32b20 68 20 70 61 72 61 6d 65 74 65 72 73 2c 20 78 46  h parameters, xF
32b30 75 6e 63 2c 20 78 53 74 65 70 20 61 6e 64 20 78  unc, xStep and x
32b40 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f  Final, are.** po
32b50 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61 6e 67  inters to C-lang
32b60 75 61 67 65 20 66 75 6e 63 74 69 6f 6e 73 20 74  uage functions t
32b70 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68  hat implement th
32b80 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f  e SQL function o
32b90 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 2e 20  r.** aggregate. 
32ba0 5e 41 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75  ^A scalar SQL fu
32bb0 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20  nction requires 
32bc0 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  an implementatio
32bd0 6e 20 6f 66 20 74 68 65 20 78 46 75 6e 63 0a 2a  n of the xFunc.*
32be0 2a 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79 3b  * callback only;
32bf0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 6d   NULL pointers m
32c00 75 73 74 20 62 65 20 70 61 73 73 65 64 20 61 73  ust be passed as
32c10 20 74 68 65 20 78 53 74 65 70 20 61 6e 64 20 78   the xStep and x
32c20 46 69 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d 65 74  Final.** paramet
32c30 65 72 73 2e 20 5e 41 6e 20 61 67 67 72 65 67 61  ers. ^An aggrega
32c40 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  te SQL function 
32c50 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c  requires an impl
32c60 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 78 53  ementation of xS
32c70 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69 6e 61  tep.** and xFina
32c80 6c 20 61 6e 64 20 4e 55 4c 4c 20 70 6f 69 6e 74  l and NULL point
32c90 65 72 20 6d 75 73 74 20 62 65 20 70 61 73 73 65  er must be passe
32ca0 64 20 66 6f 72 20 78 46 75 6e 63 2e 20 5e 54 6f  d for xFunc. ^To
32cb0 20 64 65 6c 65 74 65 20 61 6e 20 65 78 69 73 74   delete an exist
32cc0 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74  ing.** SQL funct
32cd0 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65  ion or aggregate
32ce0 2c 20 70 61 73 73 20 4e 55 4c 4c 20 70 6f 69 6e  , pass NULL poin
32cf0 74 65 72 73 20 66 6f 72 20 61 6c 6c 20 74 68 72  ters for all thr
32d00 65 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63  ee function.** c
32d10 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20  allbacks..**.** 
32d20 5e 28 49 66 20 74 68 65 20 6e 69 6e 74 68 20 70  ^(If the ninth p
32d30 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
32d40 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
32d50 69 6f 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20  ion_v2() is not 
32d60 4e 55 4c 4c 2c 0a 2a 2a 20 74 68 65 6e 20 69 74  NULL,.** then it
32d70 20 69 73 20 64 65 73 74 72 75 63 74 6f 72 20 66   is destructor f
32d80 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  or the applicati
32d90 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 2e  on data pointer.
32da0 20 0a 2a 2a 20 54 68 65 20 64 65 73 74 72 75 63   .** The destruc
32db0 74 6f 72 20 69 73 20 69 6e 76 6f 6b 65 64 20 77  tor is invoked w
32dc0 68 65 6e 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  hen the function
32dd0 20 69 73 20 64 65 6c 65 74 65 64 2c 20 65 69 74   is deleted, eit
32de0 68 65 72 20 62 79 20 62 65 69 6e 67 0a 2a 2a 20  her by being.** 
32df0 6f 76 65 72 6c 6f 61 64 65 64 20 6f 72 20 77 68  overloaded or wh
32e00 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
32e10 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65  connection close
32e20 73 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 64 65 73  s.)^.** ^The des
32e30 74 72 75 63 74 6f 72 20 69 73 20 61 6c 73 6f 20  tructor is also 
32e40 69 6e 76 6f 6b 65 64 20 69 66 20 74 68 65 20 63  invoked if the c
32e50 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  all to.** sqlite
32e60 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
32e70 6e 5f 76 32 28 29 20 66 61 69 6c 73 2e 0a 2a 2a  n_v2() fails..**
32e80 20 5e 57 68 65 6e 20 74 68 65 20 64 65 73 74 72   ^When the destr
32e90 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 6f  uctor callback o
32ea0 66 20 74 68 65 20 74 65 6e 74 68 20 70 61 72 61  f the tenth para
32eb0 6d 65 74 65 72 20 69 73 20 69 6e 76 6f 6b 65 64  meter is invoked
32ec0 2c 20 69 74 0a 2a 2a 20 69 73 20 70 61 73 73 65  , it.** is passe
32ed0 64 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  d a single argum
32ee0 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 63  ent which is a c
32ef0 6f 70 79 20 6f 66 20 74 68 65 20 61 70 70 6c 69  opy of the appli
32f00 63 61 74 69 6f 6e 20 64 61 74 61 20 0a 2a 2a 20  cation data .** 
32f10 70 6f 69 6e 74 65 72 20 77 68 69 63 68 20 77 61  pointer which wa
32f20 73 20 74 68 65 20 66 69 66 74 68 20 70 61 72 61  s the fifth para
32f30 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
32f40 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
32f50 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74  _v2()..**.** ^It
32f60 20 69 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f   is permitted to
32f70 20 72 65 67 69 73 74 65 72 20 6d 75 6c 74 69 70   register multip
32f80 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
32f90 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a  ns of the same.*
32fa0 2a 20 66 75 6e 63 74 69 6f 6e 73 20 77 69 74 68  * functions with
32fb0 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 62   the same name b
32fc0 75 74 20 77 69 74 68 20 65 69 74 68 65 72 20 64  ut with either d
32fd0 69 66 66 65 72 69 6e 67 20 6e 75 6d 62 65 72 73  iffering numbers
32fe0 20 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73   of.** arguments
32ff0 20 6f 72 20 64 69 66 66 65 72 69 6e 67 20 70 72   or differing pr
33000 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63  eferred text enc
33010 6f 64 69 6e 67 73 2e 20 20 5e 53 51 4c 69 74 65  odings.  ^SQLite
33020 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 74 68 65   will use.** the
33030 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
33040 74 68 61 74 20 6d 6f 73 74 20 63 6c 6f 73 65 6c  that most closel
33050 79 20 6d 61 74 63 68 65 73 20 74 68 65 20 77 61  y matches the wa
33060 79 20 69 6e 20 77 68 69 63 68 20 74 68 65 0a 2a  y in which the.*
33070 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  * SQL function i
33080 73 20 75 73 65 64 2e 20 20 5e 41 20 66 75 6e 63  s used.  ^A func
33090 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  tion implementat
330a0 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e 2d 6e  ion with a non-n
330b0 65 67 61 74 69 76 65 0a 2a 2a 20 6e 41 72 67 20  egative.** nArg 
330c0 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 62  parameter is a b
330d0 65 74 74 65 72 20 6d 61 74 63 68 20 74 68 61 6e  etter match than
330e0 20 61 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c   a function impl
330f0 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 0a  ementation with.
33100 2a 2a 20 61 20 6e 65 67 61 74 69 76 65 20 6e 41  ** a negative nA
33110 72 67 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e  rg.  ^A function
33120 20 77 68 65 72 65 20 74 68 65 20 70 72 65 66 65   where the prefe
33130 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69  rred text encodi
33140 6e 67 0a 2a 2a 20 6d 61 74 63 68 65 73 20 74 68  ng.** matches th
33150 65 20 64 61 74 61 62 61 73 65 20 65 6e 63 6f 64  e database encod
33160 69 6e 67 20 69 73 20 61 20 62 65 74 74 65 72 0a  ing is a better.
33170 2a 2a 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20  ** match than a 
33180 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74  function where t
33190 68 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 64  he encoding is d
331a0 69 66 66 65 72 65 6e 74 2e 20 20 0a 2a 2a 20 5e  ifferent.  .** ^
331b0 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65  A function where
331c0 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69   the encoding di
331d0 66 66 65 72 65 6e 63 65 20 69 73 20 62 65 74 77  fference is betw
331e0 65 65 6e 20 55 54 46 31 36 6c 65 20 61 6e 64 20  een UTF16le and 
331f0 55 54 46 31 36 62 65 0a 2a 2a 20 69 73 20 61 20  UTF16be.** is a 
33200 63 6c 6f 73 65 72 20 6d 61 74 63 68 20 74 68 61  closer match tha
33210 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65  n a function whe
33220 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20  re the encoding 
33230 64 69 66 66 65 72 65 6e 63 65 20 69 73 0a 2a 2a  difference is.**
33240 20 62 65 74 77 65 65 6e 20 55 54 46 38 20 61 6e   between UTF8 an
33250 64 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e  d UTF16..**.** ^
33260 42 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74 69 6f  Built-in functio
33270 6e 73 20 6d 61 79 20 62 65 20 6f 76 65 72 6c 6f  ns may be overlo
33280 61 64 65 64 20 62 79 20 6e 65 77 20 61 70 70 6c  aded by new appl
33290 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
332a0 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  functions..**.**
332b0 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e   ^An application
332c0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
332d0 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 20 74  n is permitted t
332e0 6f 20 63 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20  o call other.** 
332f0 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
33300 73 2e 20 20 48 6f 77 65 76 65 72 2c 20 73 75 63  s.  However, suc
33310 68 20 63 61 6c 6c 73 20 6d 75 73 74 20 6e 6f 74  h calls must not
33320 0a 2a 2a 20 63 6c 6f 73 65 20 74 68 65 20 64 61  .** close the da
33330 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
33340 6e 20 6e 6f 72 20 66 69 6e 61 6c 69 7a 65 20 6f  n nor finalize o
33350 72 20 72 65 73 65 74 20 74 68 65 20 70 72 65 70  r reset the prep
33360 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e  ared.** statemen
33370 74 20 69 6e 20 77 68 69 63 68 20 74 68 65 20 66  t in which the f
33380 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69  unction is runni
33390 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  ng..*/.SQLITE_AP
333a0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72  I int sqlite3_cr
333b0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 0a 20  eate_function(. 
333c0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20   sqlite3 *db,.  
333d0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e  const char *zFun
333e0 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74  ctionName,.  int
333f0 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65   nArg,.  int eTe
33400 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70  xtRep,.  void *p
33410 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  App,.  void (*xF
33420 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  unc)(sqlite3_con
33430 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
33440 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
33450 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69  id (*xStep)(sqli
33460 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
33470 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
33480 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e  ),.  void (*xFin
33490 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  al)(sqlite3_cont
334a0 65 78 74 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 5f  ext*).);.SQLITE_
334b0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
334c0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
334d0 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  6(.  sqlite3 *db
334e0 2c 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  ,.  const void *
334f0 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20  zFunctionName,. 
33500 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74   int nArg,.  int
33510 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69   eTextRep,.  voi
33520 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20  d *pApp,.  void 
33530 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33  (*xFunc)(sqlite3
33540 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
33550 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
33560 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28    void (*xStep)(
33570 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
33580 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
33590 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
335a0 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f  xFinal)(sqlite3_
335b0 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 53 51 4c  context*).);.SQL
335c0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
335d0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
335e0 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74 65  ion_v2(.  sqlite
335f0 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63  3 *db,.  const c
33600 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61  har *zFunctionNa
33610 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a  me,.  int nArg,.
33620 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a    int eTextRep,.
33630 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20    void *pApp,.  
33640 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71  void (*xFunc)(sq
33650 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
33660 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
33670 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53  **),.  void (*xS
33680 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  tep)(sqlite3_con
33690 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
336a0 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
336b0 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c  id (*xFinal)(sql
336c0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 2c 0a  ite3_context*),.
336d0 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79    void(*xDestroy
336e0 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a  )(void*).);../*.
336f0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65 78  ** CAPI3REF: Tex
33700 74 20 45 6e 63 6f 64 69 6e 67 73 0a 2a 2a 0a 2a  t Encodings.**.*
33710 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
33720 20 64 65 66 69 6e 65 20 69 6e 74 65 67 65 72 20   define integer 
33730 63 6f 64 65 73 20 74 68 61 74 20 72 65 70 72 65  codes that repre
33740 73 65 6e 74 20 74 68 65 20 76 61 72 69 6f 75 73  sent the various
33750 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  .** text encodin
33760 67 73 20 73 75 70 70 6f 72 74 65 64 20 62 79 20  gs supported by 
33770 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69  SQLite..*/.#defi
33780 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 38 20 20  ne SQLITE_UTF8  
33790 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69           1.#defi
337a0 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 4c  ne SQLITE_UTF16L
337b0 45 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69  E        2.#defi
337c0 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 42  ne SQLITE_UTF16B
337d0 45 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69  E        3.#defi
337e0 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 20  ne SQLITE_UTF16 
337f0 20 20 20 20 20 20 20 20 20 34 20 20 20 20 2f 2a           4    /*
33800 20 55 73 65 20 6e 61 74 69 76 65 20 62 79 74 65   Use native byte
33810 20 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66 69 6e   order */.#defin
33820 65 20 53 51 4c 49 54 45 5f 41 4e 59 20 20 20 20  e SQLITE_ANY    
33830 20 20 20 20 20 20 20 20 35 20 20 20 20 2f 2a 20          5    /* 
33840 44 65 70 72 65 63 61 74 65 64 20 2a 2f 0a 23 64  Deprecated */.#d
33850 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46  efine SQLITE_UTF
33860 31 36 5f 41 4c 49 47 4e 45 44 20 20 38 20 20 20  16_ALIGNED  8   
33870 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61   /* sqlite3_crea
33880 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c  te_collation onl
33890 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  y */../*.** CAPI
338a0 33 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 46  3REF: Function F
338b0 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  lags.**.** These
338c0 20 63 6f 6e 73 74 61 6e 74 73 20 6d 61 79 20 62   constants may b
338d0 65 20 4f 52 65 64 20 74 6f 67 65 74 68 65 72 20  e ORed together 
338e0 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51  with the .** [SQ
338f0 4c 49 54 45 5f 55 54 46 38 20 7c 20 70 72 65 66  LITE_UTF8 | pref
33900 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64  erred text encod
33910 69 6e 67 5d 20 61 73 20 74 68 65 20 66 6f 75 72  ing] as the four
33920 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74  th argument.** t
33930 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  o [sqlite3_creat
33940 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 5b  e_function()], [
33950 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
33960 75 6e 63 74 69 6f 6e 31 36 28 29 5d 2c 20 6f 72  unction16()], or
33970 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  .** [sqlite3_cre
33980 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28  ate_function_v2(
33990 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  )]..*/.#define S
339a0 51 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e 49 53  QLITE_DETERMINIS
339b0 54 49 43 20 20 20 20 30 78 38 30 30 0a 0a 2f 2a  TIC    0x800../*
339c0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
339d0 70 72 65 63 61 74 65 64 20 46 75 6e 63 74 69 6f  precated Functio
339e0 6e 73 0a 2a 2a 20 44 45 50 52 45 43 41 54 45 44  ns.** DEPRECATED
339f0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e  .**.** These fun
33a00 63 74 69 6f 6e 73 20 61 72 65 20 5b 64 65 70 72  ctions are [depr
33a10 65 63 61 74 65 64 5d 2e 20 20 49 6e 20 6f 72 64  ecated].  In ord
33a20 65 72 20 74 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a  er to maintain.*
33a30 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70  * backwards comp
33a40 61 74 69 62 69 6c 69 74 79 20 77 69 74 68 20 6f  atibility with o
33a50 6c 64 65 72 20 63 6f 64 65 2c 20 74 68 65 73 65  lder code, these
33a60 20 66 75 6e 63 74 69 6f 6e 73 20 63 6f 6e 74 69   functions conti
33a70 6e 75 65 20 0a 2a 2a 20 74 6f 20 62 65 20 73 75  nue .** to be su
33a80 70 70 6f 72 74 65 64 2e 20 20 48 6f 77 65 76 65  pported.  Howeve
33a90 72 2c 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69  r, new applicati
33aa0 6f 6e 73 20 73 68 6f 75 6c 64 20 61 76 6f 69 64  ons should avoid
33ab0 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20 74  .** the use of t
33ac0 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20  hese functions. 
33ad0 20 54 6f 20 68 65 6c 70 20 65 6e 63 6f 75 72 61   To help encoura
33ae0 67 65 20 70 65 6f 70 6c 65 20 74 6f 20 61 76 6f  ge people to avo
33af0 69 64 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65 73  id.** using thes
33b00 65 20 66 75 6e 63 74 69 6f 6e 73 2c 20 77 65 20  e functions, we 
33b10 61 72 65 20 6e 6f 74 20 67 6f 69 6e 67 20 74 6f  are not going to
33b20 20 74 65 6c 6c 20 79 6f 75 20 77 68 61 74 20 74   tell you what t
33b30 68 65 79 20 64 6f 2e 0a 2a 2f 0a 23 69 66 6e 64  hey do..*/.#ifnd
33b40 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 44  ef SQLITE_OMIT_D
33b50 45 50 52 45 43 41 54 45 44 0a 53 51 4c 49 54 45  EPRECATED.SQLITE
33b60 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52  _API SQLITE_DEPR
33b70 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74  ECATED int sqlit
33b80 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 75  e3_aggregate_cou
33b90 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  nt(sqlite3_conte
33ba0 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  xt*);.SQLITE_API
33bb0 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54   SQLITE_DEPRECAT
33bc0 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  ED int sqlite3_e
33bd0 78 70 69 72 65 64 28 73 71 6c 69 74 65 33 5f 73  xpired(sqlite3_s
33be0 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  tmt*);.SQLITE_AP
33bf0 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  I SQLITE_DEPRECA
33c00 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  TED int sqlite3_
33c10 74 72 61 6e 73 66 65 72 5f 62 69 6e 64 69 6e 67  transfer_binding
33c20 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  s(sqlite3_stmt*,
33c30 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b   sqlite3_stmt*);
33c40 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49  .SQLITE_API SQLI
33c50 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e  TE_DEPRECATED in
33c60 74 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c  t sqlite3_global
33c70 5f 72 65 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a  _recover(void);.
33c80 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54  SQLITE_API SQLIT
33c90 45 5f 44 45 50 52 45 43 41 54 45 44 20 76 6f 69  E_DEPRECATED voi
33ca0 64 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64  d sqlite3_thread
33cb0 5f 63 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a  _cleanup(void);.
33cc0 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54  SQLITE_API SQLIT
33cd0 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74  E_DEPRECATED int
33ce0 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f   sqlite3_memory_
33cf0 61 6c 61 72 6d 28 76 6f 69 64 28 2a 29 28 76 6f  alarm(void(*)(vo
33d00 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36  id*,sqlite3_int6
33d10 34 2c 69 6e 74 29 2c 0a 20 20 20 20 20 20 20 20  4,int),.        
33d20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f                vo
33d30 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36  id*,sqlite3_int6
33d40 34 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a  4);.#endif../*.*
33d50 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61  * CAPI3REF: Obta
33d60 69 6e 69 6e 67 20 53 51 4c 20 46 75 6e 63 74 69  ining SQL Functi
33d70 6f 6e 20 50 61 72 61 6d 65 74 65 72 20 56 61 6c  on Parameter Val
33d80 75 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d  ues.**.** The C-
33d90 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c 65 6d 65  language impleme
33da0 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66  ntation of SQL f
33db0 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67  unctions and agg
33dc0 72 65 67 61 74 65 73 20 75 73 65 73 0a 2a 2a 20  regates uses.** 
33dd0 74 68 69 73 20 73 65 74 20 6f 66 20 69 6e 74 65  this set of inte
33de0 72 66 61 63 65 20 72 6f 75 74 69 6e 65 73 20 74  rface routines t
33df0 6f 20 61 63 63 65 73 73 20 74 68 65 20 70 61 72  o access the par
33e00 61 6d 65 74 65 72 20 76 61 6c 75 65 73 20 6f 6e  ameter values on
33e10 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  .** the function
33e20 20 6f 72 20 61 67 67 72 65 67 61 74 65 2e 0a 2a   or aggregate..*
33e30 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63 20 28  *.** The xFunc (
33e40 66 6f 72 20 73 63 61 6c 61 72 20 66 75 6e 63 74  for scalar funct
33e50 69 6f 6e 73 29 20 6f 72 20 78 53 74 65 70 20 28  ions) or xStep (
33e60 66 6f 72 20 61 67 67 72 65 67 61 74 65 73 29 20  for aggregates) 
33e70 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f  parameters.** to
33e80 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
33e90 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64  _function()] and
33ea0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
33eb0 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a  _function16()].*
33ec0 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c 62 61 63  * define callbac
33ed0 6b 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e  ks that implemen
33ee0 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  t the SQL functi
33ef0 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74  ons and aggregat
33f00 65 73 2e 0a 2a 2a 20 54 68 65 20 33 72 64 20 70  es..** The 3rd p
33f10 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 73  arameter to thes
33f20 65 20 63 61 6c 6c 62 61 63 6b 73 20 69 73 20 61  e callbacks is a
33f30 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
33f40 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65  ers to.** [prote
33f50 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
33f60 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20 54 68  ue] objects.  Th
33f70 65 72 65 20 69 73 20 6f 6e 65 20 5b 73 71 6c 69  ere is one [sqli
33f80 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
33f90 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 70 61  t for.** each pa
33fa0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 53  rameter to the S
33fb0 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20 54 68  QL function.  Th
33fc0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
33fd0 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78 74 72   used to.** extr
33fe0 61 63 74 20 76 61 6c 75 65 73 20 66 72 6f 6d 20  act values from 
33ff0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  the [sqlite3_val
34000 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a  ue] objects..**.
34010 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
34020 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 69 74 68  s work only with
34030 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
34040 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
34050 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d  ts..** Any attem
34060 70 74 20 74 6f 20 75 73 65 20 74 68 65 73 65 20  pt to use these 
34070 72 6f 75 74 69 6e 65 73 20 6f 6e 20 61 6e 20 5b  routines on an [
34080 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
34090 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62  te3_value].** ob
340a0 6a 65 63 74 20 72 65 73 75 6c 74 73 20 69 6e 20  ject results in 
340b0 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69  undefined behavi
340c0 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  or..**.** ^These
340d0 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6a   routines work j
340e0 75 73 74 20 6c 69 6b 65 20 74 68 65 20 63 6f 72  ust like the cor
340f0 72 65 73 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75  responding [colu
34100 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69  mn access functi
34110 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65 70 74 20 74  ons].** except t
34120 68 61 74 20 74 68 65 73 65 20 72 6f 75 74 69 6e  hat these routin
34130 65 73 20 74 61 6b 65 20 61 20 73 69 6e 67 6c 65  es take a single
34140 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
34150 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
34160 74 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 73  t.** pointer ins
34170 74 65 61 64 20 6f 66 20 61 20 5b 73 71 6c 69 74  tead of a [sqlit
34180 65 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e 74 65  e3_stmt*] pointe
34190 72 20 61 6e 64 20 61 6e 20 69 6e 74 65 67 65 72  r and an integer
341a0 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a   column number..
341b0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
341c0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28  e3_value_text16(
341d0 29 20 69 6e 74 65 72 66 61 63 65 20 65 78 74 72  ) interface extr
341e0 61 63 74 73 20 61 20 55 54 46 2d 31 36 20 73 74  acts a UTF-16 st
341f0 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 20 6e  ring.** in the n
34200 61 74 69 76 65 20 62 79 74 65 2d 6f 72 64 65 72  ative byte-order
34210 20 6f 66 20 74 68 65 20 68 6f 73 74 20 6d 61 63   of the host mac
34220 68 69 6e 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 73  hine.  ^The.** s
34230 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
34240 74 31 36 62 65 28 29 20 61 6e 64 20 73 71 6c 69  t16be() and sqli
34250 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
34260 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a  le() interfaces.
34270 2a 2a 20 65 78 74 72 61 63 74 20 55 54 46 2d 31  ** extract UTF-1
34280 36 20 73 74 72 69 6e 67 73 20 61 73 20 62 69 67  6 strings as big
34290 2d 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69 74 74  -endian and litt
342a0 6c 65 2d 65 6e 64 69 61 6e 20 72 65 73 70 65 63  le-endian respec
342b0 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28  tively..**.** ^(
342c0 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  The sqlite3_valu
342d0 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 29  e_numeric_type()
342e0 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d   interface attem
342f0 70 74 73 20 74 6f 20 61 70 70 6c 79 0a 2a 2a 20  pts to apply.** 
34300 6e 75 6d 65 72 69 63 20 61 66 66 69 6e 69 74 79  numeric affinity
34310 20 74 6f 20 74 68 65 20 76 61 6c 75 65 2e 20 20   to the value.  
34320 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20  This means that 
34330 61 6e 20 61 74 74 65 6d 70 74 20 69 73 0a 2a 2a  an attempt is.**
34340 20 6d 61 64 65 20 74 6f 20 63 6f 6e 76 65 72 74   made to convert
34350 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 61 6e   the value to an
34360 20 69 6e 74 65 67 65 72 20 6f 72 20 66 6c 6f 61   integer or floa
34370 74 69 6e 67 20 70 6f 69 6e 74 2e 20 20 49 66 0a  ting point.  If.
34380 2a 2a 20 73 75 63 68 20 61 20 63 6f 6e 76 65 72  ** such a conver
34390 73 69 6f 6e 20 69 73 20 70 6f 73 73 69 62 6c 65  sion is possible
343a0 20 77 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66   without loss of
343b0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 69 6e   information (in
343c0 20 6f 74 68 65 72 0a 2a 2a 20 77 6f 72 64 73 2c   other.** words,
343d0 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 69 73   if the value is
343e0 20 61 20 73 74 72 69 6e 67 20 74 68 61 74 20 6c   a string that l
343f0 6f 6f 6b 73 20 6c 69 6b 65 20 61 20 6e 75 6d 62  ooks like a numb
34400 65 72 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  er).** then the 
34410 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 65  conversion is pe
34420 72 66 6f 72 6d 65 64 2e 20 20 4f 74 68 65 72 77  rformed.  Otherw
34430 69 73 65 20 6e 6f 20 63 6f 6e 76 65 72 73 69 6f  ise no conversio
34440 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a 20 54 68 65  n occurs..** The
34450 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52   [SQLITE_INTEGER
34460 20 7c 20 64 61 74 61 74 79 70 65 5d 20 61 66 74   | datatype] aft
34470 65 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73  er conversion is
34480 20 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a   returned.)^.**.
34490 2a 2a 20 50 6c 65 61 73 65 20 70 61 79 20 70 61  ** Please pay pa
344a0 72 74 69 63 75 6c 61 72 20 61 74 74 65 6e 74 69  rticular attenti
344b0 6f 6e 20 74 6f 20 74 68 65 20 66 61 63 74 20 74  on to the fact t
344c0 68 61 74 20 74 68 65 20 70 6f 69 6e 74 65 72 20  hat the pointer 
344d0 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d  returned.** from
344e0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
344f0 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65  blob()], [sqlite
34500 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c  3_value_text()],
34510 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
34520 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 20  value_text16()] 
34530 63 61 6e 20 62 65 20 69 6e 76 61 6c 69 64 61 74  can be invalidat
34540 65 64 20 62 79 20 61 20 73 75 62 73 65 71 75 65  ed by a subseque
34550 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73  nt call to.** [s
34560 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
34570 65 73 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  es()], [sqlite3_
34580 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 29 5d  value_bytes16()]
34590 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  , [sqlite3_value
345a0 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20  _text()],.** or 
345b0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
345c0 65 78 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  ext16()]..**.** 
345d0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d  These routines m
345e0 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72  ust be called fr
345f0 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65  om the same thre
34600 61 64 20 61 73 0a 2a 2a 20 74 68 65 20 53 51 4c  ad as.** the SQL
34610 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 73   function that s
34620 75 70 70 6c 69 65 64 20 74 68 65 20 5b 73 71 6c  upplied the [sql
34630 69 74 65 33 5f 76 61 6c 75 65 2a 5d 20 70 61 72  ite3_value*] par
34640 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a 53 51 4c 49  ameters..*/.SQLI
34650 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69  TE_API const voi
34660 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  d *sqlite3_value
34670 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 76 61  _blob(sqlite3_va
34680 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  lue*);.SQLITE_AP
34690 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61  I int sqlite3_va
346a0 6c 75 65 5f 62 79 74 65 73 28 73 71 6c 69 74 65  lue_bytes(sqlite
346b0 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54  3_value*);.SQLIT
346c0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
346d0 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28  3_value_bytes16(
346e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
346f0 0a 53 51 4c 49 54 45 5f 41 50 49 20 64 6f 75 62  .SQLITE_API doub
34700 6c 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  le sqlite3_value
34710 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f  _double(sqlite3_
34720 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f  value*);.SQLITE_
34730 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
34740 76 61 6c 75 65 5f 69 6e 74 28 73 71 6c 69 74 65  value_int(sqlite
34750 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54  3_value*);.SQLIT
34760 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e  E_API sqlite3_in
34770 74 36 34 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  t64 sqlite3_valu
34780 65 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f  e_int64(sqlite3_
34790 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f  value*);.SQLITE_
347a0 41 50 49 20 63 6f 6e 73 74 20 75 6e 73 69 67 6e  API const unsign
347b0 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  ed char *sqlite3
347c0 5f 76 61 6c 75 65 5f 74 65 78 74 28 73 71 6c 69  _value_text(sqli
347d0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c  te3_value*);.SQL
347e0 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f  ITE_API const vo
347f0 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75  id *sqlite3_valu
34800 65 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33  e_text16(sqlite3
34810 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45  _value*);.SQLITE
34820 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20  _API const void 
34830 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  *sqlite3_value_t
34840 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f  ext16le(sqlite3_
34850 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f  value*);.SQLITE_
34860 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  API const void *
34870 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
34880 78 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f 76  xt16be(sqlite3_v
34890 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41  alue*);.SQLITE_A
348a0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 76  PI int sqlite3_v
348b0 61 6c 75 65 5f 74 79 70 65 28 73 71 6c 69 74 65  alue_type(sqlite
348c0 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54  3_value*);.SQLIT
348d0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
348e0 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f  3_value_numeric_
348f0 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  type(sqlite3_val
34900 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ue*);../*.** CAP
34910 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 41 67  I3REF: Obtain Ag
34920 67 72 65 67 61 74 65 20 46 75 6e 63 74 69 6f 6e  gregate Function
34930 20 43 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 49   Context.**.** I
34940 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f  mplementations o
34950 66 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20  f aggregate SQL 
34960 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 20 74 68  functions use th
34970 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 74 6f  is.** routine to
34980 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79   allocate memory
34990 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 74 68 65   for storing the
349a0 69 72 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20  ir state..**.** 
349b0 5e 54 68 65 20 66 69 72 73 74 20 74 69 6d 65 20  ^The first time 
349c0 74 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72  the sqlite3_aggr
349d0 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c  egate_context(C,
349e0 4e 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61  N) routine is ca
349f0 6c 6c 65 64 20 0a 2a 2a 20 66 6f 72 20 61 20 70  lled .** for a p
34a00 61 72 74 69 63 75 6c 61 72 20 61 67 67 72 65 67  articular aggreg
34a10 61 74 65 20 66 75 6e 63 74 69 6f 6e 2c 20 53 51  ate function, SQ
34a20 4c 69 74 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65  Lite.** allocate
34a30 73 20 4e 20 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a  s N of memory, z
34a40 65 72 6f 65 73 20 6f 75 74 20 74 68 61 74 20 6d  eroes out that m
34a50 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74 75 72  emory, and retur
34a60 6e 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  ns a pointer.** 
34a70 74 6f 20 74 68 65 20 6e 65 77 20 6d 65 6d 6f 72  to the new memor
34a80 79 2e 20 5e 4f 6e 20 73 65 63 6f 6e 64 20 61 6e  y. ^On second an
34a90 64 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  d subsequent cal
34aa0 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  ls to.** sqlite3
34ab0 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
34ac0 78 74 28 29 20 66 6f 72 20 74 68 65 20 73 61 6d  xt() for the sam
34ad0 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63  e aggregate func
34ae0 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 2c 0a 2a  tion instance,.*
34af0 2a 20 74 68 65 20 73 61 6d 65 20 62 75 66 66 65  * the same buffe
34b00 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20  r is returned.  
34b10 53 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  Sqlite3_aggregat
34b20 65 5f 63 6f 6e 74 65 78 74 28 29 20 69 73 20 6e  e_context() is n
34b30 6f 72 6d 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65  ormally.** calle
34b40 64 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20  d once for each 
34b50 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68  invocation of th
34b60 65 20 78 53 74 65 70 20 63 61 6c 6c 62 61 63 6b  e xStep callback
34b70 20 61 6e 64 20 74 68 65 6e 20 6f 6e 65 0a 2a 2a   and then one.**
34b80 20 6c 61 73 74 20 74 69 6d 65 20 77 68 65 6e 20   last time when 
34b90 74 68 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62  the xFinal callb
34ba0 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20  ack is invoked. 
34bb0 20 5e 28 57 68 65 6e 20 6e 6f 20 72 6f 77 73 20   ^(When no rows 
34bc0 6d 61 74 63 68 0a 2a 2a 20 61 6e 20 61 67 67 72  match.** an aggr
34bd0 65 67 61 74 65 20 71 75 65 72 79 2c 20 74 68 65  egate query, the
34be0 20 78 53 74 65 70 28 29 20 63 61 6c 6c 62 61 63   xStep() callbac
34bf0 6b 20 6f 66 20 74 68 65 20 61 67 67 72 65 67 61  k of the aggrega
34c00 74 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 69  te function.** i
34c10 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73  mplementation is
34c20 20 6e 65 76 65 72 20 63 61 6c 6c 65 64 20 61 6e   never called an
34c30 64 20 78 46 69 6e 61 6c 28 29 20 69 73 20 63 61  d xFinal() is ca
34c40 6c 6c 65 64 20 65 78 61 63 74 6c 79 20 6f 6e 63  lled exactly onc
34c50 65 2e 0a 2a 2a 20 49 6e 20 74 68 6f 73 65 20 63  e..** In those c
34c60 61 73 65 73 2c 20 73 71 6c 69 74 65 33 5f 61 67  ases, sqlite3_ag
34c70 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
34c80 29 20 6d 69 67 68 74 20 62 65 20 63 61 6c 6c 65  ) might be calle
34c90 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 66 69 72  d for the.** fir
34ca0 73 74 20 74 69 6d 65 20 66 72 6f 6d 20 77 69 74  st time from wit
34cb0 68 69 6e 20 78 46 69 6e 61 6c 28 29 2e 29 5e 0a  hin xFinal().)^.
34cc0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
34cd0 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
34ce0 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e  text(C,N) routin
34cf0 65 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  e returns a NULL
34d00 20 70 6f 69 6e 74 65 72 20 0a 2a 2a 20 77 68 65   pointer .** whe
34d10 6e 20 66 69 72 73 74 20 63 61 6c 6c 65 64 20 69  n first called i
34d20 66 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e  f N is less than
34d30 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72   or equal to zer
34d40 6f 20 6f 72 20 69 66 20 61 20 6d 65 6d 6f 72 79  o or if a memory
34d50 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 65 72 72  .** allocate err
34d60 6f 72 20 6f 63 63 75 72 73 2e 0a 2a 2a 0a 2a 2a  or occurs..**.**
34d70 20 5e 28 54 68 65 20 61 6d 6f 75 6e 74 20 6f 66   ^(The amount of
34d80 20 73 70 61 63 65 20 61 6c 6c 6f 63 61 74 65 64   space allocated
34d90 20 62 79 20 73 71 6c 69 74 65 33 5f 61 67 67 72   by sqlite3_aggr
34da0 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c  egate_context(C,
34db0 4e 29 20 69 73 0a 2a 2a 20 64 65 74 65 72 6d 69  N) is.** determi
34dc0 6e 65 64 20 62 79 20 74 68 65 20 4e 20 70 61 72  ned by the N par
34dd0 61 6d 65 74 65 72 20 6f 6e 20 66 69 72 73 74 20  ameter on first 
34de0 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 2e  successful call.
34df0 20 20 43 68 61 6e 67 69 6e 67 20 74 68 65 0a 2a    Changing the.*
34e00 2a 20 76 61 6c 75 65 20 6f 66 20 4e 20 69 6e 20  * value of N in 
34e10 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20  subsequent call 
34e20 74 6f 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  to sqlite3_aggre
34e30 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 77  gate_context() w
34e40 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20 73 61 6d  ithin.** the sam
34e50 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63  e aggregate func
34e60 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 20 77 69  tion instance wi
34e70 6c 6c 20 6e 6f 74 20 72 65 73 69 7a 65 20 74 68  ll not resize th
34e80 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f  e memory.** allo
34e90 63 61 74 69 6f 6e 2e 29 5e 20 20 57 69 74 68 69  cation.)^  Withi
34ea0 6e 20 74 68 65 20 78 46 69 6e 61 6c 20 63 61 6c  n the xFinal cal
34eb0 6c 62 61 63 6b 2c 20 69 74 20 69 73 20 63 75 73  lback, it is cus
34ec0 74 6f 6d 61 72 79 20 74 6f 20 73 65 74 0a 2a 2a  tomary to set.**
34ed0 20 4e 3d 30 20 69 6e 20 63 61 6c 6c 73 20 74 6f   N=0 in calls to
34ee0 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
34ef0 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20  te_context(C,N) 
34f00 73 6f 20 74 68 61 74 20 6e 6f 20 0a 2a 2a 20 70  so that no .** p
34f10 6f 69 6e 74 6c 65 73 73 20 6d 65 6d 6f 72 79 20  ointless memory 
34f20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 6f 63 63 75  allocations occu
34f30 72 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65  r..**.** ^SQLite
34f40 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66   automatically f
34f50 72 65 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20  rees the memory 
34f60 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 0a 2a 2a  allocated by .**
34f70 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
34f80 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 77 68 65  te_context() whe
34f90 6e 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20  n the aggregate 
34fa0 71 75 65 72 79 20 63 6f 6e 63 6c 75 64 65 73 2e  query concludes.
34fb0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
34fc0 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20   parameter must 
34fd0 62 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  be a copy of the
34fe0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
34ff0 74 65 78 74 20 7c 20 53 51 4c 20 66 75 6e 63 74  text | SQL funct
35000 69 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 74 68 61  ion context] tha
35010 74 20 69 73 20 74 68 65 20 66 69 72 73 74 20 70  t is the first p
35020 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74  arameter.** to t
35030 68 65 20 78 53 74 65 70 20 6f 72 20 78 46 69 6e  he xStep or xFin
35040 61 6c 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74  al callback rout
35050 69 6e 65 20 74 68 61 74 20 69 6d 70 6c 65 6d 65  ine that impleme
35060 6e 74 73 20 74 68 65 20 61 67 67 72 65 67 61 74  nts the aggregat
35070 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  e.** function..*
35080 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
35090 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64  e must be called
350a0 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74   from the same t
350b0 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a  hread in which.*
350c0 2a 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20  * the aggregate 
350d0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  SQL function is 
350e0 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49  running..*/.SQLI
350f0 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c  TE_API void *sql
35100 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
35110 6f 6e 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63  ontext(sqlite3_c
35120 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 42 79  ontext*, int nBy
35130 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tes);../*.** CAP
35140 49 33 52 45 46 3a 20 55 73 65 72 20 44 61 74 61  I3REF: User Data
35150 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a   For Functions.*
35160 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
35170 33 5f 75 73 65 72 5f 64 61 74 61 28 29 20 69 6e  3_user_data() in
35180 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
35190 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65  a copy of.** the
351a0 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 77 61   pointer that wa
351b0 73 20 74 68 65 20 70 55 73 65 72 44 61 74 61 20  s the pUserData 
351c0 70 61 72 61 6d 65 74 65 72 20 28 74 68 65 20 35  parameter (the 5
351d0 74 68 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a  th parameter).**
351e0 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
351f0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
35200 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69  ()].** and [sqli
35210 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
35220 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65  ion16()] routine
35230 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c  s that originall
35240 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20  y.** registered 
35250 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
35260 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
35270 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  ..**.** This rou
35280 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c  tine must be cal
35290 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d  led from the sam
352a0 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63  e thread in whic
352b0 68 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61  h.** the applica
352c0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
352d0 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67  ction is running
352e0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
352f0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 75 73  void *sqlite3_us
35300 65 72 5f 64 61 74 61 28 73 71 6c 69 74 65 33 5f  er_data(sqlite3_
35310 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a  context*);../*.*
35320 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61  * CAPI3REF: Data
35330 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20  base Connection 
35340 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  For Functions.**
35350 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
35360 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64  _context_db_hand
35370 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  le() interface r
35380 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66  eturns a copy of
35390 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20  .** the pointer 
353a0 74 6f 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  to the [database
353b0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 68   connection] (th
353c0 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 29  e 1st parameter)
353d0 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  .** of the [sqli
353e0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
353f0 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73  ion()].** and [s
35400 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
35410 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74  nction16()] rout
35420 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e  ines that origin
35430 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72  ally.** register
35440 65 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ed the applicati
35450 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on defined funct
35460 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ion..*/.SQLITE_A
35470 50 49 20 73 71 6c 69 74 65 33 20 2a 73 71 6c 69  PI sqlite3 *sqli
35480 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68  te3_context_db_h
35490 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f  andle(sqlite3_co
354a0 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ntext*);../*.** 
354b0 43 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74 69  CAPI3REF: Functi
354c0 6f 6e 20 41 75 78 69 6c 69 61 72 79 20 44 61 74  on Auxiliary Dat
354d0 61 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75  a.**.** These fu
354e0 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 75  nctions may be u
354f0 73 65 64 20 62 79 20 28 6e 6f 6e 2d 61 67 67 72  sed by (non-aggr
35500 65 67 61 74 65 29 20 53 51 4c 20 66 75 6e 63 74  egate) SQL funct
35510 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63  ions to.** assoc
35520 69 61 74 65 20 6d 65 74 61 64 61 74 61 20 77 69  iate metadata wi
35530 74 68 20 61 72 67 75 6d 65 6e 74 20 76 61 6c 75  th argument valu
35540 65 73 2e 20 49 66 20 74 68 65 20 73 61 6d 65 20  es. If the same 
35550 76 61 6c 75 65 20 69 73 20 70 61 73 73 65 64 20  value is passed 
35560 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69  to.** multiple i
35570 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68  nvocations of th
35580 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74  e same SQL funct
35590 69 6f 6e 20 64 75 72 69 6e 67 20 71 75 65 72 79  ion during query
355a0 20 65 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65   execution, unde
355b0 72 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d  r.** some circum
355c0 73 74 61 6e 63 65 73 20 74 68 65 20 61 73 73 6f  stances the asso
355d0 63 69 61 74 65 64 20 6d 65 74 61 64 61 74 61 20  ciated metadata 
355e0 6d 61 79 20 62 65 20 70 72 65 73 65 72 76 65 64  may be preserved
355f0 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 0a 2a 2a  .  An example.**
35600 20 6f 66 20 77 68 65 72 65 20 74 68 69 73 20 6d   of where this m
35610 69 67 68 74 20 62 65 20 75 73 65 66 75 6c 20 69  ight be useful i
35620 73 20 69 6e 20 61 20 72 65 67 75 6c 61 72 2d 65  s in a regular-e
35630 78 70 72 65 73 73 69 6f 6e 20 6d 61 74 63 68 69  xpression matchi
35640 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 20  ng.** function. 
35650 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 76 65 72  The compiled ver
35660 73 69 6f 6e 20 6f 66 20 74 68 65 20 72 65 67 75  sion of the regu
35670 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63  lar expression c
35680 61 6e 20 62 65 20 73 74 6f 72 65 64 20 61 73 0a  an be stored as.
35690 2a 2a 20 6d 65 74 61 64 61 74 61 20 61 73 73 6f  ** metadata asso
356a0 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
356b0 70 61 74 74 65 72 6e 20 73 74 72 69 6e 67 2e 20  pattern string. 
356c0 20 0a 2a 2a 20 54 68 65 6e 20 61 73 20 6c 6f 6e   .** Then as lon
356d0 67 20 61 73 20 74 68 65 20 70 61 74 74 65 72 6e  g as the pattern
356e0 20 73 74 72 69 6e 67 20 72 65 6d 61 69 6e 73 20   string remains 
356f0 74 68 65 20 73 61 6d 65 2c 0a 2a 2a 20 74 68 65  the same,.** the
35700 20 63 6f 6d 70 69 6c 65 64 20 72 65 67 75 6c 61   compiled regula
35710 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61 6e  r expression can
35720 20 62 65 20 72 65 75 73 65 64 20 6f 6e 20 6d 75   be reused on mu
35730 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61  ltiple.** invoca
35740 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d  tions of the sam
35750 65 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a  e function..**.*
35760 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67  * ^The sqlite3_g
35770 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74  et_auxdata() int
35780 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
35790 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
357a0 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f  metadata.** asso
357b0 63 69 61 74 65 64 20 62 79 20 74 68 65 20 73 71  ciated by the sq
357c0 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
357d0 61 28 29 20 66 75 6e 63 74 69 6f 6e 20 77 69 74  a() function wit
357e0 68 20 74 68 65 20 4e 74 68 20 61 72 67 75 6d 65  h the Nth argume
357f0 6e 74 0a 2a 2a 20 76 61 6c 75 65 20 74 6f 20 74  nt.** value to t
35800 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
35810 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e  efined function.
35820 20 5e 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f   ^If there is no
35830 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61 73 73   metadata.** ass
35840 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65  ociated with the
35850 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65   function argume
35860 6e 74 2c 20 74 68 69 73 20 73 71 6c 69 74 65 33  nt, this sqlite3
35870 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 69  _get_auxdata() i
35880 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 65 74 75  nterface.** retu
35890 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  rns a NULL point
358a0 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  er..**.** ^The s
358b0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
358c0 74 61 28 43 2c 4e 2c 50 2c 58 29 20 69 6e 74 65  ta(C,N,P,X) inte
358d0 72 66 61 63 65 20 73 61 76 65 73 20 50 20 61 73  rface saves P as
358e0 20 6d 65 74 61 64 61 74 61 20 66 6f 72 20 74 68   metadata for th
358f0 65 20 4e 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65  e N-th.** argume
35900 6e 74 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  nt of the applic
35910 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
35920 6e 63 74 69 6f 6e 2e 20 20 5e 53 75 62 73 65 71  nction.  ^Subseq
35930 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f  uent.** calls to
35940 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78   sqlite3_get_aux
35950 64 61 74 61 28 43 2c 4e 29 20 72 65 74 75 72 6e  data(C,N) return
35960 20 50 20 66 72 6f 6d 20 74 68 65 20 6d 6f 73 74   P from the most
35970 20 72 65 63 65 6e 74 0a 2a 2a 20 73 71 6c 69 74   recent.** sqlit
35980 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43  e3_set_auxdata(C
35990 2c 4e 2c 50 2c 58 29 20 63 61 6c 6c 20 69 66 20  ,N,P,X) call if 
359a0 74 68 65 20 6d 65 74 61 64 61 74 61 20 69 73 20  the metadata is 
359b0 73 74 69 6c 6c 20 76 61 6c 69 64 20 6f 72 0a 2a  still valid or.*
359c0 2a 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 6d 65  * NULL if the me
359d0 74 61 64 61 74 61 20 68 61 73 20 62 65 65 6e 20  tadata has been 
359e0 64 69 73 63 61 72 64 65 64 2e 0a 2a 2a 20 5e 41  discarded..** ^A
359f0 66 74 65 72 20 65 61 63 68 20 63 61 6c 6c 20 74  fter each call t
35a00 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  o sqlite3_set_au
35a10 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20 77  xdata(C,N,P,X) w
35a20 68 65 72 65 20 58 20 69 73 20 6e 6f 74 20 4e 55  here X is not NU
35a30 4c 4c 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69  LL,.** SQLite wi
35a40 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 65  ll invoke the de
35a50 73 74 72 75 63 74 6f 72 20 66 75 6e 63 74 69 6f  structor functio
35a60 6e 20 58 20 77 69 74 68 20 70 61 72 61 6d 65 74  n X with paramet
35a70 65 72 20 50 20 65 78 61 63 74 6c 79 0a 2a 2a 20  er P exactly.** 
35a80 6f 6e 63 65 2c 20 77 68 65 6e 20 74 68 65 20 6d  once, when the m
35a90 65 74 61 64 61 74 61 20 69 73 20 64 69 73 63 61  etadata is disca
35aa0 72 64 65 64 2e 0a 2a 2a 20 53 51 4c 69 74 65 20  rded..** SQLite 
35ab0 69 73 20 66 72 65 65 20 74 6f 20 64 69 73 63 61  is free to disca
35ac0 72 64 20 74 68 65 20 6d 65 74 61 64 61 74 61 20  rd the metadata 
35ad0 61 74 20 61 6e 79 20 74 69 6d 65 2c 20 69 6e 63  at any time, inc
35ae0 6c 75 64 69 6e 67 3a 20 3c 75 6c 3e 0a 2a 2a 20  luding: <ul>.** 
35af0 3c 6c 69 3e 20 77 68 65 6e 20 74 68 65 20 63 6f  <li> when the co
35b00 72 72 65 73 70 6f 6e 64 69 6e 67 20 66 75 6e 63  rresponding func
35b10 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 63  tion parameter c
35b20 68 61 6e 67 65 73 2c 20 6f 72 0a 2a 2a 20 3c 6c  hanges, or.** <l
35b30 69 3e 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33  i> when [sqlite3
35b40 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71  _reset()] or [sq
35b50 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
35b60 5d 20 69 73 20 63 61 6c 6c 65 64 20 66 6f 72 20  ] is called for 
35b70 74 68 65 0a 2a 2a 20 20 20 20 20 20 53 51 4c 20  the.**      SQL 
35b80 73 74 61 74 65 6d 65 6e 74 2c 20 6f 72 0a 2a 2a  statement, or.**
35b90 20 3c 6c 69 3e 20 77 68 65 6e 20 73 71 6c 69 74   <li> when sqlit
35ba0 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29  e3_set_auxdata()
35bb0 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 67 61 69   is invoked agai
35bc0 6e 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 70 61  n on the same pa
35bd0 72 61 6d 65 74 65 72 2c 20 6f 72 0a 2a 2a 20 3c  rameter, or.** <
35be0 6c 69 3e 20 64 75 72 69 6e 67 20 74 68 65 20 6f  li> during the o
35bf0 72 69 67 69 6e 61 6c 20 73 71 6c 69 74 65 33 5f  riginal sqlite3_
35c00 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 63 61  set_auxdata() ca
35c10 6c 6c 20 77 68 65 6e 20 61 20 6d 65 6d 6f 72 79  ll when a memory
35c20 20 0a 2a 2a 20 20 20 20 20 20 61 6c 6c 6f 63 61   .**      alloca
35c30 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  tion error occur
35c40 73 2e 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a  s. </ul>)^.**.**
35c50 20 4e 6f 74 65 20 74 68 65 20 6c 61 73 74 20 62   Note the last b
35c60 75 6c 6c 65 74 20 69 6e 20 70 61 72 74 69 63 75  ullet in particu
35c70 6c 61 72 2e 20 20 54 68 65 20 64 65 73 74 72 75  lar.  The destru
35c80 63 74 6f 72 20 58 20 69 6e 20 0a 2a 2a 20 73 71  ctor X in .** sq
35c90 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
35ca0 61 28 43 2c 4e 2c 50 2c 58 29 20 6d 69 67 68 74  a(C,N,P,X) might
35cb0 20 62 65 20 63 61 6c 6c 65 64 20 69 6d 6d 65 64   be called immed
35cc0 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 20 74  iately, before t
35cd0 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65  he.** sqlite3_se
35ce0 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 65  t_auxdata() inte
35cf0 72 66 61 63 65 20 65 76 65 6e 20 72 65 74 75 72  rface even retur
35d00 6e 73 2e 20 20 48 65 6e 63 65 20 73 71 6c 69 74  ns.  Hence sqlit
35d10 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29  e3_set_auxdata()
35d20 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 63 61  .** should be ca
35d30 6c 6c 65 64 20 6e 65 61 72 20 74 68 65 20 65 6e  lled near the en
35d40 64 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f  d of the functio
35d50 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
35d60 20 61 6e 64 20 74 68 65 0a 2a 2a 20 66 75 6e 63   and the.** func
35d70 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  tion implementat
35d80 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f 74 20 6d  ion should not m
35d90 61 6b 65 20 61 6e 79 20 75 73 65 20 6f 66 20 50  ake any use of P
35da0 20 61 66 74 65 72 0a 2a 2a 20 73 71 6c 69 74 65   after.** sqlite
35db0 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_set_auxdata() 
35dc0 68 61 73 20 62 65 65 6e 20 63 61 6c 6c 65 64 2e  has been called.
35dd0 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 70 72 61 63  .**.** ^(In prac
35de0 74 69 63 65 2c 20 6d 65 74 61 64 61 74 61 20 69  tice, metadata i
35df0 73 20 70 72 65 73 65 72 76 65 64 20 62 65 74 77  s preserved betw
35e00 65 65 6e 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c  een function cal
35e10 6c 73 20 66 6f 72 0a 2a 2a 20 66 75 6e 63 74 69  ls for.** functi
35e20 6f 6e 20 70 61 72 61 6d 65 74 65 72 73 20 74 68  on parameters th
35e30 61 74 20 61 72 65 20 63 6f 6d 70 69 6c 65 2d 74  at are compile-t
35e40 69 6d 65 20 63 6f 6e 73 74 61 6e 74 73 2c 20 69  ime constants, i
35e50 6e 63 6c 75 64 69 6e 67 20 6c 69 74 65 72 61 6c  ncluding literal
35e60 0a 2a 2a 20 76 61 6c 75 65 73 20 61 6e 64 20 5b  .** values and [
35e70 70 61 72 61 6d 65 74 65 72 73 5d 20 61 6e 64 20  parameters] and 
35e80 65 78 70 72 65 73 73 69 6f 6e 73 20 63 6f 6d 70  expressions comp
35e90 6f 73 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61  osed from the sa
35ea0 6d 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  me.)^.**.** Thes
35eb0 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20  e routines must 
35ec0 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74  be called from t
35ed0 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69  he same thread i
35ee0 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 53  n which.** the S
35ef0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  QL function is r
35f00 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54  unning..*/.SQLIT
35f10 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69  E_API void *sqli
35f20 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28  te3_get_auxdata(
35f30 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
35f40 2c 20 69 6e 74 20 4e 29 3b 0a 53 51 4c 49 54 45  , int N);.SQLITE
35f50 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65  _API void sqlite
35f60 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 73 71  3_set_auxdata(sq
35f70 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
35f80 69 6e 74 20 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f  int N, void*, vo
35f90 69 64 20 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  id (*)(void*));.
35fa0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
35fb0 3a 20 43 6f 6e 73 74 61 6e 74 73 20 44 65 66 69  : Constants Defi
35fc0 6e 69 6e 67 20 53 70 65 63 69 61 6c 20 44 65 73  ning Special Des
35fd0 74 72 75 63 74 6f 72 20 42 65 68 61 76 69 6f 72  tructor Behavior
35fe0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65  .**.** These are
35ff0 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 73 20   special values 
36000 66 6f 72 20 74 68 65 20 64 65 73 74 72 75 63 74  for the destruct
36010 6f 72 20 74 68 61 74 20 69 73 20 70 61 73 73 65  or that is passe
36020 64 20 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66  d in as the.** f
36030 69 6e 61 6c 20 61 72 67 75 6d 65 6e 74 20 74 6f  inal argument to
36040 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b   routines like [
36050 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
36060 6c 6f 62 28 29 5d 2e 20 20 5e 49 66 20 74 68 65  lob()].  ^If the
36070 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 61   destructor.** a
36080 72 67 75 6d 65 6e 74 20 69 73 20 53 51 4c 49 54  rgument is SQLIT
36090 45 5f 53 54 41 54 49 43 2c 20 69 74 20 6d 65 61  E_STATIC, it mea
360a0 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74  ns that the cont
360b0 65 6e 74 20 70 6f 69 6e 74 65 72 20 69 73 20 63  ent pointer is c
360c0 6f 6e 73 74 61 6e 74 0a 2a 2a 20 61 6e 64 20 77  onstant.** and w
360d0 69 6c 6c 20 6e 65 76 65 72 20 63 68 61 6e 67 65  ill never change
360e0 2e 20 20 49 74 20 64 6f 65 73 20 6e 6f 74 20 6e  .  It does not n
360f0 65 65 64 20 74 6f 20 62 65 20 64 65 73 74 72 6f  eed to be destro
36100 79 65 64 2e 20 20 5e 54 68 65 0a 2a 2a 20 53 51  yed.  ^The.** SQ
36110 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 76  LITE_TRANSIENT v
36120 61 6c 75 65 20 6d 65 61 6e 73 20 74 68 61 74 20  alue means that 
36130 74 68 65 20 63 6f 6e 74 65 6e 74 20 77 69 6c 6c  the content will
36140 20 6c 69 6b 65 6c 79 20 63 68 61 6e 67 65 20 69   likely change i
36150 6e 0a 2a 2a 20 74 68 65 20 6e 65 61 72 20 66 75  n.** the near fu
36160 74 75 72 65 20 61 6e 64 20 74 68 61 74 20 53 51  ture and that SQ
36170 4c 69 74 65 20 73 68 6f 75 6c 64 20 6d 61 6b 65  Lite should make
36180 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65   its own private
36190 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20   copy of.** the 
361a0 63 6f 6e 74 65 6e 74 20 62 65 66 6f 72 65 20 72  content before r
361b0 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  eturning..**.** 
361c0 54 68 65 20 74 79 70 65 64 65 66 20 69 73 20 6e  The typedef is n
361d0 65 63 65 73 73 61 72 79 20 74 6f 20 77 6f 72 6b  ecessary to work
361e0 20 61 72 6f 75 6e 64 20 70 72 6f 62 6c 65 6d 73   around problems
361f0 20 69 6e 20 63 65 72 74 61 69 6e 0a 2a 2a 20 43   in certain.** C
36200 2b 2b 20 63 6f 6d 70 69 6c 65 72 73 2e 0a 2a 2f  ++ compilers..*/
36210 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a  .typedef void (*
36220 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74  sqlite3_destruct
36230 6f 72 5f 74 79 70 65 29 28 76 6f 69 64 2a 29 3b  or_type)(void*);
36240 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
36250 53 54 41 54 49 43 20 20 20 20 20 20 28 28 73 71  STATIC      ((sq
36260 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72  lite3_destructor
36270 5f 74 79 70 65 29 30 29 0a 23 64 65 66 69 6e 65  _type)0).#define
36280 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e   SQLITE_TRANSIEN
36290 54 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65  T   ((sqlite3_de
362a0 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 2d 31  structor_type)-1
362b0 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  )../*.** CAPI3RE
362c0 46 3a 20 53 65 74 74 69 6e 67 20 54 68 65 20 52  F: Setting The R
362d0 65 73 75 6c 74 20 4f 66 20 41 6e 20 53 51 4c 20  esult Of An SQL 
362e0 46 75 6e 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 54  Function.**.** T
362f0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
36300 65 20 75 73 65 64 20 62 79 20 74 68 65 20 78 46  e used by the xF
36310 75 6e 63 20 6f 72 20 78 46 69 6e 61 6c 20 63 61  unc or xFinal ca
36320 6c 6c 62 61 63 6b 73 20 74 68 61 74 0a 2a 2a 20  llbacks that.** 
36330 69 6d 70 6c 65 6d 65 6e 74 20 53 51 4c 20 66 75  implement SQL fu
36340 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72  nctions and aggr
36350 65 67 61 74 65 73 2e 20 20 53 65 65 0a 2a 2a 20  egates.  See.** 
36360 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
36370 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20  function()] and 
36380 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
36390 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a  function16()].**
363a0 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
363b0 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
363c0 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f  ** These functio
363d0 6e 73 20 77 6f 72 6b 20 76 65 72 79 20 6d 75 63  ns work very muc
363e0 68 20 6c 69 6b 65 20 74 68 65 20 5b 70 61 72 61  h like the [para
363f0 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 5d 20 66  meter binding] f
36400 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 66 75 6e 63  amily of.** func
36410 74 69 6f 6e 73 20 75 73 65 64 20 74 6f 20 62 69  tions used to bi
36420 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 68 6f 73  nd values to hos
36430 74 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e 20  t parameters in 
36440 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
36450 6e 74 73 2e 0a 2a 2a 20 52 65 66 65 72 20 74 6f  nts..** Refer to
36460 20 74 68 65 20 5b 53 51 4c 20 70 61 72 61 6d 65   the [SQL parame
36470 74 65 72 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69  ter] documentati
36480 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  on for additiona
36490 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  l information..*
364a0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
364b0 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 20  3_result_blob() 
364c0 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74  interface sets t
364d0 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a  he result from.*
364e0 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  * an application
364f0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
36500 6e 20 74 6f 20 62 65 20 74 68 65 20 42 4c 4f 42  n to be the BLOB
36510 20 77 68 6f 73 65 20 63 6f 6e 74 65 6e 74 20 69   whose content i
36520 73 20 70 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f 20  s pointed.** to 
36530 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  by the second pa
36540 72 61 6d 65 74 65 72 20 61 6e 64 20 77 68 69 63  rameter and whic
36550 68 20 69 73 20 4e 20 62 79 74 65 73 20 6c 6f 6e  h is N bytes lon
36560 67 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  g where N is the
36570 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d 65  .** third parame
36580 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ter..**.** ^The 
36590 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a  sqlite3_result_z
365a0 65 72 6f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66  eroblob() interf
365b0 61 63 65 73 20 73 65 74 20 74 68 65 20 72 65 73  aces set the res
365c0 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70  ult of.** the ap
365d0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
365e0 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
365f0 20 61 20 42 4c 4f 42 20 63 6f 6e 74 61 69 6e 69   a BLOB containi
36600 6e 67 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a 20 62  ng all zero.** b
36610 79 74 65 73 20 61 6e 64 20 4e 20 62 79 74 65 73  ytes and N bytes
36620 20 69 6e 20 73 69 7a 65 2c 20 77 68 65 72 65 20   in size, where 
36630 4e 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f  N is the value o
36640 66 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  f the 2nd parame
36650 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ter..**.** ^The 
36660 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64  sqlite3_result_d
36670 6f 75 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63  ouble() interfac
36680 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c  e sets the resul
36690 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70  t from.** an app
366a0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
366b0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
366c0 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  a floating point
366d0 20 76 61 6c 75 65 20 73 70 65 63 69 66 69 65 64   value specified
366e0 0a 2a 2a 20 62 79 20 69 74 73 20 32 6e 64 20 61  .** by its 2nd a
366f0 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e  rgument..**.** ^
36700 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
36710 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73  lt_error() and s
36720 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
36730 72 6f 72 31 36 28 29 20 66 75 6e 63 74 69 6f 6e  ror16() function
36740 73 0a 2a 2a 20 63 61 75 73 65 20 74 68 65 20 69  s.** cause the i
36750 6d 70 6c 65 6d 65 6e 74 65 64 20 53 51 4c 20 66  mplemented SQL f
36760 75 6e 63 74 69 6f 6e 20 74 6f 20 74 68 72 6f 77  unction to throw
36770 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 2e 0a 2a   an exception..*
36780 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 74  * ^SQLite uses t
36790 68 65 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65  he string pointe
367a0 64 20 74 6f 20 62 79 20 74 68 65 0a 2a 2a 20 32  d to by the.** 2
367b0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  nd parameter of 
367c0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
367d0 72 72 6f 72 28 29 20 6f 72 20 73 71 6c 69 74 65  rror() or sqlite
367e0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
367f0 28 29 0a 2a 2a 20 61 73 20 74 68 65 20 74 65 78  ().** as the tex
36800 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 6d 65  t of an error me
36810 73 73 61 67 65 2e 20 20 5e 53 51 4c 69 74 65 20  ssage.  ^SQLite 
36820 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 65  interprets the e
36830 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20  rror.** message 
36840 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69  string from sqli
36850 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
36860 28 29 20 61 73 20 55 54 46 2d 38 2e 20 5e 53 51  () as UTF-8. ^SQ
36870 4c 69 74 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65  Lite.** interpre
36880 74 73 20 74 68 65 20 73 74 72 69 6e 67 20 66 72  ts the string fr
36890 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  om sqlite3_resul
368a0 74 5f 65 72 72 6f 72 31 36 28 29 20 61 73 20 55  t_error16() as U
368b0 54 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 65 0a  TF-16 in native.
368c0 2a 2a 20 62 79 74 65 20 6f 72 64 65 72 2e 20 20  ** byte order.  
368d0 5e 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61  ^If the third pa
368e0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
368f0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
36900 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  ).** or sqlite3_
36910 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
36920 20 69 73 20 6e 65 67 61 74 69 76 65 20 74 68 65   is negative the
36930 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 61  n SQLite takes a
36940 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d  s the error.** m
36950 65 73 73 61 67 65 20 61 6c 6c 20 74 65 78 74 20  essage all text 
36960 75 70 20 74 68 72 6f 75 67 68 20 74 68 65 20 66  up through the f
36970 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63  irst zero charac
36980 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ter..** ^If the 
36990 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
369a0 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  to sqlite3_resul
369b0 74 5f 65 72 72 6f 72 28 29 20 6f 72 0a 2a 2a 20  t_error() or.** 
369c0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
369d0 72 72 6f 72 31 36 28 29 20 69 73 20 6e 6f 6e 2d  rror16() is non-
369e0 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 53 51  negative then SQ
369f0 4c 69 74 65 20 74 61 6b 65 73 20 74 68 61 74 20  Lite takes that 
36a00 6d 61 6e 79 0a 2a 2a 20 62 79 74 65 73 20 28 6e  many.** bytes (n
36a10 6f 74 20 63 68 61 72 61 63 74 65 72 73 29 20 66  ot characters) f
36a20 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61  rom the 2nd para
36a30 6d 65 74 65 72 20 61 73 20 74 68 65 20 65 72 72  meter as the err
36a40 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 20 5e  or message..** ^
36a50 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
36a60 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73  lt_error() and s
36a70 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
36a80 72 6f 72 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69  ror16().** routi
36a90 6e 65 73 20 6d 61 6b 65 20 61 20 70 72 69 76 61  nes make a priva
36aa0 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 65  te copy of the e
36ab0 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78  rror message tex
36ac0 74 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 79  t before.** they
36ad0 20 72 65 74 75 72 6e 2e 20 20 48 65 6e 63 65 2c   return.  Hence,
36ae0 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e   the calling fun
36af0 63 74 69 6f 6e 20 63 61 6e 20 64 65 61 6c 6c 6f  ction can deallo
36b00 63 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66  cate or.** modif
36b10 79 20 74 68 65 20 74 65 78 74 20 61 66 74 65 72  y the text after
36b20 20 74 68 65 79 20 72 65 74 75 72 6e 20 77 69 74   they return wit
36b30 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 54  hout harm..** ^T
36b40 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
36b50 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 29 20 66  t_error_code() f
36b60 75 6e 63 74 69 6f 6e 20 63 68 61 6e 67 65 73 20  unction changes 
36b70 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a  the error code.*
36b80 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 53 51  * returned by SQ
36b90 4c 69 74 65 20 61 73 20 61 20 72 65 73 75 6c 74  Lite as a result
36ba0 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 69 6e 20   of an error in 
36bb0 61 20 66 75 6e 63 74 69 6f 6e 2e 20 20 5e 42 79  a function.  ^By
36bc0 20 64 65 66 61 75 6c 74 2c 0a 2a 2a 20 74 68 65   default,.** the
36bd0 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 53   error code is S
36be0 51 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20 5e 41  QLITE_ERROR.  ^A
36bf0 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
36c00 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75   to sqlite3_resu
36c10 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72  lt_error().** or
36c20 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
36c30 65 72 72 6f 72 31 36 28 29 20 72 65 73 65 74 73  error16() resets
36c40 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20   the error code 
36c50 74 6f 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e  to SQLITE_ERROR.
36c60 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
36c70 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
36c80 5f 74 6f 6f 62 69 67 28 29 20 69 6e 74 65 72 66  _toobig() interf
36c90 61 63 65 20 63 61 75 73 65 73 20 53 51 4c 69 74  ace causes SQLit
36ca0 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 0a 2a 2a  e to throw an.**
36cb0 20 65 72 72 6f 72 20 69 6e 64 69 63 61 74 69 6e   error indicatin
36cc0 67 20 74 68 61 74 20 61 20 73 74 72 69 6e 67 20  g that a string 
36cd0 6f 72 20 42 4c 4f 42 20 69 73 20 74 6f 6f 20 6c  or BLOB is too l
36ce0 6f 6e 67 20 74 6f 20 72 65 70 72 65 73 65 6e 74  ong to represent
36cf0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
36d00 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
36d10 72 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74 65 72 66  r_nomem() interf
36d20 61 63 65 20 63 61 75 73 65 73 20 53 51 4c 69 74  ace causes SQLit
36d30 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 0a 2a 2a  e to throw an.**
36d40 20 65 72 72 6f 72 20 69 6e 64 69 63 61 74 69 6e   error indicatin
36d50 67 20 74 68 61 74 20 61 20 6d 65 6d 6f 72 79 20  g that a memory 
36d60 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 65  allocation faile
36d70 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  d..**.** ^The sq
36d80 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74  lite3_result_int
36d90 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
36da0 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  s the return val
36db0 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70  ue.** of the app
36dc0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
36dd0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
36de0 74 68 65 20 33 32 2d 62 69 74 20 73 69 67 6e 65  the 32-bit signe
36df0 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c  d integer.** val
36e00 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20  ue given in the 
36e10 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  2nd argument..**
36e20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
36e30 73 75 6c 74 5f 69 6e 74 36 34 28 29 20 69 6e 74  sult_int64() int
36e40 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20  erface sets the 
36e50 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20  return value.** 
36e60 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
36e70 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
36e80 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 36 34  ion to be the 64
36e90 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
36ea0 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76  ger.** value giv
36eb0 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72  en in the 2nd ar
36ec0 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54  gument..**.** ^T
36ed0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
36ee0 74 5f 6e 75 6c 6c 28 29 20 69 6e 74 65 72 66 61  t_null() interfa
36ef0 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75  ce sets the retu
36f00 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74  rn value.** of t
36f10 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
36f20 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
36f30 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  to be NULL..**.*
36f40 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
36f50 65 73 75 6c 74 5f 74 65 78 74 28 29 2c 20 73 71  esult_text(), sq
36f60 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
36f70 74 31 36 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65  t16(),.** sqlite
36f80 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c  3_result_text16l
36f90 65 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 65 33  e(), and sqlite3
36fa0 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65  _result_text16be
36fb0 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  () interfaces.**
36fc0 20 73 65 74 20 74 68 65 20 72 65 74 75 72 6e 20   set the return 
36fd0 76 61 6c 75 65 20 6f 66 20 74 68 65 20 61 70 70  value of the app
36fe0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
36ff0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 0a   function to be.
37000 2a 2a 20 61 20 74 65 78 74 20 73 74 72 69 6e 67  ** a text string
37010 20 77 68 69 63 68 20 69 73 20 72 65 70 72 65 73   which is repres
37020 65 6e 74 65 64 20 61 73 20 55 54 46 2d 38 2c 20  ented as UTF-8, 
37030 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79  UTF-16 native by
37040 74 65 20 6f 72 64 65 72 2c 0a 2a 2a 20 55 54 46  te order,.** UTF
37050 2d 31 36 20 6c 69 74 74 6c 65 20 65 6e 64 69 61  -16 little endia
37060 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20 62 69 67  n, or UTF-16 big
37070 20 65 6e 64 69 61 6e 2c 20 72 65 73 70 65 63 74   endian, respect
37080 69 76 65 6c 79 2e 0a 2a 2a 20 5e 54 68 65 20 73  ively..** ^The s
37090 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
370a0 78 74 36 34 28 29 20 69 6e 74 65 72 66 61 63 65  xt64() interface
370b0 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e   sets the return
370c0 20 76 61 6c 75 65 20 6f 66 20 61 6e 0a 2a 2a 20   value of an.** 
370d0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
370e0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
370f0 62 65 20 61 20 74 65 78 74 20 73 74 72 69 6e 67  be a text string
37100 20 69 6e 20 61 6e 20 65 6e 63 6f 64 69 6e 67 0a   in an encoding.
37110 2a 2a 20 73 70 65 63 69 66 69 65 64 20 62 79 20  ** specified by 
37120 74 68 65 20 66 69 66 74 68 20 28 61 6e 64 20 6c  the fifth (and l
37130 61 73 74 29 20 70 61 72 61 6d 65 74 65 72 2c 20  ast) parameter, 
37140 77 68 69 63 68 20 6d 75 73 74 20 62 65 20 6f 6e  which must be on
37150 65 0a 2a 2a 20 6f 66 20 5b 53 51 4c 49 54 45 5f  e.** of [SQLITE_
37160 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55  UTF8], [SQLITE_U
37170 54 46 31 36 5d 2c 20 5b 53 51 4c 49 54 45 5f 55  TF16], [SQLITE_U
37180 54 46 31 36 42 45 5d 2c 20 6f 72 20 5b 53 51 4c  TF16BE], or [SQL
37190 49 54 45 5f 55 54 46 31 36 4c 45 5d 2e 0a 2a 2a  ITE_UTF16LE]..**
371a0 20 5e 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74   ^SQLite takes t
371b0 68 65 20 74 65 78 74 20 72 65 73 75 6c 74 20 66  he text result f
371c0 72 6f 6d 20 74 68 65 20 61 70 70 6c 69 63 61 74  rom the applicat
371d0 69 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20  ion from.** the 
371e0 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66  2nd parameter of
371f0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   the sqlite3_res
37200 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66  ult_text* interf
37210 61 63 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  aces..** ^If the
37220 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74   3rd parameter t
37230 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65  o the sqlite3_re
37240 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72  sult_text* inter
37250 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 65 67 61  faces.** is nega
37260 74 69 76 65 2c 20 74 68 65 6e 20 53 51 4c 69 74  tive, then SQLit
37270 65 20 74 61 6b 65 73 20 72 65 73 75 6c 74 20 74  e takes result t
37280 65 78 74 20 66 72 6f 6d 20 74 68 65 20 32 6e 64  ext from the 2nd
37290 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 68   parameter.** th
372a0 72 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 20  rough the first 
372b0 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a  zero character..
372c0 2a 2a 20 5e 49 66 20 74 68 65 20 33 72 64 20 70  ** ^If the 3rd p
372d0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
372e0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
372f0 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a  ext* interfaces.
37300 2a 2a 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69  ** is non-negati
37310 76 65 2c 20 74 68 65 6e 20 61 73 20 6d 61 6e 79  ve, then as many
37320 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72   bytes (not char
37330 61 63 74 65 72 73 29 20 6f 66 20 74 68 65 20 74  acters) of the t
37340 65 78 74 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74  ext.** pointed t
37350 6f 20 62 79 20 74 68 65 20 32 6e 64 20 70 61 72  o by the 2nd par
37360 61 6d 65 74 65 72 20 61 72 65 20 74 61 6b 65 6e  ameter are taken
37370 20 61 73 20 74 68 65 20 61 70 70 6c 69 63 61 74   as the applicat
37380 69 6f 6e 2d 64 65 66 69 6e 65 64 0a 2a 2a 20 66  ion-defined.** f
37390 75 6e 63 74 69 6f 6e 20 72 65 73 75 6c 74 2e 20  unction result. 
373a0 20 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61   If the 3rd para
373b0 6d 65 74 65 72 20 69 73 20 6e 6f 6e 2d 6e 65 67  meter is non-neg
373c0 61 74 69 76 65 2c 20 74 68 65 6e 20 69 74 0a 2a  ative, then it.*
373d0 2a 20 6d 75 73 74 20 62 65 20 74 68 65 20 62 79  * must be the by
373e0 74 65 20 6f 66 66 73 65 74 20 69 6e 74 6f 20 74  te offset into t
373f0 68 65 20 73 74 72 69 6e 67 20 77 68 65 72 65 20  he string where 
37400 74 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74  the NUL terminat
37410 6f 72 20 77 6f 75 6c 64 0a 2a 2a 20 61 70 70 65  or would.** appe
37420 61 72 20 69 66 20 74 68 65 20 73 74 72 69 6e 67  ar if the string
37430 20 77 68 65 72 65 20 4e 55 4c 20 74 65 72 6d 69   where NUL termi
37440 6e 61 74 65 64 2e 20 20 49 66 20 61 6e 79 20 4e  nated.  If any N
37450 55 4c 20 63 68 61 72 61 63 74 65 72 73 20 6f 63  UL characters oc
37460 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 73 74  cur.** in the st
37470 72 69 6e 67 20 61 74 20 61 20 62 79 74 65 20 6f  ring at a byte o
37480 66 66 73 65 74 20 74 68 61 74 20 69 73 20 6c 65  ffset that is le
37490 73 73 20 74 68 61 6e 20 74 68 65 20 76 61 6c 75  ss than the valu
374a0 65 20 6f 66 20 74 68 65 20 33 72 64 0a 2a 2a 20  e of the 3rd.** 
374b0 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 20  parameter, then 
374c0 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74  the resulting st
374d0 72 69 6e 67 20 77 69 6c 6c 20 63 6f 6e 74 61 69  ring will contai
374e0 6e 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20  n embedded NULs 
374f0 61 6e 64 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c  and the.** resul
37500 74 20 6f 66 20 65 78 70 72 65 73 73 69 6f 6e 73  t of expressions
37510 20 6f 70 65 72 61 74 69 6e 67 20 6f 6e 20 73 74   operating on st
37520 72 69 6e 67 73 20 77 69 74 68 20 65 6d 62 65 64  rings with embed
37530 64 65 64 20 4e 55 4c 73 20 69 73 20 75 6e 64 65  ded NULs is unde
37540 66 69 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68  fined..** ^If th
37550 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 4th parameter 
37560 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72  to the sqlite3_r
37570 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65  esult_text* inte
37580 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c  rfaces.** or sql
37590 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
375a0 20 69 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70   is a non-NULL p
375b0 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c  ointer, then SQL
375c0 69 74 65 20 63 61 6c 6c 73 20 74 68 61 74 0a 2a  ite calls that.*
375d0 2a 20 66 75 6e 63 74 69 6f 6e 20 61 73 20 74 68  * function as th
375e0 65 20 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20  e destructor on 
375f0 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42  the text or BLOB
37600 20 72 65 73 75 6c 74 20 77 68 65 6e 20 69 74 20   result when it 
37610 68 61 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64 20  has.** finished 
37620 75 73 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c  using that resul
37630 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74  t..** ^If the 4t
37640 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
37650 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
37660 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63  t_text* interfac
37670 65 73 20 6f 72 20 74 6f 0a 2a 2a 20 73 71 6c 69  es or to.** sqli
37680 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20  te3_result_blob 
37690 69 73 20 74 68 65 20 73 70 65 63 69 61 6c 20 63  is the special c
376a0 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 53  onstant SQLITE_S
376b0 54 41 54 49 43 2c 20 74 68 65 6e 20 53 51 4c 69  TATIC, then SQLi
376c0 74 65 0a 2a 2a 20 61 73 73 75 6d 65 73 20 74 68  te.** assumes th
376d0 61 74 20 74 68 65 20 74 65 78 74 20 6f 72 20 42  at the text or B
376e0 4c 4f 42 20 72 65 73 75 6c 74 20 69 73 20 69 6e  LOB result is in
376f0 20 63 6f 6e 73 74 61 6e 74 20 73 70 61 63 65 20   constant space 
37700 61 6e 64 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20  and does not.** 
37710 63 6f 70 79 20 74 68 65 20 63 6f 6e 74 65 6e 74  copy the content
37720 20 6f 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   of the paramete
37730 72 20 6e 6f 72 20 63 61 6c 6c 20 61 20 64 65 73  r nor call a des
37740 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 63  tructor on the c
37750 6f 6e 74 65 6e 74 0a 2a 2a 20 77 68 65 6e 20 69  ontent.** when i
37760 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 75  t has finished u
37770 73 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74  sing that result
37780 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68  ..** ^If the 4th
37790 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
377a0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
377b0 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65  _text* interface
377c0 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  s.** or sqlite3_
377d0 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74  result_blob is t
377e0 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74  he special const
377f0 61 6e 74 20 53 51 4c 49 54 45 5f 54 52 41 4e 53  ant SQLITE_TRANS
37800 49 45 4e 54 0a 2a 2a 20 74 68 65 6e 20 53 51 4c  IENT.** then SQL
37810 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79  ite makes a copy
37820 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 69   of the result i
37830 6e 74 6f 20 73 70 61 63 65 20 6f 62 74 61 69 6e  nto space obtain
37840 65 64 20 66 72 6f 6d 0a 2a 2a 20 66 72 6f 6d 20  ed from.** from 
37850 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
37860 29 5d 20 62 65 66 6f 72 65 20 69 74 20 72 65 74  )] before it ret
37870 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  urns..**.** ^The
37880 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
37890 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63  value() interfac
378a0 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c  e sets the resul
378b0 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c  t of.** the appl
378c0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
378d0 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  function to be a
378e0 20 63 6f 70 79 20 74 68 65 0a 2a 2a 20 5b 75 6e   copy the.** [un
378f0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
37900 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
37910 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65  specified by the
37920 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20   2nd parameter. 
37930 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33   ^The.** sqlite3
37940 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20  _result_value() 
37950 69 6e 74 65 72 66 61 63 65 20 6d 61 6b 65 73 20  interface makes 
37960 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73  a copy of the [s
37970 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a  qlite3_value].**
37980 20 73 6f 20 74 68 61 74 20 74 68 65 20 5b 73 71   so that the [sq
37990 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 73 70 65  lite3_value] spe
379a0 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 70 61  cified in the pa
379b0 72 61 6d 65 74 65 72 20 6d 61 79 20 63 68 61 6e  rameter may chan
379c0 67 65 20 6f 72 0a 2a 2a 20 62 65 20 64 65 61 6c  ge or.** be deal
379d0 6c 6f 63 61 74 65 64 20 61 66 74 65 72 20 73 71  located after sq
379e0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
379f0 75 65 28 29 20 72 65 74 75 72 6e 73 20 77 69 74  ue() returns wit
37a00 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 41  hout harm..** ^A
37a10 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
37a20 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
37a30 74 20 6d 61 79 20 61 6c 77 61 79 73 20 62 65 20  t may always be 
37a40 75 73 65 64 20 77 68 65 72 65 20 61 6e 0a 2a 2a  used where an.**
37a50 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   [unprotected sq
37a60 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
37a70 65 63 74 20 69 73 20 72 65 71 75 69 72 65 64 2c  ect is required,
37a80 20 73 6f 20 65 69 74 68 65 72 0a 2a 2a 20 6b 69   so either.** ki
37a90 6e 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 76  nd of [sqlite3_v
37aa0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 63 61 6e  alue] object can
37ab0 20 62 65 20 75 73 65 64 20 77 69 74 68 20 74 68   be used with th
37ac0 69 73 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  is interface..**
37ad0 0a 2a 2a 20 49 66 20 74 68 65 73 65 20 72 6f 75  .** If these rou
37ae0 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64  tines are called
37af0 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 74 68 65   from within the
37b00 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61   different threa
37b10 64 0a 2a 2a 20 74 68 61 6e 20 74 68 65 20 6f 6e  d.** than the on
37b20 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  e containing the
37b30 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
37b40 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 68  ined function th
37b50 61 74 20 72 65 63 65 69 76 65 64 0a 2a 2a 20 74  at received.** t
37b60 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74  he [sqlite3_cont
37b70 65 78 74 5d 20 70 6f 69 6e 74 65 72 2c 20 74 68  ext] pointer, th
37b80 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e  e results are un
37b90 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 53 51 4c 49  defined..*/.SQLI
37ba0 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69  TE_API void sqli
37bb0 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28  te3_result_blob(
37bc0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
37bd0 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
37be0 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64  nt, void(*)(void
37bf0 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  *));.SQLITE_API 
37c00 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
37c10 75 6c 74 5f 62 6c 6f 62 36 34 28 73 71 6c 69 74  ult_blob64(sqlit
37c20 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 63 6f 6e 73  e3_context*,cons
37c30 74 20 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f  t void*,sqlite3_
37c40 75 69 6e 74 36 34 2c 76 6f 69 64 28 2a 29 28 76  uint64,void(*)(v
37c50 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41  oid*));.SQLITE_A
37c60 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  PI void sqlite3_
37c70 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 73 71  result_double(sq
37c80 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
37c90 64 6f 75 62 6c 65 29 3b 0a 53 51 4c 49 54 45 5f  double);.SQLITE_
37ca0 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33  API void sqlite3
37cb0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 73 71  _result_error(sq
37cc0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
37cd0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74  const char*, int
37ce0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  );.SQLITE_API vo
37cf0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
37d00 74 5f 65 72 72 6f 72 31 36 28 73 71 6c 69 74 65  t_error16(sqlite
37d10 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
37d20 74 20 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 53  t void*, int);.S
37d30 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73  QLITE_API void s
37d40 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
37d50 72 6f 72 5f 74 6f 6f 62 69 67 28 73 71 6c 69 74  ror_toobig(sqlit
37d60 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51  e3_context*);.SQ
37d70 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71  LITE_API void sq
37d80 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
37d90 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c 69 74 65 33  or_nomem(sqlite3
37da0 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49  _context*);.SQLI
37db0 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69  TE_API void sqli
37dc0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
37dd0 5f 63 6f 64 65 28 73 71 6c 69 74 65 33 5f 63 6f  _code(sqlite3_co
37de0 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 53 51  ntext*, int);.SQ
37df0 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71  LITE_API void sq
37e00 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74  lite3_result_int
37e10 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
37e20 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f  *, int);.SQLITE_
37e30 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33  API void sqlite3
37e40 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 73 71  _result_int64(sq
37e50 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
37e60 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a  sqlite3_int64);.
37e70 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
37e80 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e  sqlite3_result_n
37e90 75 6c 6c 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ull(sqlite3_cont
37ea0 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  ext*);.SQLITE_AP
37eb0 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  I void sqlite3_r
37ec0 65 73 75 6c 74 5f 74 65 78 74 28 73 71 6c 69 74  esult_text(sqlit
37ed0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
37ee0 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 2c 20 76  st char*, int, v
37ef0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
37f00 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
37f10 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
37f20 65 78 74 36 34 28 73 71 6c 69 74 65 33 5f 63 6f  ext64(sqlite3_co
37f30 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68  ntext*, const ch
37f40 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74  ar*,sqlite3_uint
37f50 36 34 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  64,.            
37f60 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76                 v
37f70 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 2c 20 75  oid(*)(void*), u
37f80 6e 73 69 67 6e 65 64 20 63 68 61 72 20 65 6e 63  nsigned char enc
37f90 6f 64 69 6e 67 29 3b 0a 53 51 4c 49 54 45 5f 41  oding);.SQLITE_A
37fa0 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  PI void sqlite3_
37fb0 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 73 71  result_text16(sq
37fc0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
37fd0 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
37fe0 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
37ff0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  );.SQLITE_API vo
38000 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
38010 74 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74  t_text16le(sqlit
38020 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
38030 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f  st void*, int,vo
38040 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53  id(*)(void*));.S
38050 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73  QLITE_API void s
38060 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
38070 78 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f 63  xt16be(sqlite3_c
38080 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76  ontext*, const v
38090 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a  oid*, int,void(*
380a0 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54  )(void*));.SQLIT
380b0 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74  E_API void sqlit
380c0 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
380d0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
380e0 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  , sqlite3_value*
380f0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  );.SQLITE_API vo
38100 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
38110 74 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74  t_zeroblob(sqlit
38120 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74  e3_context*, int
38130 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49   n);../*.** CAPI
38140 33 52 45 46 3a 20 44 65 66 69 6e 65 20 4e 65 77  3REF: Define New
38150 20 43 6f 6c 6c 61 74 69 6e 67 20 53 65 71 75 65   Collating Seque
38160 6e 63 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  nces.**.** ^Thes
38170 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 64 64 2c  e functions add,
38180 20 72 65 6d 6f 76 65 2c 20 6f 72 20 6d 6f 64 69   remove, or modi
38190 66 79 20 61 20 5b 63 6f 6c 6c 61 74 69 6f 6e 5d  fy a [collation]
381a0 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77   associated.** w
381b0 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73  ith the [databas
381c0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70  e connection] sp
381d0 65 63 69 66 69 65 64 20 61 73 20 74 68 65 20 66  ecified as the f
381e0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  irst argument..*
381f0 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f  *.** ^The name o
38200 66 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20  f the collation 
38210 69 73 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e  is a UTF-8 strin
38220 67 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65 33  g.** for sqlite3
38230 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
38240 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  n() and sqlite3_
38250 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
38260 5f 76 32 28 29 0a 2a 2a 20 61 6e 64 20 61 20 55  _v2().** and a U
38270 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20  TF-16 string in 
38280 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
38290 72 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72  r for sqlite3_cr
382a0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36  eate_collation16
382b0 28 29 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6f  ()..** ^Collatio
382c0 6e 20 6e 61 6d 65 73 20 74 68 61 74 20 63 6f 6d  n names that com
382d0 70 61 72 65 20 65 71 75 61 6c 20 61 63 63 6f 72  pare equal accor
382e0 64 69 6e 67 20 74 6f 20 5b 73 71 6c 69 74 65 33  ding to [sqlite3
382f0 5f 73 74 72 6e 69 63 6d 70 28 29 5d 20 61 72 65  _strnicmp()] are
38300 0a 2a 2a 20 63 6f 6e 73 69 64 65 72 65 64 20 74  .** considered t
38310 6f 20 62 65 20 74 68 65 20 73 61 6d 65 20 6e 61  o be the same na
38320 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  me..**.** ^(The 
38330 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 28  third argument (
38340 65 54 65 78 74 52 65 70 29 20 6d 75 73 74 20 62  eTextRep) must b
38350 65 20 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f 6e  e one of the con
38360 73 74 61 6e 74 73 3a 0a 2a 2a 20 3c 75 6c 3e 0a  stants:.** <ul>.
38370 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
38380 55 54 46 38 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  UTF8],.** <li> [
38390 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c  SQLITE_UTF16LE],
383a0 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
383b0 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 3c 6c  _UTF16BE],.** <l
383c0 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  i> [SQLITE_UTF16
383d0 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  ], or.** <li> [S
383e0 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47  QLITE_UTF16_ALIG
383f0 4e 45 44 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e  NED]..** </ul>)^
38400 0a 2a 2a 20 5e 54 68 65 20 65 54 65 78 74 52 65  .** ^The eTextRe
38410 70 20 61 72 67 75 6d 65 6e 74 20 64 65 74 65 72  p argument deter
38420 6d 69 6e 65 73 20 74 68 65 20 65 6e 63 6f 64 69  mines the encodi
38430 6e 67 20 6f 66 20 73 74 72 69 6e 67 73 20 70 61  ng of strings pa
38440 73 73 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20 63  ssed.** to the c
38450 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
38460 6e 20 63 61 6c 6c 62 61 63 6b 2c 20 78 43 61 6c  n callback, xCal
38470 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 54 68 65 20 5b  lback..** ^The [
38480 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 20 61 6e  SQLITE_UTF16] an
38490 64 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f  d [SQLITE_UTF16_
384a0 41 4c 49 47 4e 45 44 5d 20 76 61 6c 75 65 73 20  ALIGNED] values 
384b0 66 6f 72 20 65 54 65 78 74 52 65 70 0a 2a 2a 20  for eTextRep.** 
384c0 66 6f 72 63 65 20 73 74 72 69 6e 67 73 20 74 6f  force strings to
384d0 20 62 65 20 55 54 46 31 36 20 77 69 74 68 20 6e   be UTF16 with n
384e0 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
384f0 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ..** ^The [SQLIT
38500 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d  E_UTF16_ALIGNED]
38510 20 76 61 6c 75 65 20 66 6f 72 20 65 54 65 78 74   value for eText
38520 52 65 70 20 66 6f 72 63 65 73 20 73 74 72 69 6e  Rep forces strin
38530 67 73 20 74 6f 20 62 65 67 69 6e 0a 2a 2a 20 6f  gs to begin.** o
38540 6e 20 61 6e 20 65 76 65 6e 20 62 79 74 65 20 61  n an even byte a
38550 64 64 72 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ddress..**.** ^T
38560 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  he fourth argume
38570 6e 74 2c 20 70 41 72 67 2c 20 69 73 20 61 6e 20  nt, pArg, is an 
38580 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61  application data
38590 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73   pointer that is
385a0 20 70 61 73 73 65 64 0a 2a 2a 20 74 68 72 6f 75   passed.** throu
385b0 67 68 20 61 73 20 74 68 65 20 66 69 72 73 74 20  gh as the first 
385c0 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
385d0 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
385e0 6f 6e 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a  on callback..**.
385f0 2a 2a 20 5e 54 68 65 20 66 69 66 74 68 20 61 72  ** ^The fifth ar
38600 67 75 6d 65 6e 74 2c 20 78 43 61 6c 6c 62 61 63  gument, xCallbac
38610 6b 2c 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  k, is a pointer 
38620 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67  to the collating
38630 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 5e 4d   function..** ^M
38640 75 6c 74 69 70 6c 65 20 63 6f 6c 6c 61 74 69 6e  ultiple collatin
38650 67 20 66 75 6e 63 74 69 6f 6e 73 20 63 61 6e 20  g functions can 
38660 62 65 20 72 65 67 69 73 74 65 72 65 64 20 75 73  be registered us
38670 69 6e 67 20 74 68 65 20 73 61 6d 65 20 6e 61 6d  ing the same nam
38680 65 20 62 75 74 0a 2a 2a 20 77 69 74 68 20 64 69  e but.** with di
38690 66 66 65 72 65 6e 74 20 65 54 65 78 74 52 65 70  fferent eTextRep
386a0 20 70 61 72 61 6d 65 74 65 72 73 20 61 6e 64 20   parameters and 
386b0 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20  SQLite will use 
386c0 77 68 69 63 68 65 76 65 72 0a 2a 2a 20 66 75 6e  whichever.** fun
386d0 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 74  ction requires t
386e0 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20  he least amount 
386f0 6f 66 20 64 61 74 61 20 74 72 61 6e 73 66 6f 72  of data transfor
38700 6d 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74  mation..** ^If t
38710 68 65 20 78 43 61 6c 6c 62 61 63 6b 20 61 72 67  he xCallback arg
38720 75 6d 65 6e 74 20 69 73 20 4e 55 4c 4c 20 74 68  ument is NULL th
38730 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67  en the collating
38740 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20   function is.** 
38750 64 65 6c 65 74 65 64 2e 20 20 5e 57 68 65 6e 20  deleted.  ^When 
38760 61 6c 6c 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  all collating fu
38770 6e 63 74 69 6f 6e 73 20 68 61 76 69 6e 67 20 74  nctions having t
38780 68 65 20 73 61 6d 65 20 6e 61 6d 6