System.Data.SQLite
Hex Artifact Content
Not logged in

Artifact c645adc28279d322d277558abe23710138c9fd5a:


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 31 2e 20 20 42  ersion 3.8.1.  B
00b0: 79 20 63 6f 6d 62 69 6e 69 6e 67 20 61 6c 6c 20  y combining all 
00c0: 74 68 65 20 69 6e 64 69 76 69 64 75 61 6c 20 43  the individual C
00d0: 20 63 6f 64 65 20 66 69 6c 65 73 20 69 6e 74 6f   code files into
00e0: 20 74 68 69 73 20 0a 2a 2a 20 73 69 6e 67 6c 65   this .** single
00f0: 20 6c 61 72 67 65 20 66 69 6c 65 2c 20 74 68 65   large file, the
0100: 20 65 6e 74 69 72 65 20 63 6f 64 65 20 63 61 6e   entire code can
0110: 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 61 73 20   be compiled as 
0120: 61 20 73 69 6e 67 6c 65 20 74 72 61 6e 73 6c 61  a single transla
0130: 74 69 6f 6e 0a 2a 2a 20 75 6e 69 74 2e 20 20 54  tion.** unit.  T
0140: 68 69 73 20 61 6c 6c 6f 77 73 20 6d 61 6e 79 20  his allows many 
0150: 63 6f 6d 70 69 6c 65 72 73 20 74 6f 20 64 6f 20  compilers to do 
0160: 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 73 20 74 68  optimizations th
0170: 61 74 20 77 6f 75 6c 64 20 6e 6f 74 20 62 65 0a  at would not be.
0180: 2a 2a 20 70 6f 73 73 69 62 6c 65 20 69 66 20 74  ** possible if t
0190: 68 65 20 66 69 6c 65 73 20 77 65 72 65 20 63 6f  he files were co
01a0: 6d 70 69 6c 65 64 20 73 65 70 61 72 61 74 65 6c  mpiled separatel
01b0: 79 2e 20 20 50 65 72 66 6f 72 6d 61 6e 63 65 20  y.  Performance 
01c0: 69 6d 70 72 6f 76 65 6d 65 6e 74 73 0a 2a 2a 20  improvements.** 
01d0: 6f 66 20 35 25 20 6f 72 20 6d 6f 72 65 20 61 72  of 5% or more ar
01e0: 65 20 63 6f 6d 6d 6f 6e 6c 79 20 73 65 65 6e 20  e commonly seen 
01f0: 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63  when SQLite is c
0200: 6f 6d 70 69 6c 65 64 20 61 73 20 61 20 73 69 6e  ompiled as a sin
0210: 67 6c 65 0a 2a 2a 20 74 72 61 6e 73 6c 61 74 69  gle.** translati
0220: 6f 6e 20 75 6e 69 74 2e 0a 2a 2a 0a 2a 2a 20 54  on unit..**.** T
0230: 68 69 73 20 66 69 6c 65 20 69 73 20 61 6c 6c 20  his file is all 
0240: 79 6f 75 20 6e 65 65 64 20 74 6f 20 63 6f 6d 70  you need to comp
0250: 69 6c 65 20 53 51 4c 69 74 65 2e 20 20 54 6f 20  ile SQLite.  To 
0260: 75 73 65 20 53 51 4c 69 74 65 20 69 6e 20 6f 74  use SQLite in ot
0270: 68 65 72 0a 2a 2a 20 70 72 6f 67 72 61 6d 73 2c  her.** programs,
0280: 20 79 6f 75 20 6e 65 65 64 20 74 68 69 73 20 66   you need this f
0290: 69 6c 65 20 61 6e 64 20 74 68 65 20 22 73 71 6c  ile and the "sql
02a0: 69 74 65 33 2e 68 22 20 68 65 61 64 65 72 20 66  ite3.h" header f
02b0: 69 6c 65 20 74 68 61 74 20 64 65 66 69 6e 65 73  ile that defines
02c0: 0a 2a 2a 20 74 68 65 20 70 72 6f 67 72 61 6d 6d  .** the programm
02d0: 69 6e 67 20 69 6e 74 65 72 66 61 63 65 20 74 6f  ing interface to
02e0: 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72   the SQLite libr
02f0: 61 72 79 2e 20 20 28 49 66 20 79 6f 75 20 64 6f  ary.  (If you do
0300: 20 6e 6f 74 20 68 61 76 65 20 0a 2a 2a 20 74 68   not have .** th
0310: 65 20 22 73 71 6c 69 74 65 33 2e 68 22 20 68 65  e "sqlite3.h" he
0320: 61 64 65 72 20 66 69 6c 65 20 61 74 20 68 61 6e  ader file at han
0330: 64 2c 20 79 6f 75 20 77 69 6c 6c 20 66 69 6e 64  d, you will find
0340: 20 61 20 63 6f 70 79 20 65 6d 62 65 64 64 65 64   a copy embedded
0350: 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20 74   within.** the t
0360: 65 78 74 20 6f 66 20 74 68 69 73 20 66 69 6c 65  ext of this file
0370: 2e 20 20 53 65 61 72 63 68 20 66 6f 72 20 22 42  .  Search for "B
0380: 65 67 69 6e 20 66 69 6c 65 20 73 71 6c 69 74 65  egin file sqlite
0390: 33 2e 68 22 20 74 6f 20 66 69 6e 64 20 74 68 65  3.h" to find the
03a0: 20 73 74 61 72 74 0a 2a 2a 20 6f 66 20 74 68 65   start.** of the
03b0: 20 65 6d 62 65 64 64 65 64 20 73 71 6c 69 74 65   embedded sqlite
03c0: 33 2e 68 20 68 65 61 64 65 72 20 66 69 6c 65 2e  3.h header file.
03d0: 29 20 41 64 64 69 74 69 6f 6e 61 6c 20 63 6f 64  ) Additional cod
03e0: 65 20 66 69 6c 65 73 20 6d 61 79 20 62 65 20 6e  e files may be n
03f0: 65 65 64 65 64 0a 2a 2a 20 69 66 20 79 6f 75 20  eeded.** if you 
0400: 77 61 6e 74 20 61 20 77 72 61 70 70 65 72 20 74  want a wrapper t
0410: 6f 20 69 6e 74 65 72 66 61 63 65 20 53 51 4c 69  o interface SQLi
0420: 74 65 20 77 69 74 68 20 79 6f 75 72 20 63 68 6f  te with your cho
0430: 69 63 65 20 6f 66 20 70 72 6f 67 72 61 6d 6d 69  ice of programmi
0440: 6e 67 0a 2a 2a 20 6c 61 6e 67 75 61 67 65 2e 20  ng.** language. 
0450: 54 68 65 20 63 6f 64 65 20 66 6f 72 20 74 68 65  The code for the
0460: 20 22 73 71 6c 69 74 65 33 22 20 63 6f 6d 6d 61   "sqlite3" comma
0470: 6e 64 2d 6c 69 6e 65 20 73 68 65 6c 6c 20 69 73  nd-line shell is
0480: 20 61 6c 73 6f 20 69 6e 20 61 0a 2a 2a 20 73 65   also in a.** se
0490: 70 61 72 61 74 65 20 66 69 6c 65 2e 20 54 68 69  parate file. Thi
04a0: 73 20 66 69 6c 65 20 63 6f 6e 74 61 69 6e 73 20  s file contains 
04b0: 6f 6e 6c 79 20 63 6f 64 65 20 66 6f 72 20 74 68  only code for th
04c0: 65 20 63 6f 72 65 20 53 51 4c 69 74 65 20 6c 69  e core SQLite li
04d0: 62 72 61 72 79 2e 0a 2a 2f 0a 23 64 65 66 69 6e  brary..*/.#defin
04e0: 65 20 53 51 4c 49 54 45 5f 43 4f 52 45 20 31 0a  e SQLITE_CORE 1.
04f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
0500: 4d 41 4c 47 41 4d 41 54 49 4f 4e 20 31 0a 23 69  MALGAMATION 1.#i
0510: 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 50 52 49  fndef SQLITE_PRI
0520: 56 41 54 45 0a 23 20 64 65 66 69 6e 65 20 53 51  VATE.# define SQ
0530: 4c 49 54 45 5f 50 52 49 56 41 54 45 20 73 74 61  LITE_PRIVATE sta
0540: 74 69 63 0a 23 65 6e 64 69 66 0a 23 69 66 6e 64  tic.#endif.#ifnd
0550: 65 66 20 53 51 4c 49 54 45 5f 41 50 49 0a 23 20  ef SQLITE_API.# 
0560: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 50  define SQLITE_AP
0570: 49 0a 23 65 6e 64 69 66 0a 2f 2a 2a 2a 2a 2a 2a  I.#endif./******
0580: 2a 2a 2a 2a 2a 2a 2a 2a 20 42 65 67 69 6e 20 66  ******** Begin f
0590: 69 6c 65 20 73 71 6c 69 74 65 49 6e 74 2e 68 20  ile sqliteInt.h 
05a0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
05b0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
05c0: 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a 0a 2a 2a 20 32  *******/./*.** 2
05d0: 30 30 31 20 53 65 70 74 65 6d 62 65 72 20 31 35  001 September 15
05e0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f  .**.** The autho
05f0: 72 20 64 69 73 63 6c 61 69 6d 73 20 63 6f 70 79  r disclaims copy
0600: 72 69 67 68 74 20 74 6f 20 74 68 69 73 20 73 6f  right to this so
0610: 75 72 63 65 20 63 6f 64 65 2e 20 20 49 6e 20 70  urce code.  In p
0620: 6c 61 63 65 20 6f 66 0a 2a 2a 20 61 20 6c 65 67  lace of.** a leg
0630: 61 6c 20 6e 6f 74 69 63 65 2c 20 68 65 72 65 20  al notice, here 
0640: 69 73 20 61 20 62 6c 65 73 73 69 6e 67 3a 0a 2a  is a blessing:.*
0650: 2a 0a 2a 2a 20 20 20 20 4d 61 79 20 79 6f 75 20  *.**    May you 
0660: 64 6f 20 67 6f 6f 64 20 61 6e 64 20 6e 6f 74 20  do good and not 
0670: 65 76 69 6c 2e 0a 2a 2a 20 20 20 20 4d 61 79 20  evil..**    May 
0680: 79 6f 75 20 66 69 6e 64 20 66 6f 72 67 69 76 65  you find forgive
0690: 6e 65 73 73 20 66 6f 72 20 79 6f 75 72 73 65 6c  ness for yoursel
06a0: 66 20 61 6e 64 20 66 6f 72 67 69 76 65 20 6f 74  f and forgive ot
06b0: 68 65 72 73 2e 0a 2a 2a 20 20 20 20 4d 61 79 20  hers..**    May 
06c0: 79 6f 75 20 73 68 61 72 65 20 66 72 65 65 6c 79  you share freely
06d0: 2c 20 6e 65 76 65 72 20 74 61 6b 69 6e 67 20 6d  , never taking m
06e0: 6f 72 65 20 74 68 61 6e 20 79 6f 75 20 67 69 76  ore than you giv
06f0: 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  e..**.**********
0700: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0710: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0720: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0730: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a  ***************.
0740: 2a 2a 20 49 6e 74 65 72 6e 61 6c 20 69 6e 74 65  ** Internal inte
0750: 72 66 61 63 65 20 64 65 66 69 6e 69 74 69 6f 6e  rface definition
0760: 73 20 66 6f 72 20 53 51 4c 69 74 65 2e 0a 2a 2a  s for SQLite..**
0770: 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53 51 4c  .*/.#ifndef _SQL
0780: 49 54 45 49 4e 54 5f 48 5f 0a 23 64 65 66 69 6e  ITEINT_H_.#defin
0790: 65 20 5f 53 51 4c 49 54 45 49 4e 54 5f 48 5f 0a  e _SQLITEINT_H_.
07a0: 0a 2f 2a 0a 2a 2a 20 54 68 65 73 65 20 23 64 65  ./*.** These #de
07b0: 66 69 6e 65 73 20 73 68 6f 75 6c 64 20 65 6e 61  fines should ena
07c0: 62 6c 65 20 3e 32 47 42 20 66 69 6c 65 20 73 75  ble >2GB file su
07d0: 70 70 6f 72 74 20 6f 6e 20 50 4f 53 49 58 20 69  pport on POSIX i
07e0: 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79  f the.** underly
07f0: 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79  ing operating sy
0800: 73 74 65 6d 20 73 75 70 70 6f 72 74 73 20 69 74  stem supports it
0810: 2e 20 20 49 66 20 74 68 65 20 4f 53 20 6c 61 63  .  If the OS lac
0820: 6b 73 0a 2a 2a 20 6c 61 72 67 65 20 66 69 6c 65  ks.** large file
0830: 20 73 75 70 70 6f 72 74 2c 20 6f 72 20 69 66 20   support, or if 
0840: 74 68 65 20 4f 53 20 69 73 20 77 69 6e 64 6f 77  the OS is window
0850: 73 2c 20 74 68 65 73 65 20 73 68 6f 75 6c 64 20  s, these should 
0860: 62 65 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 0a 2a 2a  be no-ops..**.**
0870: 20 54 69 63 6b 65 74 20 23 32 37 33 39 3a 20 20   Ticket #2739:  
0880: 54 68 65 20 5f 4c 41 52 47 45 46 49 4c 45 5f 53  The _LARGEFILE_S
0890: 4f 55 52 43 45 20 6d 61 63 72 6f 20 6d 75 73 74  OURCE macro must
08a0: 20 61 70 70 65 61 72 20 62 65 66 6f 72 65 20 61   appear before a
08b0: 6e 79 0a 2a 2a 20 73 79 73 74 65 6d 20 23 69 6e  ny.** system #in
08c0: 63 6c 75 64 65 73 2e 20 20 48 65 6e 63 65 2c 20  cludes.  Hence, 
08d0: 74 68 69 73 20 62 6c 6f 63 6b 20 6f 66 20 63 6f  this block of co
08e0: 64 65 20 6d 75 73 74 20 62 65 20 74 68 65 20 76  de must be the v
08f0: 65 72 79 20 66 69 72 73 74 0a 2a 2a 20 63 6f 64  ery first.** cod
0900: 65 20 69 6e 20 61 6c 6c 20 73 6f 75 72 63 65 20  e in all source 
0910: 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 4c 61 72  files..**.** Lar
0920: 67 65 20 66 69 6c 65 20 73 75 70 70 6f 72 74 20  ge file support 
0930: 63 61 6e 20 62 65 20 64 69 73 61 62 6c 65 64 20  can be disabled 
0940: 75 73 69 6e 67 20 74 68 65 20 2d 44 53 51 4c 49  using the -DSQLI
0950: 54 45 5f 44 49 53 41 42 4c 45 5f 4c 46 53 20 73  TE_DISABLE_LFS s
0960: 77 69 74 63 68 0a 2a 2a 20 6f 6e 20 74 68 65 20  witch.** on the 
0970: 63 6f 6d 70 69 6c 65 72 20 63 6f 6d 6d 61 6e 64  compiler command
0980: 20 6c 69 6e 65 2e 20 20 54 68 69 73 20 69 73 20   line.  This is 
0990: 6e 65 63 65 73 73 61 72 79 20 69 66 20 79 6f 75  necessary if you
09a0: 20 61 72 65 20 63 6f 6d 70 69 6c 69 6e 67 0a 2a   are compiling.*
09b0: 2a 20 6f 6e 20 61 20 72 65 63 65 6e 74 20 6d 61  * on a recent ma
09c0: 63 68 69 6e 65 20 28 65 78 3a 20 52 65 64 20 48  chine (ex: Red H
09d0: 61 74 20 37 2e 32 29 20 62 75 74 20 79 6f 75 20  at 7.2) but you 
09e0: 77 61 6e 74 20 79 6f 75 72 20 63 6f 64 65 20 74  want your code t
09f0: 6f 20 77 6f 72 6b 0a 2a 2a 20 6f 6e 20 61 6e 20  o work.** on an 
0a00: 6f 6c 64 65 72 20 6d 61 63 68 69 6e 65 20 28 65  older machine (e
0a10: 78 3a 20 52 65 64 20 48 61 74 20 36 2e 30 29 2e  x: Red Hat 6.0).
0a20: 20 20 49 66 20 79 6f 75 20 63 6f 6d 70 69 6c 65    If you compile
0a30: 20 6f 6e 20 52 65 64 20 48 61 74 20 37 2e 32 0a   on Red Hat 7.2.
0a40: 2a 2a 20 77 69 74 68 6f 75 74 20 74 68 69 73 20  ** without this 
0a50: 6f 70 74 69 6f 6e 2c 20 4c 46 53 20 69 73 20 65  option, LFS is e
0a60: 6e 61 62 6c 65 2e 20 20 42 75 74 20 4c 46 53 20  nable.  But LFS 
0a70: 64 6f 65 73 20 6e 6f 74 20 65 78 69 73 74 20 69  does not exist i
0a80: 6e 20 74 68 65 20 6b 65 72 6e 65 6c 0a 2a 2a 20  n the kernel.** 
0a90: 69 6e 20 52 65 64 20 48 61 74 20 36 2e 30 2c 20  in Red Hat 6.0, 
0aa0: 73 6f 20 74 68 65 20 63 6f 64 65 20 77 6f 6e 27  so the code won'
0ab0: 74 20 77 6f 72 6b 2e 20 20 48 65 6e 63 65 2c 20  t work.  Hence, 
0ac0: 66 6f 72 20 6d 61 78 69 6d 75 6d 20 62 69 6e 61  for maximum bina
0ad0: 72 79 0a 2a 2a 20 70 6f 72 74 61 62 69 6c 69 74  ry.** portabilit
0ae0: 79 20 79 6f 75 20 73 68 6f 75 6c 64 20 6f 6d 69  y you should omi
0af0: 74 20 4c 46 53 2e 0a 2a 2a 0a 2a 2a 20 53 69 6d  t LFS..**.** Sim
0b00: 69 6c 61 72 20 69 73 20 74 72 75 65 20 66 6f 72  ilar is true for
0b10: 20 4d 61 63 20 4f 53 20 58 2e 20 20 4c 46 53 20   Mac OS X.  LFS 
0b20: 69 73 20 6f 6e 6c 79 20 73 75 70 70 6f 72 74 65  is only supporte
0b30: 64 20 6f 6e 20 4d 61 63 20 4f 53 20 58 20 39 20  d on Mac OS X 9 
0b40: 61 6e 64 20 6c 61 74 65 72 2e 0a 2a 2f 0a 23 69  and later..*/.#i
0b50: 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 44 49 53  fndef SQLITE_DIS
0b60: 41 42 4c 45 5f 4c 46 53 0a 23 20 64 65 66 69 6e  ABLE_LFS.# defin
0b70: 65 20 5f 4c 41 52 47 45 5f 46 49 4c 45 20 20 20  e _LARGE_FILE   
0b80: 20 20 20 20 31 0a 23 20 69 66 6e 64 65 66 20 5f      1.# ifndef _
0b90: 46 49 4c 45 5f 4f 46 46 53 45 54 5f 42 49 54 53  FILE_OFFSET_BITS
0ba0: 0a 23 20 20 20 64 65 66 69 6e 65 20 5f 46 49 4c  .#   define _FIL
0bb0: 45 5f 4f 46 46 53 45 54 5f 42 49 54 53 20 36 34  E_OFFSET_BITS 64
0bc0: 0a 23 20 65 6e 64 69 66 0a 23 20 64 65 66 69 6e  .# endif.# defin
0bd0: 65 20 5f 4c 41 52 47 45 46 49 4c 45 5f 53 4f 55  e _LARGEFILE_SOU
0be0: 52 43 45 20 31 0a 23 65 6e 64 69 66 0a 0a 2f 2a  RCE 1.#endif../*
0bf0: 0a 2a 2a 20 49 6e 63 6c 75 64 65 20 74 68 65 20  .** Include the 
0c00: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 68 65  configuration he
0c10: 61 64 65 72 20 6f 75 74 70 75 74 20 62 79 20 27  ader output by '
0c20: 63 6f 6e 66 69 67 75 72 65 27 20 69 66 20 77 65  configure' if we
0c30: 27 72 65 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a  're using the.**
0c40: 20 61 75 74 6f 63 6f 6e 66 2d 62 61 73 65 64 20   autoconf-based 
0c50: 62 75 69 6c 64 0a 2a 2f 0a 23 69 66 64 65 66 20  build.*/.#ifdef 
0c60: 5f 48 41 56 45 5f 53 51 4c 49 54 45 5f 43 4f 4e  _HAVE_SQLITE_CON
0c70: 46 49 47 5f 48 0a 23 69 6e 63 6c 75 64 65 20 22  FIG_H.#include "
0c80: 63 6f 6e 66 69 67 2e 68 22 0a 23 65 6e 64 69 66  config.h".#endif
0c90: 0a 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ../*************
0ca0: 2a 20 49 6e 63 6c 75 64 65 20 73 71 6c 69 74 65  * Include sqlite
0cb0: 4c 69 6d 69 74 2e 68 20 69 6e 20 74 68 65 20 6d  Limit.h in the m
0cc0: 69 64 64 6c 65 20 6f 66 20 73 71 6c 69 74 65 49  iddle of sqliteI
0cd0: 6e 74 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  nt.h ***********
0ce0: 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  /./*************
0cf0: 2a 20 42 65 67 69 6e 20 66 69 6c 65 20 73 71 6c  * Begin file sql
0d00: 69 74 65 4c 69 6d 69 74 2e 68 20 2a 2a 2a 2a 2a  iteLimit.h *****
0d10: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0d20: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0d30: 2f 0a 2f 2a 0a 2a 2a 20 32 30 30 37 20 4d 61 79  /./*.** 2007 May
0d40: 20 37 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74   7.**.** The aut
0d50: 68 6f 72 20 64 69 73 63 6c 61 69 6d 73 20 63 6f  hor disclaims co
0d60: 70 79 72 69 67 68 74 20 74 6f 20 74 68 69 73 20  pyright to this 
0d70: 73 6f 75 72 63 65 20 63 6f 64 65 2e 20 20 49 6e  source code.  In
0d80: 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 61 20 6c   place of.** a l
0d90: 65 67 61 6c 20 6e 6f 74 69 63 65 2c 20 68 65 72  egal notice, her
0da0: 65 20 69 73 20 61 20 62 6c 65 73 73 69 6e 67 3a  e is a blessing:
0db0: 0a 2a 2a 0a 2a 2a 20 20 20 20 4d 61 79 20 79 6f  .**.**    May yo
0dc0: 75 20 64 6f 20 67 6f 6f 64 20 61 6e 64 20 6e 6f  u do good and no
0dd0: 74 20 65 76 69 6c 2e 0a 2a 2a 20 20 20 20 4d 61  t evil..**    Ma
0de0: 79 20 79 6f 75 20 66 69 6e 64 20 66 6f 72 67 69  y you find forgi
0df0: 76 65 6e 65 73 73 20 66 6f 72 20 79 6f 75 72 73  veness for yours
0e00: 65 6c 66 20 61 6e 64 20 66 6f 72 67 69 76 65 20  elf and forgive 
0e10: 6f 74 68 65 72 73 2e 0a 2a 2a 20 20 20 20 4d 61  others..**    Ma
0e20: 79 20 79 6f 75 20 73 68 61 72 65 20 66 72 65 65  y you share free
0e30: 6c 79 2c 20 6e 65 76 65 72 20 74 61 6b 69 6e 67  ly, never taking
0e40: 20 6d 6f 72 65 20 74 68 61 6e 20 79 6f 75 20 67   more than you g
0e50: 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 2a 2a  ive..**.********
0e60: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0e70: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0e80: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0e90: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0ea0: 2a 0a 2a 2a 20 0a 2a 2a 20 54 68 69 73 20 66 69  *.** .** This fi
0eb0: 6c 65 20 64 65 66 69 6e 65 73 20 76 61 72 69 6f  le defines vario
0ec0: 75 73 20 6c 69 6d 69 74 73 20 6f 66 20 77 68 61  us limits of wha
0ed0: 74 20 53 51 4c 69 74 65 20 63 61 6e 20 70 72 6f  t SQLite can pro
0ee0: 63 65 73 73 2e 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  cess..*/../*.** 
0ef0: 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67  The maximum leng
0f00: 74 68 20 6f 66 20 61 20 54 45 58 54 20 6f 72 20  th of a TEXT or 
0f10: 42 4c 4f 42 20 69 6e 20 62 79 74 65 73 2e 20 20  BLOB in bytes.  
0f20: 20 54 68 69 73 20 61 6c 73 6f 0a 2a 2a 20 6c 69   This also.** li
0f30: 6d 69 74 73 20 74 68 65 20 73 69 7a 65 20 6f 66  mits the size of
0f40: 20 61 20 72 6f 77 20 69 6e 20 61 20 74 61 62 6c   a row in a tabl
0f50: 65 20 6f 72 20 69 6e 64 65 78 2e 0a 2a 2a 0a 2a  e or index..**.*
0f60: 2a 20 54 68 65 20 68 61 72 64 20 6c 69 6d 69 74  * The hard limit
0f70: 20 69 73 20 74 68 65 20 61 62 69 6c 69 74 79 20   is the ability 
0f80: 6f 66 20 61 20 33 32 2d 62 69 74 20 73 69 67 6e  of a 32-bit sign
0f90: 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 74 6f  ed integer.** to
0fa0: 20 63 6f 75 6e 74 20 74 68 65 20 73 69 7a 65 3a   count the size:
0fb0: 20 32 5e 33 31 2d 31 20 6f 72 20 32 31 34 37 34   2^31-1 or 21474
0fc0: 38 33 36 34 37 2e 0a 2a 2f 0a 23 69 66 6e 64 65  83647..*/.#ifnde
0fd0: 66 20 53 51 4c 49 54 45 5f 4d 41 58 5f 4c 45 4e  f SQLITE_MAX_LEN
0fe0: 47 54 48 0a 23 20 64 65 66 69 6e 65 20 53 51 4c  GTH.# define SQL
0ff0: 49 54 45 5f 4d 41 58 5f 4c 45 4e 47 54 48 20 31  ITE_MAX_LENGTH 1
1000: 30 30 30 30 30 30 30 30 30 0a 23 65 6e 64 69 66  000000000.#endif
1010: 0a 0a 2f 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20  ../*.** This is 
1020: 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  the maximum numb
1030: 65 72 20 6f 66 0a 2a 2a 0a 2a 2a 20 20 20 20 2a  er of.**.**    *
1040: 20 43 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74 61   Columns in a ta
1050: 62 6c 65 0a 2a 2a 20 20 20 20 2a 20 43 6f 6c 75  ble.**    * Colu
1060: 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65 78 0a  mns in an index.
1070: 2a 2a 20 20 20 20 2a 20 43 6f 6c 75 6d 6e 73 20  **    * Columns 
1080: 69 6e 20 61 20 76 69 65 77 0a 2a 2a 20 20 20 20  in a view.**    
1090: 2a 20 54 65 72 6d 73 20 69 6e 20 74 68 65 20 53  * Terms in the S
10a0: 45 54 20 63 6c 61 75 73 65 20 6f 66 20 61 6e 20  ET clause of an 
10b0: 55 50 44 41 54 45 20 73 74 61 74 65 6d 65 6e 74  UPDATE statement
10c0: 0a 2a 2a 20 20 20 20 2a 20 54 65 72 6d 73 20 69  .**    * Terms i
10d0: 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  n the result set
10e0: 20 6f 66 20 61 20 53 45 4c 45 43 54 20 73 74 61   of a SELECT sta
10f0: 74 65 6d 65 6e 74 0a 2a 2a 20 20 20 20 2a 20 54  tement.**    * T
1100: 65 72 6d 73 20 69 6e 20 74 68 65 20 47 52 4f 55  erms in the GROU
1110: 50 20 42 59 20 6f 72 20 4f 52 44 45 52 20 42 59  P BY or ORDER BY
1120: 20 63 6c 61 75 73 65 73 20 6f 66 20 61 20 53 45   clauses of a SE
1130: 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 0a  LECT statement..
1140: 2a 2a 20 20 20 20 2a 20 54 65 72 6d 73 20 69 6e  **    * Terms in
1150: 20 74 68 65 20 56 41 4c 55 45 53 20 63 6c 61 75   the VALUES clau
1160: 73 65 20 6f 66 20 61 6e 20 49 4e 53 45 52 54 20  se of an INSERT 
1170: 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20  statement.**.** 
1180: 54 68 65 20 68 61 72 64 20 75 70 70 65 72 20 6c  The hard upper l
1190: 69 6d 69 74 20 68 65 72 65 20 69 73 20 33 32 36  imit here is 326
11a0: 37 36 2e 20 20 4d 6f 73 74 20 64 61 74 61 62 61  76.  Most databa
11b0: 73 65 20 70 65 6f 70 6c 65 20 77 69 6c 6c 0a 2a  se people will.*
11c0: 2a 20 74 65 6c 6c 20 79 6f 75 20 74 68 61 74 20  * tell you that 
11d0: 69 6e 20 61 20 77 65 6c 6c 2d 6e 6f 72 6d 61 6c  in a well-normal
11e0: 69 7a 65 64 20 64 61 74 61 62 61 73 65 2c 20 79  ized database, y
11f0: 6f 75 20 75 73 75 61 6c 6c 79 20 73 68 6f 75 6c  ou usually shoul
1200: 64 0a 2a 2a 20 6e 6f 74 20 68 61 76 65 20 6d 6f  d.** not have mo
1210: 72 65 20 74 68 61 6e 20 61 20 64 6f 7a 65 6e 20  re than a dozen 
1220: 6f 72 20 73 6f 20 63 6f 6c 75 6d 6e 73 20 69 6e  or so columns in
1230: 20 61 6e 79 20 74 61 62 6c 65 2e 20 20 41 6e 64   any table.  And
1240: 20 69 66 0a 2a 2a 20 74 68 61 74 20 69 73 20 74   if.** that is t
1250: 68 65 20 63 61 73 65 2c 20 74 68 65 72 65 20 69  he case, there i
1260: 73 20 6e 6f 20 70 6f 69 6e 74 20 69 6e 20 68 61  s no point in ha
1270: 76 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20 61  ving more than a
1280: 20 66 65 77 0a 2a 2a 20 64 6f 7a 65 6e 20 76 61   few.** dozen va
1290: 6c 75 65 73 20 69 6e 20 61 6e 79 20 6f 66 20 74  lues in any of t
12a0: 68 65 20 6f 74 68 65 72 20 73 69 74 75 61 74 69  he other situati
12b0: 6f 6e 73 20 64 65 73 63 72 69 62 65 64 20 61 62  ons described ab
12c0: 6f 76 65 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20  ove..*/.#ifndef 
12d0: 53 51 4c 49 54 45 5f 4d 41 58 5f 43 4f 4c 55 4d  SQLITE_MAX_COLUM
12e0: 4e 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54  N.# define SQLIT
12f0: 45 5f 4d 41 58 5f 43 4f 4c 55 4d 4e 20 32 30 30  E_MAX_COLUMN 200
1300: 30 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20  0.#endif../*.** 
1310: 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67  The maximum leng
1320: 74 68 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 53  th of a single S
1330: 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20  QL statement in 
1340: 62 79 74 65 73 2e 0a 2a 2a 0a 2a 2a 20 49 74 20  bytes..**.** It 
1350: 75 73 65 64 20 74 6f 20 62 65 20 74 68 65 20 63  used to be the c
1360: 61 73 65 20 74 68 61 74 20 73 65 74 74 69 6e 67  ase that setting
1370: 20 74 68 69 73 20 76 61 6c 75 65 20 74 6f 20 7a   this value to z
1380: 65 72 6f 20 77 6f 75 6c 64 0a 2a 2a 20 74 75 72  ero would.** tur
1390: 6e 20 74 68 65 20 6c 69 6d 69 74 20 6f 66 66 2e  n the limit off.
13a0: 20 20 54 68 61 74 20 69 73 20 6e 6f 20 6c 6f 6e    That is no lon
13b0: 67 65 72 20 74 72 75 65 2e 20 20 49 74 20 69 73  ger true.  It is
13c0: 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 0a 2a 2a   not possible.**
13d0: 20 74 6f 20 74 75 72 6e 20 74 68 69 73 20 6c 69   to turn this li
13e0: 6d 69 74 20 6f 66 66 2e 0a 2a 2f 0a 23 69 66 6e  mit off..*/.#ifn
13f0: 64 65 66 20 53 51 4c 49 54 45 5f 4d 41 58 5f 53  def SQLITE_MAX_S
1400: 51 4c 5f 4c 45 4e 47 54 48 0a 23 20 64 65 66 69  QL_LENGTH.# defi
1410: 6e 65 20 53 51 4c 49 54 45 5f 4d 41 58 5f 53 51  ne SQLITE_MAX_SQ
1420: 4c 5f 4c 45 4e 47 54 48 20 31 30 30 30 30 30 30  L_LENGTH 1000000
1430: 30 30 30 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a  000.#endif../*.*
1440: 2a 20 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65  * The maximum de
1450: 70 74 68 20 6f 66 20 61 6e 20 65 78 70 72 65 73  pth of an expres
1460: 73 69 6f 6e 20 74 72 65 65 2e 20 54 68 69 73 20  sion tree. This 
1470: 69 73 20 6c 69 6d 69 74 65 64 20 74 6f 20 0a 2a  is limited to .*
1480: 2a 20 73 6f 6d 65 20 65 78 74 65 6e 74 20 62 79  * some extent by
1490: 20 53 51 4c 49 54 45 5f 4d 41 58 5f 53 51 4c 5f   SQLITE_MAX_SQL_
14a0: 4c 45 4e 47 54 48 2e 20 42 75 74 20 73 6f 6d 65  LENGTH. But some
14b0: 74 69 6d 65 20 79 6f 75 20 6d 69 67 68 74 20 0a  time you might .
14c0: 2a 2a 20 77 61 6e 74 20 74 6f 20 70 6c 61 63 65  ** want to place
14d0: 20 6d 6f 72 65 20 73 65 76 65 72 65 20 6c 69 6d   more severe lim
14e0: 69 74 73 20 6f 6e 20 74 68 65 20 63 6f 6d 70 6c  its on the compl
14f0: 65 78 69 74 79 20 6f 66 20 61 6e 20 0a 2a 2a 20  exity of an .** 
1500: 65 78 70 72 65 73 73 69 6f 6e 2e 0a 2a 2a 0a 2a  expression..**.*
1510: 2a 20 41 20 76 61 6c 75 65 20 6f 66 20 30 20 75  * A value of 0 u
1520: 73 65 64 20 74 6f 20 6d 65 61 6e 20 74 68 61 74  sed to mean that
1530: 20 74 68 65 20 6c 69 6d 69 74 20 77 61 73 20 6e   the limit was n
1540: 6f 74 20 65 6e 66 6f 72 63 65 64 2e 0a 2a 2a 20  ot enforced..** 
1550: 42 75 74 20 74 68 61 74 20 69 73 20 6e 6f 20 6c  But that is no l
1560: 6f 6e 67 65 72 20 74 72 75 65 2e 20 20 54 68 65  onger true.  The
1570: 20 6c 69 6d 69 74 20 69 73 20 6e 6f 77 20 73 74   limit is now st
1580: 72 69 63 74 6c 79 20 65 6e 66 6f 72 63 65 64 0a  rictly enforced.
1590: 2a 2a 20 61 74 20 61 6c 6c 20 74 69 6d 65 73 2e  ** at all times.
15a0: 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  .*/.#ifndef SQLI
15b0: 54 45 5f 4d 41 58 5f 45 58 50 52 5f 44 45 50 54  TE_MAX_EXPR_DEPT
15c0: 48 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54  H.# define SQLIT
15d0: 45 5f 4d 41 58 5f 45 58 50 52 5f 44 45 50 54 48  E_MAX_EXPR_DEPTH
15e0: 20 31 30 30 30 0a 23 65 6e 64 69 66 0a 0a 2f 2a   1000.#endif../*
15f0: 0a 2a 2a 20 54 68 65 20 6d 61 78 69 6d 75 6d 20  .** The maximum 
1600: 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20  number of terms 
1610: 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45  in a compound SE
1620: 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 0a  LECT statement..
1630: 2a 2a 20 54 68 65 20 63 6f 64 65 20 67 65 6e 65  ** The code gene
1640: 72 61 74 6f 72 20 66 6f 72 20 63 6f 6d 70 6f 75  rator for compou
1650: 6e 64 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d  nd SELECT statem
1660: 65 6e 74 73 20 64 6f 65 73 20 6f 6e 65 0a 2a 2a  ents does one.**
1670: 20 6c 65 76 65 6c 20 6f 66 20 72 65 63 75 72 73   level of recurs
1680: 69 6f 6e 20 66 6f 72 20 65 61 63 68 20 74 65 72  ion for each ter
1690: 6d 2e 20 20 41 20 73 74 61 63 6b 20 6f 76 65 72  m.  A stack over
16a0: 66 6c 6f 77 20 63 61 6e 20 72 65 73 75 6c 74 0a  flow can result.
16b0: 2a 2a 20 69 66 20 74 68 65 20 6e 75 6d 62 65 72  ** if the number
16c0: 20 6f 66 20 74 65 72 6d 73 20 69 73 20 74 6f 6f   of terms is too
16d0: 20 6c 61 72 67 65 2e 20 20 49 6e 20 70 72 61 63   large.  In prac
16e0: 74 69 63 65 2c 20 6d 6f 73 74 20 53 51 4c 0a 2a  tice, most SQL.*
16f0: 2a 20 6e 65 76 65 72 20 68 61 73 20 6d 6f 72 65  * never has more
1700: 20 74 68 61 6e 20 33 20 6f 72 20 34 20 74 65 72   than 3 or 4 ter
1710: 6d 73 2e 20 20 55 73 65 20 61 20 76 61 6c 75 65  ms.  Use a value
1720: 20 6f 66 20 30 20 74 6f 20 64 69 73 61 62 6c 65   of 0 to disable
1730: 0a 2a 2a 20 61 6e 79 20 6c 69 6d 69 74 20 6f 6e  .** any limit on
1740: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74   the number of t
1750: 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75  erms in a compou
1760: 6e 74 20 53 45 4c 45 43 54 2e 0a 2a 2f 0a 23 69  nt SELECT..*/.#i
1770: 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4d 41 58  fndef SQLITE_MAX
1780: 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54  _COMPOUND_SELECT
1790: 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45  .# define SQLITE
17a0: 5f 4d 41 58 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45  _MAX_COMPOUND_SE
17b0: 4c 45 43 54 20 35 30 30 0a 23 65 6e 64 69 66 0a  LECT 500.#endif.
17c0: 0a 2f 2a 0a 2a 2a 20 54 68 65 20 6d 61 78 69 6d  ./*.** The maxim
17d0: 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 6f 70 63  um number of opc
17e0: 6f 64 65 73 20 69 6e 20 61 20 56 44 42 45 20 70  odes in a VDBE p
17f0: 72 6f 67 72 61 6d 2e 0a 2a 2a 20 4e 6f 74 20 63  rogram..** Not c
1800: 75 72 72 65 6e 74 6c 79 20 65 6e 66 6f 72 63 65  urrently enforce
1810: 64 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51  d..*/.#ifndef SQ
1820: 4c 49 54 45 5f 4d 41 58 5f 56 44 42 45 5f 4f 50  LITE_MAX_VDBE_OP
1830: 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45  .# define SQLITE
1840: 5f 4d 41 58 5f 56 44 42 45 5f 4f 50 20 32 35 30  _MAX_VDBE_OP 250
1850: 30 30 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a  00.#endif../*.**
1860: 20 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d   The maximum num
1870: 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73  ber of arguments
1880: 20 74 6f 20 61 6e 20 53 51 4c 20 66 75 6e 63 74   to an SQL funct
1890: 69 6f 6e 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20  ion..*/.#ifndef 
18a0: 53 51 4c 49 54 45 5f 4d 41 58 5f 46 55 4e 43 54  SQLITE_MAX_FUNCT
18b0: 49 4f 4e 5f 41 52 47 0a 23 20 64 65 66 69 6e 65  ION_ARG.# define
18c0: 20 53 51 4c 49 54 45 5f 4d 41 58 5f 46 55 4e 43   SQLITE_MAX_FUNC
18d0: 54 49 4f 4e 5f 41 52 47 20 31 32 37 0a 23 65 6e  TION_ARG 127.#en
18e0: 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 6d  dif../*.** The m
18f0: 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
1900: 20 69 6e 2d 6d 65 6d 6f 72 79 20 70 61 67 65 73   in-memory pages
1910: 20 74 6f 20 75 73 65 20 66 6f 72 20 74 68 65 20   to use for the 
1920: 6d 61 69 6e 20 64 61 74 61 62 61 73 65 0a 2a 2a  main database.**
1930: 20 74 61 62 6c 65 20 61 6e 64 20 66 6f 72 20 74   table and for t
1940: 65 6d 70 6f 72 61 72 79 20 74 61 62 6c 65 73 2e  emporary tables.
1950: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 44 45 46    The SQLITE_DEF
1960: 41 55 4c 54 5f 43 41 43 48 45 5f 53 49 5a 45 0a  AULT_CACHE_SIZE.
1970: 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54  */.#ifndef SQLIT
1980: 45 5f 44 45 46 41 55 4c 54 5f 43 41 43 48 45 5f  E_DEFAULT_CACHE_
1990: 53 49 5a 45 0a 23 20 64 65 66 69 6e 65 20 53 51  SIZE.# define SQ
19a0: 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 43 41 43  LITE_DEFAULT_CAC
19b0: 48 45 5f 53 49 5a 45 20 20 32 30 30 30 0a 23 65  HE_SIZE  2000.#e
19c0: 6e 64 69 66 0a 23 69 66 6e 64 65 66 20 53 51 4c  ndif.#ifndef SQL
19d0: 49 54 45 5f 44 45 46 41 55 4c 54 5f 54 45 4d 50  ITE_DEFAULT_TEMP
19e0: 5f 43 41 43 48 45 5f 53 49 5a 45 0a 23 20 64 65  _CACHE_SIZE.# de
19f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 46 41  fine SQLITE_DEFA
1a00: 55 4c 54 5f 54 45 4d 50 5f 43 41 43 48 45 5f 53  ULT_TEMP_CACHE_S
1a10: 49 5a 45 20 20 35 30 30 0a 23 65 6e 64 69 66 0a  IZE  500.#endif.
1a20: 0a 2f 2a 0a 2a 2a 20 54 68 65 20 64 65 66 61 75  ./*.** The defau
1a30: 6c 74 20 6e 75 6d 62 65 72 20 6f 66 20 66 72 61  lt number of fra
1a40: 6d 65 73 20 74 6f 20 61 63 63 75 6d 75 6c 61 74  mes to accumulat
1a50: 65 20 69 6e 20 74 68 65 20 6c 6f 67 20 66 69 6c  e in the log fil
1a60: 65 20 62 65 66 6f 72 65 0a 2a 2a 20 63 68 65 63  e before.** chec
1a70: 6b 70 6f 69 6e 74 69 6e 67 20 74 68 65 20 64 61  kpointing the da
1a80: 74 61 62 61 73 65 20 69 6e 20 57 41 4c 20 6d 6f  tabase in WAL mo
1a90: 64 65 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53  de..*/.#ifndef S
1aa0: 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 57 41  QLITE_DEFAULT_WA
1ab0: 4c 5f 41 55 54 4f 43 48 45 43 4b 50 4f 49 4e 54  L_AUTOCHECKPOINT
1ac0: 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45  .# define SQLITE
1ad0: 5f 44 45 46 41 55 4c 54 5f 57 41 4c 5f 41 55 54  _DEFAULT_WAL_AUT
1ae0: 4f 43 48 45 43 4b 50 4f 49 4e 54 20 20 31 30 30  OCHECKPOINT  100
1af0: 30 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20  0.#endif../*.** 
1b00: 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
1b10: 65 72 20 6f 66 20 61 74 74 61 63 68 65 64 20 64  er of attached d
1b20: 61 74 61 62 61 73 65 73 2e 20 20 54 68 69 73 20  atabases.  This 
1b30: 6d 75 73 74 20 62 65 20 62 65 74 77 65 65 6e 20  must be between 
1b40: 30 0a 2a 2a 20 61 6e 64 20 36 32 2e 20 20 54 68  0.** and 62.  Th
1b50: 65 20 75 70 70 65 72 20 62 6f 75 6e 64 20 6f 6e  e upper bound on
1b60: 20 36 32 20 69 73 20 62 65 63 61 75 73 65 20 61   62 is because a
1b70: 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20   64-bit integer 
1b80: 62 69 74 6d 61 70 0a 2a 2a 20 69 73 20 75 73 65  bitmap.** is use
1b90: 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20  d internally to 
1ba0: 74 72 61 63 6b 20 61 74 74 61 63 68 65 64 20 64  track attached d
1bb0: 61 74 61 62 61 73 65 73 2e 0a 2a 2f 0a 23 69 66  atabases..*/.#if
1bc0: 6e 64 65 66 20 53 51 4c 49 54 45 5f 4d 41 58 5f  ndef SQLITE_MAX_
1bd0: 41 54 54 41 43 48 45 44 0a 23 20 64 65 66 69 6e  ATTACHED.# defin
1be0: 65 20 53 51 4c 49 54 45 5f 4d 41 58 5f 41 54 54  e SQLITE_MAX_ATT
1bf0: 41 43 48 45 44 20 31 30 0a 23 65 6e 64 69 66 0a  ACHED 10.#endif.
1c00: 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 6d 61 78 69  ../*.** The maxi
1c10: 6d 75 6d 20 76 61 6c 75 65 20 6f 66 20 61 20 3f  mum value of a ?
1c20: 6e 6e 6e 20 77 69 6c 64 63 61 72 64 20 74 68 61  nnn wildcard tha
1c30: 74 20 74 68 65 20 70 61 72 73 65 72 20 77 69 6c  t the parser wil
1c40: 6c 20 61 63 63 65 70 74 2e 0a 2a 2f 0a 23 69 66  l accept..*/.#if
1c50: 6e 64 65 66 20 53 51 4c 49 54 45 5f 4d 41 58 5f  ndef SQLITE_MAX_
1c60: 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 0a  VARIABLE_NUMBER.
1c70: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
1c80: 4d 41 58 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d  MAX_VARIABLE_NUM
1c90: 42 45 52 20 39 39 39 0a 23 65 6e 64 69 66 0a 0a  BER 999.#endif..
1ca0: 2f 2a 20 4d 61 78 69 6d 75 6d 20 70 61 67 65 20  /* Maximum page 
1cb0: 73 69 7a 65 2e 20 20 54 68 65 20 75 70 70 65 72  size.  The upper
1cc0: 20 62 6f 75 6e 64 20 6f 6e 20 74 68 69 73 20 76   bound on this v
1cd0: 61 6c 75 65 20 69 73 20 36 35 35 33 36 2e 20 20  alue is 65536.  
1ce0: 54 68 69 73 20 61 20 6c 69 6d 69 74 0a 2a 2a 20  This a limit.** 
1cf0: 69 6d 70 6f 73 65 64 20 62 79 20 74 68 65 20 75  imposed by the u
1d00: 73 65 20 6f 66 20 31 36 2d 62 69 74 20 6f 66 66  se of 16-bit off
1d10: 73 65 74 73 20 77 69 74 68 69 6e 20 65 61 63 68  sets within each
1d20: 20 70 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 45 61 72   page..**.** Ear
1d30: 6c 69 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66  lier versions of
1d40: 20 53 51 4c 69 74 65 20 61 6c 6c 6f 77 65 64 20   SQLite allowed 
1d50: 74 68 65 20 75 73 65 72 20 74 6f 20 63 68 61 6e  the user to chan
1d60: 67 65 20 74 68 69 73 20 76 61 6c 75 65 20 61 74  ge this value at
1d70: 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65  .** compile time
1d80: 2e 20 54 68 69 73 20 69 73 20 6e 6f 20 6c 6f 6e  . This is no lon
1d90: 67 65 72 20 70 65 72 6d 69 74 74 65 64 2c 20 6f  ger permitted, o
1da0: 6e 20 74 68 65 20 67 72 6f 75 6e 64 73 20 74 68  n the grounds th
1db0: 61 74 20 69 74 20 63 72 65 61 74 65 73 0a 2a 2a  at it creates.**
1dc0: 20 61 20 6c 69 62 72 61 72 79 20 74 68 61 74 20   a library that 
1dd0: 69 73 20 74 65 63 68 6e 69 63 61 6c 6c 79 20 69  is technically i
1de0: 6e 63 6f 6d 70 61 74 69 62 6c 65 20 77 69 74 68  ncompatible with
1df0: 20 61 6e 20 53 51 4c 69 74 65 20 6c 69 62 72 61   an SQLite libra
1e00: 72 79 20 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20  ry .** compiled 
1e10: 77 69 74 68 20 61 20 64 69 66 66 65 72 65 6e 74  with a different
1e20: 20 6c 69 6d 69 74 2e 20 49 66 20 61 20 70 72 6f   limit. If a pro
1e30: 63 65 73 73 20 6f 70 65 72 61 74 69 6e 67 20 6f  cess operating o
1e40: 6e 20 61 20 64 61 74 61 62 61 73 65 20 0a 2a 2a  n a database .**
1e50: 20 77 69 74 68 20 61 20 70 61 67 65 2d 73 69 7a   with a page-siz
1e60: 65 20 6f 66 20 36 35 35 33 36 20 62 79 74 65 73  e of 65536 bytes
1e70: 20 63 72 61 73 68 65 73 2c 20 74 68 65 6e 20 61   crashes, then a
1e80: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 53 51  n instance of SQ
1e90: 4c 69 74 65 20 0a 2a 2a 20 63 6f 6d 70 69 6c 65  Lite .** compile
1ea0: 64 20 77 69 74 68 20 74 68 65 20 64 65 66 61 75  d with the defau
1eb0: 6c 74 20 70 61 67 65 2d 73 69 7a 65 20 6c 69 6d  lt page-size lim
1ec0: 69 74 20 77 69 6c 6c 20 6e 6f 74 20 62 65 20 61  it will not be a
1ed0: 62 6c 65 20 74 6f 20 72 6f 6c 6c 62 61 63 6b 20  ble to rollback 
1ee0: 0a 2a 2a 20 74 68 65 20 61 62 6f 72 74 65 64 20  .** the aborted 
1ef0: 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 54 68 69  transaction. Thi
1f00: 73 20 63 6f 75 6c 64 20 6c 65 61 64 20 74 6f 20  s could lead to 
1f10: 64 61 74 61 62 61 73 65 20 63 6f 72 72 75 70 74  database corrupt
1f20: 69 6f 6e 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53  ion..*/.#ifdef S
1f30: 51 4c 49 54 45 5f 4d 41 58 5f 50 41 47 45 5f 53  QLITE_MAX_PAGE_S
1f40: 49 5a 45 0a 23 20 75 6e 64 65 66 20 53 51 4c 49  IZE.# undef SQLI
1f50: 54 45 5f 4d 41 58 5f 50 41 47 45 5f 53 49 5a 45  TE_MAX_PAGE_SIZE
1f60: 0a 23 65 6e 64 69 66 0a 23 64 65 66 69 6e 65 20  .#endif.#define 
1f70: 53 51 4c 49 54 45 5f 4d 41 58 5f 50 41 47 45 5f  SQLITE_MAX_PAGE_
1f80: 53 49 5a 45 20 36 35 35 33 36 0a 0a 0a 2f 2a 0a  SIZE 65536.../*.
1f90: 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20 73  ** The default s
1fa0: 69 7a 65 20 6f 66 20 61 20 64 61 74 61 62 61 73  ize of a databas
1fb0: 65 20 70 61 67 65 2e 0a 2a 2f 0a 23 69 66 6e 64  e page..*/.#ifnd
1fc0: 65 66 20 53 51 4c 49 54 45 5f 44 45 46 41 55 4c  ef SQLITE_DEFAUL
1fd0: 54 5f 50 41 47 45 5f 53 49 5a 45 0a 23 20 64 65  T_PAGE_SIZE.# de
1fe0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 46 41  fine SQLITE_DEFA
1ff0: 55 4c 54 5f 50 41 47 45 5f 53 49 5a 45 20 31 30  ULT_PAGE_SIZE 10
2000: 32 34 0a 23 65 6e 64 69 66 0a 23 69 66 20 53 51  24.#endif.#if SQ
2010: 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 50 41 47  LITE_DEFAULT_PAG
2020: 45 5f 53 49 5a 45 3e 53 51 4c 49 54 45 5f 4d 41  E_SIZE>SQLITE_MA
2030: 58 5f 50 41 47 45 5f 53 49 5a 45 0a 23 20 75 6e  X_PAGE_SIZE.# un
2040: 64 65 66 20 53 51 4c 49 54 45 5f 44 45 46 41 55  def SQLITE_DEFAU
2050: 4c 54 5f 50 41 47 45 5f 53 49 5a 45 0a 23 20 64  LT_PAGE_SIZE.# d
2060: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 46  efine SQLITE_DEF
2070: 41 55 4c 54 5f 50 41 47 45 5f 53 49 5a 45 20 53  AULT_PAGE_SIZE S
2080: 51 4c 49 54 45 5f 4d 41 58 5f 50 41 47 45 5f 53  QLITE_MAX_PAGE_S
2090: 49 5a 45 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a  IZE.#endif../*.*
20a0: 2a 20 4f 72 64 69 6e 61 72 69 6c 79 2c 20 69 66  * Ordinarily, if
20b0: 20 6e 6f 20 76 61 6c 75 65 20 69 73 20 65 78 70   no value is exp
20c0: 6c 69 63 69 74 6c 79 20 70 72 6f 76 69 64 65 64  licitly provided
20d0: 2c 20 53 51 4c 69 74 65 20 63 72 65 61 74 65 73  , SQLite creates
20e0: 20 64 61 74 61 62 61 73 65 73 0a 2a 2a 20 77 69   databases.** wi
20f0: 74 68 20 70 61 67 65 20 73 69 7a 65 20 53 51 4c  th page size SQL
2100: 49 54 45 5f 44 45 46 41 55 4c 54 5f 50 41 47 45  ITE_DEFAULT_PAGE
2110: 5f 53 49 5a 45 2e 20 48 6f 77 65 76 65 72 2c 20  _SIZE. However, 
2120: 62 61 73 65 64 20 6f 6e 20 63 65 72 74 61 69 6e  based on certain
2130: 0a 2a 2a 20 64 65 76 69 63 65 20 63 68 61 72 61  .** device chara
2140: 63 74 65 72 69 73 74 69 63 73 20 28 73 65 63 74  cteristics (sect
2150: 6f 72 2d 73 69 7a 65 20 61 6e 64 20 61 74 6f 6d  or-size and atom
2160: 69 63 20 77 72 69 74 65 28 29 20 73 75 70 70 6f  ic write() suppo
2170: 72 74 29 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 6d  rt),.** SQLite m
2180: 61 79 20 63 68 6f 6f 73 65 20 61 20 6c 61 72 67  ay choose a larg
2190: 65 72 20 76 61 6c 75 65 2e 20 54 68 69 73 20 63  er value. This c
21a0: 6f 6e 73 74 61 6e 74 20 69 73 20 74 68 65 20 6d  onstant is the m
21b0: 61 78 69 6d 75 6d 20 76 61 6c 75 65 0a 2a 2a 20  aximum value.** 
21c0: 53 51 4c 69 74 65 20 77 69 6c 6c 20 63 68 6f 6f  SQLite will choo
21d0: 73 65 20 6f 6e 20 69 74 73 20 6f 77 6e 2e 0a 2a  se on its own..*
21e0: 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45  /.#ifndef SQLITE
21f0: 5f 4d 41 58 5f 44 45 46 41 55 4c 54 5f 50 41 47  _MAX_DEFAULT_PAG
2200: 45 5f 53 49 5a 45 0a 23 20 64 65 66 69 6e 65 20  E_SIZE.# define 
2210: 53 51 4c 49 54 45 5f 4d 41 58 5f 44 45 46 41 55  SQLITE_MAX_DEFAU
2220: 4c 54 5f 50 41 47 45 5f 53 49 5a 45 20 38 31 39  LT_PAGE_SIZE 819
2230: 32 0a 23 65 6e 64 69 66 0a 23 69 66 20 53 51 4c  2.#endif.#if SQL
2240: 49 54 45 5f 4d 41 58 5f 44 45 46 41 55 4c 54 5f  ITE_MAX_DEFAULT_
2250: 50 41 47 45 5f 53 49 5a 45 3e 53 51 4c 49 54 45  PAGE_SIZE>SQLITE
2260: 5f 4d 41 58 5f 50 41 47 45 5f 53 49 5a 45 0a 23  _MAX_PAGE_SIZE.#
2270: 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 4d 41   undef SQLITE_MA
2280: 58 5f 44 45 46 41 55 4c 54 5f 50 41 47 45 5f 53  X_DEFAULT_PAGE_S
2290: 49 5a 45 0a 23 20 64 65 66 69 6e 65 20 53 51 4c  IZE.# define SQL
22a0: 49 54 45 5f 4d 41 58 5f 44 45 46 41 55 4c 54 5f  ITE_MAX_DEFAULT_
22b0: 50 41 47 45 5f 53 49 5a 45 20 53 51 4c 49 54 45  PAGE_SIZE SQLITE
22c0: 5f 4d 41 58 5f 50 41 47 45 5f 53 49 5a 45 0a 23  _MAX_PAGE_SIZE.#
22d0: 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a 2a 20 4d 61  endif.../*.** Ma
22e0: 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
22f0: 70 61 67 65 73 20 69 6e 20 6f 6e 65 20 64 61 74  pages in one dat
2300: 61 62 61 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a  abase file..**.*
2310: 2a 20 54 68 69 73 20 69 73 20 72 65 61 6c 6c 79  * This is really
2320: 20 6a 75 73 74 20 74 68 65 20 64 65 66 61 75 6c   just the defaul
2330: 74 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20  t value for the 
2340: 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 20 70  max_page_count p
2350: 72 61 67 6d 61 2e 0a 2a 2a 20 54 68 69 73 20 76  ragma..** This v
2360: 61 6c 75 65 20 63 61 6e 20 62 65 20 6c 6f 77 65  alue can be lowe
2370: 72 65 64 20 28 6f 72 20 72 61 69 73 65 64 29 20  red (or raised) 
2380: 61 74 20 72 75 6e 2d 74 69 6d 65 20 75 73 69 6e  at run-time usin
2390: 67 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 6d 61  g that the.** ma
23a0: 78 5f 70 61 67 65 5f 63 6f 75 6e 74 20 6d 61 63  x_page_count mac
23b0: 72 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53  ro..*/.#ifndef S
23c0: 51 4c 49 54 45 5f 4d 41 58 5f 50 41 47 45 5f 43  QLITE_MAX_PAGE_C
23d0: 4f 55 4e 54 0a 23 20 64 65 66 69 6e 65 20 53 51  OUNT.# define SQ
23e0: 4c 49 54 45 5f 4d 41 58 5f 50 41 47 45 5f 43 4f  LITE_MAX_PAGE_CO
23f0: 55 4e 54 20 31 30 37 33 37 34 31 38 32 33 0a 23  UNT 1073741823.#
2400: 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 4d 61 78  endif../*.** Max
2410: 69 6d 75 6d 20 6c 65 6e 67 74 68 20 28 69 6e 20  imum length (in 
2420: 62 79 74 65 73 29 20 6f 66 20 74 68 65 20 70 61  bytes) of the pa
2430: 74 74 65 72 6e 20 69 6e 20 61 20 4c 49 4b 45 20  ttern in a LIKE 
2440: 6f 72 20 47 4c 4f 42 0a 2a 2a 20 6f 70 65 72 61  or GLOB.** opera
2450: 74 6f 72 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20  tor..*/.#ifndef 
2460: 53 51 4c 49 54 45 5f 4d 41 58 5f 4c 49 4b 45 5f  SQLITE_MAX_LIKE_
2470: 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 0a 23  PATTERN_LENGTH.#
2480: 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d   define SQLITE_M
2490: 41 58 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f  AX_LIKE_PATTERN_
24a0: 4c 45 4e 47 54 48 20 35 30 30 30 30 0a 23 65 6e  LENGTH 50000.#en
24b0: 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 4d 61 78 69 6d  dif../*.** Maxim
24c0: 75 6d 20 64 65 70 74 68 20 6f 66 20 72 65 63 75  um depth of recu
24d0: 72 73 69 6f 6e 20 66 6f 72 20 74 72 69 67 67 65  rsion for trigge
24e0: 72 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 76 61 6c 75  rs..**.** A valu
24f0: 65 20 6f 66 20 31 20 6d 65 61 6e 73 20 74 68 61  e of 1 means tha
2500: 74 20 61 20 74 72 69 67 67 65 72 20 70 72 6f 67  t a trigger prog
2510: 72 61 6d 20 77 69 6c 6c 20 6e 6f 74 20 62 65 20  ram will not be 
2520: 61 62 6c 65 20 74 6f 20 69 74 73 65 6c 66 0a 2a  able to itself.*
2530: 2a 20 66 69 72 65 20 61 6e 79 20 74 72 69 67 67  * fire any trigg
2540: 65 72 73 2e 20 41 20 76 61 6c 75 65 20 6f 66 20  ers. A value of 
2550: 30 20 6d 65 61 6e 73 20 74 68 61 74 20 6e 6f 20  0 means that no 
2560: 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 73  trigger programs
2570: 20 61 74 20 61 6c 6c 20 0a 2a 2a 20 6d 61 79 20   at all .** may 
2580: 62 65 20 65 78 65 63 75 74 65 64 2e 0a 2a 2f 0a  be executed..*/.
2590: 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4d  #ifndef SQLITE_M
25a0: 41 58 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48  AX_TRIGGER_DEPTH
25b0: 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45  .# define SQLITE
25c0: 5f 4d 41 58 5f 54 52 49 47 47 45 52 5f 44 45 50  _MAX_TRIGGER_DEP
25d0: 54 48 20 31 30 30 30 0a 23 65 6e 64 69 66 0a 0a  TH 1000.#endif..
25e0: 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20  /************** 
25f0: 45 6e 64 20 6f 66 20 73 71 6c 69 74 65 4c 69 6d  End of sqliteLim
2600: 69 74 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  it.h ***********
2610: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
2620: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a  **************/.
2630: 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20  /************** 
2640: 43 6f 6e 74 69 6e 75 69 6e 67 20 77 68 65 72 65  Continuing where
2650: 20 77 65 20 6c 65 66 74 20 6f 66 66 20 69 6e 20   we left off in 
2660: 73 71 6c 69 74 65 49 6e 74 2e 68 20 2a 2a 2a 2a  sqliteInt.h ****
2670: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a  **************/.
2680: 0a 2f 2a 20 44 69 73 61 62 6c 65 20 6e 75 69 73  ./* Disable nuis
2690: 61 6e 63 65 20 77 61 72 6e 69 6e 67 73 20 6f 6e  ance warnings on
26a0: 20 42 6f 72 6c 61 6e 64 20 63 6f 6d 70 69 6c 65   Borland compile
26b0: 72 73 20 2a 2f 0a 23 69 66 20 64 65 66 69 6e 65  rs */.#if define
26c0: 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29 0a  d(__BORLANDC__).
26d0: 23 70 72 61 67 6d 61 20 77 61 72 6e 20 2d 72 63  #pragma warn -rc
26e0: 68 20 2f 2a 20 75 6e 72 65 61 63 68 61 62 6c 65  h /* unreachable
26f0: 20 63 6f 64 65 20 2a 2f 0a 23 70 72 61 67 6d 61   code */.#pragma
2700: 20 77 61 72 6e 20 2d 63 63 63 20 2f 2a 20 43 6f   warn -ccc /* Co
2710: 6e 64 69 74 69 6f 6e 20 69 73 20 61 6c 77 61 79  ndition is alway
2720: 73 20 74 72 75 65 20 6f 72 20 66 61 6c 73 65 20  s true or false 
2730: 2a 2f 0a 23 70 72 61 67 6d 61 20 77 61 72 6e 20  */.#pragma warn 
2740: 2d 61 75 73 20 2f 2a 20 41 73 73 69 67 6e 65 64  -aus /* Assigned
2750: 20 76 61 6c 75 65 20 69 73 20 6e 65 76 65 72 20   value is never 
2760: 75 73 65 64 20 2a 2f 0a 23 70 72 61 67 6d 61 20  used */.#pragma 
2770: 77 61 72 6e 20 2d 63 73 75 20 2f 2a 20 43 6f 6d  warn -csu /* Com
2780: 70 61 72 69 6e 67 20 73 69 67 6e 65 64 20 61 6e  paring signed an
2790: 64 20 75 6e 73 69 67 6e 65 64 20 2a 2f 0a 23 70  d unsigned */.#p
27a0: 72 61 67 6d 61 20 77 61 72 6e 20 2d 73 70 61 20  ragma warn -spa 
27b0: 2f 2a 20 53 75 73 70 69 63 69 6f 75 73 20 70 6f  /* Suspicious po
27c0: 69 6e 74 65 72 20 61 72 69 74 68 6d 65 74 69 63  inter arithmetic
27d0: 20 2a 2f 0a 23 65 6e 64 69 66 0a 0a 2f 2a 20 4e   */.#endif../* N
27e0: 65 65 64 65 64 20 66 6f 72 20 76 61 72 69 6f 75  eeded for variou
27f0: 73 20 64 65 66 69 6e 69 74 69 6f 6e 73 2e 2e 2e  s definitions...
2800: 20 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 47 4e 55   */.#ifndef _GNU
2810: 5f 53 4f 55 52 43 45 0a 23 20 64 65 66 69 6e 65  _SOURCE.# define
2820: 20 5f 47 4e 55 5f 53 4f 55 52 43 45 0a 23 65 6e   _GNU_SOURCE.#en
2830: 64 69 66 0a 0a 23 69 66 20 64 65 66 69 6e 65 64  dif..#if defined
2840: 28 5f 5f 4f 70 65 6e 42 53 44 5f 5f 29 20 26 26  (__OpenBSD__) &&
2850: 20 21 64 65 66 69 6e 65 64 28 5f 42 53 44 5f 53   !defined(_BSD_S
2860: 4f 55 52 43 45 29 0a 23 20 64 65 66 69 6e 65 20  OURCE).# define 
2870: 5f 42 53 44 5f 53 4f 55 52 43 45 0a 23 65 6e 64  _BSD_SOURCE.#end
2880: 69 66 0a 0a 2f 2a 0a 2a 2a 20 49 6e 63 6c 75 64  if../*.** Includ
2890: 65 20 73 74 61 6e 64 61 72 64 20 68 65 61 64 65  e standard heade
28a0: 72 20 66 69 6c 65 73 20 61 73 20 6e 65 63 65 73  r files as neces
28b0: 73 61 72 79 0a 2a 2f 0a 23 69 66 64 65 66 20 48  sary.*/.#ifdef H
28c0: 41 56 45 5f 53 54 44 49 4e 54 5f 48 0a 23 69 6e  AVE_STDINT_H.#in
28d0: 63 6c 75 64 65 20 3c 73 74 64 69 6e 74 2e 68 3e  clude <stdint.h>
28e0: 0a 23 65 6e 64 69 66 0a 23 69 66 64 65 66 20 48  .#endif.#ifdef H
28f0: 41 56 45 5f 49 4e 54 54 59 50 45 53 5f 48 0a 23  AVE_INTTYPES_H.#
2900: 69 6e 63 6c 75 64 65 20 3c 69 6e 74 74 79 70 65  include <inttype
2910: 73 2e 68 3e 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a  s.h>.#endif../*.
2920: 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  ** The following
2930: 20 6d 61 63 72 6f 73 20 61 72 65 20 75 73 65 64   macros are used
2940: 20 74 6f 20 63 61 73 74 20 70 6f 69 6e 74 65 72   to cast pointer
2950: 73 20 74 6f 20 69 6e 74 65 67 65 72 73 20 61 6e  s to integers an
2960: 64 0a 2a 2a 20 69 6e 74 65 67 65 72 73 20 74 6f  d.** integers to
2970: 20 70 6f 69 6e 74 65 72 73 2e 20 20 54 68 65 20   pointers.  The 
2980: 77 61 79 20 79 6f 75 20 64 6f 20 74 68 69 73 20  way you do this 
2990: 76 61 72 69 65 73 20 66 72 6f 6d 20 6f 6e 65 20  varies from one 
29a0: 63 6f 6d 70 69 6c 65 72 0a 2a 2a 20 74 6f 20 74  compiler.** to t
29b0: 68 65 20 6e 65 78 74 2c 20 73 6f 20 77 65 20 68  he next, so we h
29c0: 61 76 65 20 64 65 76 65 6c 6f 70 65 64 20 74 68  ave developed th
29d0: 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 65 74 20  e following set 
29e0: 6f 66 20 23 69 66 20 73 74 61 74 65 6d 65 6e 74  of #if statement
29f0: 73 0a 2a 2a 20 74 6f 20 67 65 6e 65 72 61 74 65  s.** to generate
2a00: 20 61 70 70 72 6f 70 72 69 61 74 65 20 6d 61 63   appropriate mac
2a10: 72 6f 73 20 66 6f 72 20 61 20 77 69 64 65 20 72  ros for a wide r
2a20: 61 6e 67 65 20 6f 66 20 63 6f 6d 70 69 6c 65 72  ange of compiler
2a30: 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 72  s..**.** The cor
2a40: 72 65 63 74 20 22 41 4e 53 49 22 20 77 61 79 20  rect "ANSI" way 
2a50: 74 6f 20 64 6f 20 74 68 69 73 20 69 73 20 74 6f  to do this is to
2a60: 20 75 73 65 20 74 68 65 20 69 6e 74 70 74 72 5f   use the intptr_
2a70: 74 20 74 79 70 65 2e 20 0a 2a 2a 20 55 6e 66 6f  t type. .** Unfo
2a80: 72 74 75 6e 61 74 65 6c 79 2c 20 74 68 61 74 20  rtunately, that 
2a90: 74 79 70 65 64 65 66 20 69 73 20 6e 6f 74 20 61  typedef is not a
2aa0: 76 61 69 6c 61 62 6c 65 20 6f 6e 20 61 6c 6c 20  vailable on all 
2ab0: 63 6f 6d 70 69 6c 65 72 73 2c 20 6f 72 0a 2a 2a  compilers, or.**
2ac0: 20 69 66 20 69 74 20 69 73 20 61 76 61 69 6c 61   if it is availa
2ad0: 62 6c 65 2c 20 69 74 20 72 65 71 75 69 72 65 73  ble, it requires
2ae0: 20 61 6e 20 23 69 6e 63 6c 75 64 65 20 6f 66 20   an #include of 
2af0: 73 70 65 63 69 66 69 63 20 68 65 61 64 65 72 73  specific headers
2b00: 0a 2a 2a 20 74 68 61 74 20 76 61 72 79 20 66 72  .** that vary fr
2b10: 6f 6d 20 6f 6e 65 20 6d 61 63 68 69 6e 65 20 74  om one machine t
2b20: 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2a 0a 2a  o the next..**.*
2b30: 2a 20 54 69 63 6b 65 74 20 23 33 38 36 30 3a 20  * Ticket #3860: 
2b40: 20 54 68 65 20 6c 6c 76 6d 2d 67 63 63 2d 34 2e   The llvm-gcc-4.
2b50: 32 20 63 6f 6d 70 69 6c 65 72 20 66 72 6f 6d 20  2 compiler from 
2b60: 41 70 70 6c 65 20 63 68 6f 6b 65 73 20 6f 6e 0a  Apple chokes on.
2b70: 2a 2a 20 74 68 65 20 28 28 76 6f 69 64 2a 29 26  ** the ((void*)&
2b80: 28 28 63 68 61 72 2a 29 30 29 5b 58 5d 29 20 63  ((char*)0)[X]) c
2b90: 6f 6e 73 74 72 75 63 74 2e 20 20 42 75 74 20 4d  onstruct.  But M
2ba0: 53 56 43 20 63 68 6f 6b 65 73 20 6f 6e 20 28 28  SVC chokes on ((
2bb0: 76 6f 69 64 2a 29 28 58 29 29 2e 0a 2a 2a 20 53  void*)(X))..** S
2bc0: 6f 20 77 65 20 68 61 76 65 20 74 6f 20 64 65 66  o we have to def
2bd0: 69 6e 65 20 74 68 65 20 6d 61 63 72 6f 73 20 69  ine the macros i
2be0: 6e 20 64 69 66 66 65 72 65 6e 74 20 77 61 79 73  n different ways
2bf0: 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68   depending on th
2c00: 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 72 2e 0a 2a  e.** compiler..*
2c10: 2f 0a 23 69 66 20 64 65 66 69 6e 65 64 28 5f 5f  /.#if defined(__
2c20: 50 54 52 44 49 46 46 5f 54 59 50 45 5f 5f 29 20  PTRDIFF_TYPE__) 
2c30: 20 2f 2a 20 54 68 69 73 20 63 61 73 65 20 73 68   /* This case sh
2c40: 6f 75 6c 64 20 77 6f 72 6b 20 66 6f 72 20 47 43  ould work for GC
2c50: 43 20 2a 2f 0a 23 20 64 65 66 69 6e 65 20 53 51  C */.# define SQ
2c60: 4c 49 54 45 5f 49 4e 54 5f 54 4f 5f 50 54 52 28  LITE_INT_TO_PTR(
2c70: 58 29 20 20 28 28 76 6f 69 64 2a 29 28 5f 5f 50  X)  ((void*)(__P
2c80: 54 52 44 49 46 46 5f 54 59 50 45 5f 5f 29 28 58  TRDIFF_TYPE__)(X
2c90: 29 29 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49  )).# define SQLI
2ca0: 54 45 5f 50 54 52 5f 54 4f 5f 49 4e 54 28 58 29  TE_PTR_TO_INT(X)
2cb0: 20 20 28 28 69 6e 74 29 28 5f 5f 50 54 52 44 49    ((int)(__PTRDI
2cc0: 46 46 5f 54 59 50 45 5f 5f 29 28 58 29 29 0a 23  FF_TYPE__)(X)).#
2cd0: 65 6c 69 66 20 21 64 65 66 69 6e 65 64 28 5f 5f  elif !defined(__
2ce0: 47 4e 55 43 5f 5f 29 20 20 20 20 20 20 20 2f 2a  GNUC__)       /*
2cf0: 20 57 6f 72 6b 73 20 66 6f 72 20 63 6f 6d 70 69   Works for compi
2d00: 6c 65 72 73 20 6f 74 68 65 72 20 74 68 61 6e 20  lers other than 
2d10: 4c 4c 56 4d 20 2a 2f 0a 23 20 64 65 66 69 6e 65  LLVM */.# define
2d20: 20 53 51 4c 49 54 45 5f 49 4e 54 5f 54 4f 5f 50   SQLITE_INT_TO_P
2d30: 54 52 28 58 29 20 20 28 28 76 6f 69 64 2a 29 26  TR(X)  ((void*)&
2d40: 28 28 63 68 61 72 2a 29 30 29 5b 58 5d 29 0a 23  ((char*)0)[X]).#
2d50: 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50   define SQLITE_P
2d60: 54 52 5f 54 4f 5f 49 4e 54 28 58 29 20 20 28 28  TR_TO_INT(X)  ((
2d70: 69 6e 74 29 28 28 28 63 68 61 72 2a 29 58 29 2d  int)(((char*)X)-
2d80: 28 63 68 61 72 2a 29 30 29 29 0a 23 65 6c 69 66  (char*)0)).#elif
2d90: 20 64 65 66 69 6e 65 64 28 48 41 56 45 5f 53 54   defined(HAVE_ST
2da0: 44 49 4e 54 5f 48 29 20 20 20 2f 2a 20 55 73 65  DINT_H)   /* Use
2db0: 20 74 68 69 73 20 63 61 73 65 20 69 66 20 77 65   this case if we
2dc0: 20 68 61 76 65 20 41 4e 53 49 20 68 65 61 64 65   have ANSI heade
2dd0: 72 73 20 2a 2f 0a 23 20 64 65 66 69 6e 65 20 53  rs */.# define S
2de0: 51 4c 49 54 45 5f 49 4e 54 5f 54 4f 5f 50 54 52  QLITE_INT_TO_PTR
2df0: 28 58 29 20 20 28 28 76 6f 69 64 2a 29 28 69 6e  (X)  ((void*)(in
2e00: 74 70 74 72 5f 74 29 28 58 29 29 0a 23 20 64 65  tptr_t)(X)).# de
2e10: 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 54 52 5f  fine SQLITE_PTR_
2e20: 54 4f 5f 49 4e 54 28 58 29 20 20 28 28 69 6e 74  TO_INT(X)  ((int
2e30: 29 28 69 6e 74 70 74 72 5f 74 29 28 58 29 29 0a  )(intptr_t)(X)).
2e40: 23 65 6c 73 65 20 20 20 20 20 20 20 20 20 20 20  #else           
2e50: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
2e60: 2a 20 47 65 6e 65 72 61 74 65 73 20 61 20 77 61  * Generates a wa
2e70: 72 6e 69 6e 67 20 2d 20 62 75 74 20 69 74 20 61  rning - but it a
2e80: 6c 77 61 79 73 20 77 6f 72 6b 73 20 2a 2f 0a 23  lways works */.#
2e90: 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49   define SQLITE_I
2ea0: 4e 54 5f 54 4f 5f 50 54 52 28 58 29 20 20 28 28  NT_TO_PTR(X)  ((
2eb0: 76 6f 69 64 2a 29 28 58 29 29 0a 23 20 64 65 66  void*)(X)).# def
2ec0: 69 6e 65 20 53 51 4c 49 54 45 5f 50 54 52 5f 54  ine SQLITE_PTR_T
2ed0: 4f 5f 49 4e 54 28 58 29 20 20 28 28 69 6e 74 29  O_INT(X)  ((int)
2ee0: 28 58 29 29 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a  (X)).#endif../*.
2ef0: 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 54 48  ** The SQLITE_TH
2f00: 52 45 41 44 53 41 46 45 20 6d 61 63 72 6f 20 6d  READSAFE macro m
2f10: 75 73 74 20 62 65 20 64 65 66 69 6e 65 64 20 61  ust be defined a
2f20: 73 20 30 2c 20 31 2c 20 6f 72 20 32 2e 0a 2a 2a  s 0, 1, or 2..**
2f30: 20 30 20 6d 65 61 6e 73 20 6d 75 74 65 78 65 73   0 means mutexes
2f40: 20 61 72 65 20 70 65 72 6d 61 6e 65 6e 74 6c 79   are permanently
2f50: 20 64 69 73 61 62 6c 65 20 61 6e 64 20 74 68 65   disable and the
2f60: 20 6c 69 62 72 61 72 79 20 69 73 20 6e 65 76 65   library is neve
2f70: 72 0a 2a 2a 20 74 68 72 65 61 64 73 61 66 65 2e  r.** threadsafe.
2f80: 20 20 31 20 6d 65 61 6e 73 20 74 68 65 20 6c 69    1 means the li
2f90: 62 72 61 72 79 20 69 73 20 73 65 72 69 61 6c 69  brary is seriali
2fa0: 7a 65 64 20 77 68 69 63 68 20 69 73 20 74 68 65  zed which is the
2fb0: 20 68 69 67 68 65 73 74 0a 2a 2a 20 6c 65 76 65   highest.** leve
2fc0: 6c 20 6f 66 20 74 68 72 65 61 64 73 61 66 65 74  l of threadsafet
2fd0: 79 2e 20 20 32 20 6d 65 61 6e 73 20 74 68 65 20  y.  2 means the 
2fe0: 6c 69 62 72 61 72 79 20 69 73 20 6d 75 6c 74 69  library is multi
2ff0: 74 68 72 65 61 64 65 64 20 2d 20 6d 75 6c 74 69  threaded - multi
3000: 70 6c 65 0a 2a 2a 20 74 68 72 65 61 64 73 20 63  ple.** threads c
3010: 61 6e 20 75 73 65 20 53 51 4c 69 74 65 20 61 73  an use SQLite as
3020: 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20   long as no two 
3030: 74 68 72 65 61 64 73 20 74 72 79 20 74 6f 20 75  threads try to u
3040: 73 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 64  se the same.** d
3050: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
3060: 6f 6e 20 61 74 20 74 68 65 20 73 61 6d 65 20 74  on at the same t
3070: 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 4f 6c 64 65 72  ime..**.** Older
3080: 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
3090: 69 74 65 20 75 73 65 64 20 61 6e 20 6f 70 74 69  ite used an opti
30a0: 6f 6e 61 6c 20 54 48 52 45 41 44 53 41 46 45 20  onal THREADSAFE 
30b0: 6d 61 63 72 6f 2e 0a 2a 2a 20 57 65 20 73 75 70  macro..** We sup
30c0: 70 6f 72 74 20 74 68 61 74 20 66 6f 72 20 6c 65  port that for le
30d0: 67 61 63 79 2e 0a 2a 2f 0a 23 69 66 20 21 64 65  gacy..*/.#if !de
30e0: 66 69 6e 65 64 28 53 51 4c 49 54 45 5f 54 48 52  fined(SQLITE_THR
30f0: 45 41 44 53 41 46 45 29 0a 23 20 69 66 20 64 65  EADSAFE).# if de
3100: 66 69 6e 65 64 28 54 48 52 45 41 44 53 41 46 45  fined(THREADSAFE
3110: 29 0a 23 20 20 20 64 65 66 69 6e 65 20 53 51 4c  ).#   define SQL
3120: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 54  ITE_THREADSAFE T
3130: 48 52 45 41 44 53 41 46 45 0a 23 20 65 6c 73 65  HREADSAFE.# else
3140: 0a 23 20 20 20 64 65 66 69 6e 65 20 53 51 4c 49  .#   define SQLI
3150: 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 31 20  TE_THREADSAFE 1 
3160: 2f 2a 20 49 4d 50 3a 20 52 2d 30 37 32 37 32 2d  /* IMP: R-07272-
3170: 32 32 33 30 39 20 2a 2f 0a 23 20 65 6e 64 69 66  22309 */.# endif
3180: 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 50  .#endif../*.** P
3190: 6f 77 65 72 73 61 66 65 20 6f 76 65 72 77 72 69  owersafe overwri
31a0: 74 65 20 69 73 20 6f 6e 20 62 79 20 64 65 66 61  te is on by defa
31b0: 75 6c 74 2e 20 20 42 75 74 20 63 61 6e 20 62 65  ult.  But can be
31c0: 20 74 75 72 6e 65 64 20 6f 66 66 20 75 73 69 6e   turned off usin
31d0: 67 0a 2a 2a 20 74 68 65 20 2d 44 53 51 4c 49 54  g.** the -DSQLIT
31e0: 45 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52  E_POWERSAFE_OVER
31f0: 57 52 49 54 45 3d 30 20 63 6f 6d 6d 61 6e 64 2d  WRITE=0 command-
3200: 6c 69 6e 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2f 0a  line option..*/.
3210: 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 50  #ifndef SQLITE_P
3220: 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49  OWERSAFE_OVERWRI
3230: 54 45 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49  TE.# define SQLI
3240: 54 45 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45  TE_POWERSAFE_OVE
3250: 52 57 52 49 54 45 20 31 0a 23 65 6e 64 69 66 0a  RWRITE 1.#endif.
3260: 0a 2f 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54  ./*.** The SQLIT
3270: 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41  E_DEFAULT_MEMSTA
3280: 54 55 53 20 6d 61 63 72 6f 20 6d 75 73 74 20 62  TUS macro must b
3290: 65 20 64 65 66 69 6e 65 64 20 61 73 20 65 69 74  e defined as eit
32a0: 68 65 72 20 30 20 6f 72 20 31 2e 0a 2a 2a 20 49  her 0 or 1..** I
32b0: 74 20 64 65 74 65 72 6d 69 6e 65 73 20 77 68 65  t determines whe
32c0: 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20  ther or not the 
32d0: 66 65 61 74 75 72 65 73 20 72 65 6c 61 74 65 64  features related
32e0: 20 74 6f 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 43   to .** SQLITE_C
32f0: 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20  ONFIG_MEMSTATUS 
3300: 61 72 65 20 61 76 61 69 6c 61 62 6c 65 20 62 79  are available by
3310: 20 64 65 66 61 75 6c 74 20 6f 72 20 6e 6f 74 2e   default or not.
3320: 20 54 68 69 73 20 76 61 6c 75 65 20 63 61 6e 0a   This value can.
3330: 2a 2a 20 62 65 20 6f 76 65 72 72 69 64 64 65 6e  ** be overridden
3340: 20 61 74 20 72 75 6e 74 69 6d 65 20 75 73 69 6e   at runtime usin
3350: 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  g the sqlite3_co
3360: 6e 66 69 67 28 29 20 41 50 49 2e 0a 2a 2f 0a 23  nfig() API..*/.#
3370: 69 66 20 21 64 65 66 69 6e 65 64 28 53 51 4c 49  if !defined(SQLI
3380: 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54  TE_DEFAULT_MEMST
3390: 41 54 55 53 29 0a 23 20 64 65 66 69 6e 65 20 53  ATUS).# define S
33a0: 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45  QLITE_DEFAULT_ME
33b0: 4d 53 54 41 54 55 53 20 31 0a 23 65 6e 64 69 66  MSTATUS 1.#endif
33c0: 0a 0a 2f 2a 0a 2a 2a 20 45 78 61 63 74 6c 79 20  ../*.** Exactly 
33d0: 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f  one of the follo
33e0: 77 69 6e 67 20 6d 61 63 72 6f 73 20 6d 75 73 74  wing macros must
33f0: 20 62 65 20 64 65 66 69 6e 65 64 20 69 6e 20 6f   be defined in o
3400: 72 64 65 72 20 74 6f 0a 2a 2a 20 73 70 65 63 69  rder to.** speci
3410: 66 79 20 77 68 69 63 68 20 6d 65 6d 6f 72 79 20  fy which memory 
3420: 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79  allocation subsy
3430: 73 74 65 6d 20 74 6f 20 75 73 65 2e 0a 2a 2a 0a  stem to use..**.
3440: 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 53 59  **     SQLITE_SY
3450: 53 54 45 4d 5f 4d 41 4c 4c 4f 43 20 20 20 20 20  STEM_MALLOC     
3460: 20 20 20 20 20 2f 2f 20 55 73 65 20 6e 6f 72 6d       // Use norm
3470: 61 6c 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63  al system malloc
3480: 28 29 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45  ().**     SQLITE
3490: 5f 57 49 4e 33 32 5f 4d 41 4c 4c 4f 43 20 20 20  _WIN32_MALLOC   
34a0: 20 20 20 20 20 20 20 20 2f 2f 20 55 73 65 20 57          // Use W
34b0: 69 6e 33 32 20 6e 61 74 69 76 65 20 68 65 61 70  in32 native heap
34c0: 20 41 50 49 0a 2a 2a 20 20 20 20 20 53 51 4c 49   API.**     SQLI
34d0: 54 45 5f 5a 45 52 4f 5f 4d 41 4c 4c 4f 43 20 20  TE_ZERO_MALLOC  
34e0: 20 20 20 20 20 20 20 20 20 20 2f 2f 20 55 73 65            // Use
34f0: 20 61 20 73 74 75 62 20 61 6c 6c 6f 63 61 74 6f   a stub allocato
3500: 72 20 74 68 61 74 20 61 6c 77 61 79 73 20 66 61  r that always fa
3510: 69 6c 73 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54  ils.**     SQLIT
3520: 45 5f 4d 45 4d 44 45 42 55 47 20 20 20 20 20 20  E_MEMDEBUG      
3530: 20 20 20 20 20 20 20 20 20 2f 2f 20 44 65 62 75           // Debu
3540: 67 67 69 6e 67 20 76 65 72 73 69 6f 6e 20 6f 66  gging version of
3550: 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29   system malloc()
3560: 0a 2a 2a 0a 2a 2a 20 4f 6e 20 57 69 6e 64 6f 77  .**.** On Window
3570: 73 2c 20 69 66 20 74 68 65 20 53 51 4c 49 54 45  s, if the SQLITE
3580: 5f 57 49 4e 33 32 5f 4d 41 4c 4c 4f 43 5f 56 41  _WIN32_MALLOC_VA
3590: 4c 49 44 41 54 45 20 6d 61 63 72 6f 20 69 73 20  LIDATE macro is 
35a0: 64 65 66 69 6e 65 64 20 61 6e 64 20 74 68 65 0a  defined and the.
35b0: 2a 2a 20 61 73 73 65 72 74 28 29 20 6d 61 63 72  ** assert() macr
35c0: 6f 20 69 73 20 65 6e 61 62 6c 65 64 2c 20 65 61  o is enabled, ea
35d0: 63 68 20 63 61 6c 6c 20 69 6e 74 6f 20 74 68 65  ch call into the
35e0: 20 57 69 6e 33 32 20 6e 61 74 69 76 65 20 68 65   Win32 native he
35f0: 61 70 20 73 75 62 73 79 73 74 65 6d 0a 2a 2a 20  ap subsystem.** 
3600: 77 69 6c 6c 20 63 61 75 73 65 20 48 65 61 70 56  will cause HeapV
3610: 61 6c 69 64 61 74 65 20 74 6f 20 62 65 20 63 61  alidate to be ca
3620: 6c 6c 65 64 2e 20 20 49 66 20 68 65 61 70 20 76  lled.  If heap v
3630: 61 6c 69 64 61 74 69 6f 6e 20 73 68 6f 75 6c 64  alidation should
3640: 20 66 61 69 6c 2c 20 61 6e 0a 2a 2a 20 61 73 73   fail, an.** ass
3650: 65 72 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 74  ertion will be t
3660: 72 69 67 67 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20  riggered..**.** 
3670: 49 66 20 6e 6f 6e 65 20 6f 66 20 74 68 65 20 61  If none of the a
3680: 62 6f 76 65 20 61 72 65 20 64 65 66 69 6e 65 64  bove are defined
3690: 2c 20 74 68 65 6e 20 73 65 74 20 53 51 4c 49 54  , then set SQLIT
36a0: 45 5f 53 59 53 54 45 4d 5f 4d 41 4c 4c 4f 43 20  E_SYSTEM_MALLOC 
36b0: 61 73 0a 2a 2a 20 74 68 65 20 64 65 66 61 75 6c  as.** the defaul
36c0: 74 2e 0a 2a 2f 0a 23 69 66 20 64 65 66 69 6e 65  t..*/.#if define
36d0: 64 28 53 51 4c 49 54 45 5f 53 59 53 54 45 4d 5f  d(SQLITE_SYSTEM_
36e0: 4d 41 4c 4c 4f 43 29 20 5c 0a 20 20 2b 20 64 65  MALLOC) \.  + de
36f0: 66 69 6e 65 64 28 53 51 4c 49 54 45 5f 57 49 4e  fined(SQLITE_WIN
3700: 33 32 5f 4d 41 4c 4c 4f 43 29 20 5c 0a 20 20 2b  32_MALLOC) \.  +
3710: 20 64 65 66 69 6e 65 64 28 53 51 4c 49 54 45 5f   defined(SQLITE_
3720: 5a 45 52 4f 5f 4d 41 4c 4c 4f 43 29 20 5c 0a 20  ZERO_MALLOC) \. 
3730: 20 2b 20 64 65 66 69 6e 65 64 28 53 51 4c 49 54   + defined(SQLIT
3740: 45 5f 4d 45 4d 44 45 42 55 47 29 3e 31 0a 23 20  E_MEMDEBUG)>1.# 
3750: 65 72 72 6f 72 20 22 54 77 6f 20 6f 72 20 6d 6f  error "Two or mo
3760: 72 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77  re of the follow
3770: 69 6e 67 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  ing compile-time
3780: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
3790: 70 74 69 6f 6e 73 5c 0a 20 61 72 65 20 64 65 66  ptions\. are def
37a0: 69 6e 65 64 20 62 75 74 20 61 74 20 6d 6f 73 74  ined but at most
37b0: 20 6f 6e 65 20 69 73 20 61 6c 6c 6f 77 65 64 3a   one is allowed:
37c0: 5c 0a 20 53 51 4c 49 54 45 5f 53 59 53 54 45 4d  \. SQLITE_SYSTEM
37d0: 5f 4d 41 4c 4c 4f 43 2c 20 53 51 4c 49 54 45 5f  _MALLOC, SQLITE_
37e0: 57 49 4e 33 32 5f 4d 41 4c 4c 4f 43 2c 20 53 51  WIN32_MALLOC, SQ
37f0: 4c 49 54 45 5f 4d 45 4d 44 45 42 55 47 2c 5c 0a  LITE_MEMDEBUG,\.
3800: 20 53 51 4c 49 54 45 5f 5a 45 52 4f 5f 4d 41 4c   SQLITE_ZERO_MAL
3810: 4c 4f 43 22 0a 23 65 6e 64 69 66 0a 23 69 66 20  LOC".#endif.#if 
3820: 64 65 66 69 6e 65 64 28 53 51 4c 49 54 45 5f 53  defined(SQLITE_S
3830: 59 53 54 45 4d 5f 4d 41 4c 4c 4f 43 29 20 5c 0a  YSTEM_MALLOC) \.
3840: 20 20 2b 20 64 65 66 69 6e 65 64 28 53 51 4c 49    + defined(SQLI
3850: 54 45 5f 57 49 4e 33 32 5f 4d 41 4c 4c 4f 43 29  TE_WIN32_MALLOC)
3860: 20 5c 0a 20 20 2b 20 64 65 66 69 6e 65 64 28 53   \.  + defined(S
3870: 51 4c 49 54 45 5f 5a 45 52 4f 5f 4d 41 4c 4c 4f  QLITE_ZERO_MALLO
3880: 43 29 20 5c 0a 20 20 2b 20 64 65 66 69 6e 65 64  C) \.  + defined
3890: 28 53 51 4c 49 54 45 5f 4d 45 4d 44 45 42 55 47  (SQLITE_MEMDEBUG
38a0: 29 3d 3d 30 0a 23 20 64 65 66 69 6e 65 20 53 51  )==0.# define SQ
38b0: 4c 49 54 45 5f 53 59 53 54 45 4d 5f 4d 41 4c 4c  LITE_SYSTEM_MALL
38c0: 4f 43 20 31 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a  OC 1.#endif../*.
38d0: 2a 2a 20 49 66 20 53 51 4c 49 54 45 5f 4d 41 4c  ** If SQLITE_MAL
38e0: 4c 4f 43 5f 53 4f 46 54 5f 4c 49 4d 49 54 20 69  LOC_SOFT_LIMIT i
38f0: 73 20 6e 6f 74 20 7a 65 72 6f 2c 20 74 68 65 6e  s not zero, then
3900: 20 74 72 79 20 74 6f 20 6b 65 65 70 20 74 68 65   try to keep the
3910: 0a 2a 2a 20 73 69 7a 65 73 20 6f 66 20 6d 65 6d  .** sizes of mem
3920: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20  ory allocations 
3930: 62 65 6c 6f 77 20 74 68 69 73 20 76 61 6c 75 65  below this value
3940: 20 77 68 65 72 65 20 70 6f 73 73 69 62 6c 65 2e   where possible.
3950: 0a 2a 2f 0a 23 69 66 20 21 64 65 66 69 6e 65 64  .*/.#if !defined
3960: 28 53 51 4c 49 54 45 5f 4d 41 4c 4c 4f 43 5f 53  (SQLITE_MALLOC_S
3970: 4f 46 54 5f 4c 49 4d 49 54 29 0a 23 20 64 65 66  OFT_LIMIT).# def
3980: 69 6e 65 20 53 51 4c 49 54 45 5f 4d 41 4c 4c 4f  ine SQLITE_MALLO
3990: 43 5f 53 4f 46 54 5f 4c 49 4d 49 54 20 31 30 32  C_SOFT_LIMIT 102
39a0: 34 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20  4.#endif../*.** 
39b0: 57 65 20 6e 65 65 64 20 74 6f 20 64 65 66 69 6e  We need to defin
39c0: 65 20 5f 58 4f 50 45 4e 5f 53 4f 55 52 43 45 20  e _XOPEN_SOURCE 
39d0: 61 73 20 66 6f 6c 6c 6f 77 73 20 69 6e 20 6f 72  as follows in or
39e0: 64 65 72 20 74 6f 20 65 6e 61 62 6c 65 0a 2a 2a  der to enable.**
39f0: 20 72 65 63 75 72 73 69 76 65 20 6d 75 74 65 78   recursive mutex
3a00: 65 73 20 6f 6e 20 6d 6f 73 74 20 55 6e 69 78 20  es on most Unix 
3a10: 73 79 73 74 65 6d 73 20 61 6e 64 20 66 63 68 6d  systems and fchm
3a20: 6f 64 28 29 20 6f 6e 20 4f 70 65 6e 42 53 44 2e  od() on OpenBSD.
3a30: 0a 2a 2a 20 42 75 74 20 5f 58 4f 50 45 4e 5f 53  .** But _XOPEN_S
3a40: 4f 55 52 43 45 20 64 65 66 69 6e 65 20 63 61 75  OURCE define cau
3a50: 73 65 73 20 70 72 6f 62 6c 65 6d 73 20 66 6f 72  ses problems for
3a60: 20 4d 61 63 20 4f 53 20 58 2c 20 73 6f 20 6f 6d   Mac OS X, so om
3a70: 69 74 0a 2a 2a 20 69 74 2e 0a 2a 2f 0a 23 69 66  it.** it..*/.#if
3a80: 20 21 64 65 66 69 6e 65 64 28 5f 58 4f 50 45 4e   !defined(_XOPEN
3a90: 5f 53 4f 55 52 43 45 29 20 26 26 20 21 64 65 66  _SOURCE) && !def
3aa0: 69 6e 65 64 28 5f 5f 44 41 52 57 49 4e 5f 5f 29  ined(__DARWIN__)
3ab0: 20 26 26 20 21 64 65 66 69 6e 65 64 28 5f 5f 41   && !defined(__A
3ac0: 50 50 4c 45 5f 5f 29 0a 23 20 20 64 65 66 69 6e  PPLE__).#  defin
3ad0: 65 20 5f 58 4f 50 45 4e 5f 53 4f 55 52 43 45 20  e _XOPEN_SOURCE 
3ae0: 36 30 30 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a  600.#endif../*.*
3af0: 2a 20 4e 44 45 42 55 47 20 61 6e 64 20 53 51 4c  * NDEBUG and SQL
3b00: 49 54 45 5f 44 45 42 55 47 20 61 72 65 20 6f 70  ITE_DEBUG are op
3b10: 70 6f 73 69 74 65 73 2e 20 20 49 74 20 73 68 6f  posites.  It sho
3b20: 75 6c 64 20 61 6c 77 61 79 73 20 62 65 20 74 72  uld always be tr
3b30: 75 65 20 74 68 61 74 0a 2a 2a 20 64 65 66 69 6e  ue that.** defin
3b40: 65 64 28 4e 44 45 42 55 47 29 3d 3d 21 64 65 66  ed(NDEBUG)==!def
3b50: 69 6e 65 64 28 53 51 4c 49 54 45 5f 44 45 42 55  ined(SQLITE_DEBU
3b60: 47 29 2e 20 20 49 66 20 74 68 69 73 20 69 73 20  G).  If this is 
3b70: 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 74 72  not currently tr
3b80: 75 65 2c 0a 2a 2a 20 6d 61 6b 65 20 69 74 20 74  ue,.** make it t
3b90: 72 75 65 20 62 79 20 64 65 66 69 6e 69 6e 67 20  rue by defining 
3ba0: 6f 72 20 75 6e 64 65 66 69 6e 69 6e 67 20 4e 44  or undefining ND
3bb0: 45 42 55 47 2e 0a 2a 2a 0a 2a 2a 20 53 65 74 74  EBUG..**.** Sett
3bc0: 69 6e 67 20 4e 44 45 42 55 47 20 6d 61 6b 65 73  ing NDEBUG makes
3bd0: 20 74 68 65 20 63 6f 64 65 20 73 6d 61 6c 6c 65   the code smalle
3be0: 72 20 61 6e 64 20 66 61 73 74 65 72 20 62 79 20  r and faster by 
3bf0: 64 69 73 61 62 6c 69 6e 67 20 74 68 65 0a 2a 2a  disabling the.**
3c00: 20 61 73 73 65 72 74 28 29 20 73 74 61 74 65 6d   assert() statem
3c10: 65 6e 74 73 20 69 6e 20 74 68 65 20 63 6f 64 65  ents in the code
3c20: 2e 20 20 53 6f 20 77 65 20 77 61 6e 74 20 74 68  .  So we want th
3c30: 65 20 64 65 66 61 75 6c 74 20 61 63 74 69 6f 6e  e default action
3c40: 0a 2a 2a 20 74 6f 20 62 65 20 66 6f 72 20 4e 44  .** to be for ND
3c50: 45 42 55 47 20 74 6f 20 62 65 20 73 65 74 20 61  EBUG to be set a
3c60: 6e 64 20 4e 44 45 42 55 47 20 74 6f 20 62 65 20  nd NDEBUG to be 
3c70: 75 6e 64 65 66 69 6e 65 64 20 6f 6e 6c 79 20 69  undefined only i
3c80: 66 20 53 51 4c 49 54 45 5f 44 45 42 55 47 0a 2a  f SQLITE_DEBUG.*
3c90: 2a 20 69 73 20 73 65 74 2e 20 20 54 68 75 73 20  * is set.  Thus 
3ca0: 4e 44 45 42 55 47 20 62 65 63 6f 6d 65 73 20 61  NDEBUG becomes a
3cb0: 6e 20 6f 70 74 2d 69 6e 20 72 61 74 68 65 72 20  n opt-in rather 
3cc0: 74 68 61 6e 20 61 6e 20 6f 70 74 2d 6f 75 74 0a  than an opt-out.
3cd0: 2a 2a 20 66 65 61 74 75 72 65 2e 0a 2a 2f 0a 23  ** feature..*/.#
3ce0: 69 66 20 21 64 65 66 69 6e 65 64 28 4e 44 45 42  if !defined(NDEB
3cf0: 55 47 29 20 26 26 20 21 64 65 66 69 6e 65 64 28  UG) && !defined(
3d00: 53 51 4c 49 54 45 5f 44 45 42 55 47 29 20 0a 23  SQLITE_DEBUG) .#
3d10: 20 64 65 66 69 6e 65 20 4e 44 45 42 55 47 20 31   define NDEBUG 1
3d20: 0a 23 65 6e 64 69 66 0a 23 69 66 20 64 65 66 69  .#endif.#if defi
3d30: 6e 65 64 28 4e 44 45 42 55 47 29 20 26 26 20 64  ned(NDEBUG) && d
3d40: 65 66 69 6e 65 64 28 53 51 4c 49 54 45 5f 44 45  efined(SQLITE_DE
3d50: 42 55 47 29 0a 23 20 75 6e 64 65 66 20 4e 44 45  BUG).# undef NDE
3d60: 42 55 47 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a  BUG.#endif../*.*
3d70: 2a 20 54 68 65 20 74 65 73 74 63 61 73 65 28 29  * The testcase()
3d80: 20 6d 61 63 72 6f 20 69 73 20 75 73 65 64 20 74   macro is used t
3d90: 6f 20 61 69 64 20 69 6e 20 63 6f 76 65 72 61 67  o aid in coverag
3da0: 65 20 74 65 73 74 69 6e 67 2e 20 20 57 68 65 6e  e testing.  When
3db0: 20 0a 2a 2a 20 64 6f 69 6e 67 20 63 6f 76 65 72   .** doing cover
3dc0: 61 67 65 20 74 65 73 74 69 6e 67 2c 20 74 68 65  age testing, the
3dd0: 20 63 6f 6e 64 69 74 69 6f 6e 20 69 6e 73 69 64   condition insid
3de0: 65 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74  e the argument t
3df0: 6f 0a 2a 2a 20 74 65 73 74 63 61 73 65 28 29 20  o.** testcase() 
3e00: 6d 75 73 74 20 62 65 20 65 76 61 6c 75 61 74 65  must be evaluate
3e10: 64 20 62 6f 74 68 20 74 72 75 65 20 61 6e 64 20  d both true and 
3e20: 66 61 6c 73 65 20 69 6e 20 6f 72 64 65 72 20 74  false in order t
3e30: 6f 0a 2a 2a 20 67 65 74 20 66 75 6c 6c 20 62 72  o.** get full br
3e40: 61 6e 63 68 20 63 6f 76 65 72 61 67 65 2e 20 20  anch coverage.  
3e50: 54 68 65 20 74 65 73 74 63 61 73 65 28 29 20 6d  The testcase() m
3e60: 61 63 72 6f 20 69 73 20 69 6e 73 65 72 74 65 64  acro is inserted
3e70: 0a 2a 2a 20 74 6f 20 68 65 6c 70 20 65 6e 73 75  .** to help ensu
3e80: 72 65 20 61 64 65 71 75 61 74 65 20 74 65 73 74  re adequate test
3e90: 20 63 6f 76 65 72 61 67 65 20 69 6e 20 70 6c 61   coverage in pla
3ea0: 63 65 73 20 77 68 65 72 65 20 73 69 6d 70 6c 65  ces where simple
3eb0: 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 2f 64 65  .** condition/de
3ec0: 63 69 73 69 6f 6e 20 63 6f 76 65 72 61 67 65 20  cision coverage 
3ed0: 69 73 20 69 6e 61 64 65 71 75 61 74 65 2e 20 20  is inadequate.  
3ee0: 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 74 65 73  For example, tes
3ef0: 74 63 61 73 65 28 29 0a 2a 2a 20 63 61 6e 20 62  tcase().** can b
3f00: 65 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 73  e used to make s
3f10: 75 72 65 20 62 6f 75 6e 64 61 72 79 20 76 61 6c  ure boundary val
3f20: 75 65 73 20 61 72 65 20 74 65 73 74 65 64 2e 20  ues are tested. 
3f30: 20 46 6f 72 0a 2a 2a 20 62 69 74 6d 61 73 6b 20   For.** bitmask 
3f40: 74 65 73 74 73 2c 20 74 65 73 74 63 61 73 65 28  tests, testcase(
3f50: 29 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  ) can be used to
3f60: 20 6d 61 6b 65 20 73 75 72 65 20 65 61 63 68 20   make sure each 
3f70: 62 69 74 0a 2a 2a 20 69 73 20 73 69 67 6e 69 66  bit.** is signif
3f80: 69 63 61 6e 74 20 61 6e 64 20 75 73 65 64 20 61  icant and used a
3f90: 74 20 6c 65 61 73 74 20 6f 6e 63 65 2e 20 20 4f  t least once.  O
3fa0: 6e 20 73 77 69 74 63 68 20 73 74 61 74 65 6d 65  n switch stateme
3fb0: 6e 74 73 0a 2a 2a 20 77 68 65 72 65 20 6d 75 6c  nts.** where mul
3fc0: 74 69 70 6c 65 20 63 61 73 65 73 20 67 6f 20 74  tiple cases go t
3fd0: 6f 20 74 68 65 20 73 61 6d 65 20 62 6c 6f 63 6b  o the same block
3fe0: 20 6f 66 20 63 6f 64 65 2c 20 74 65 73 74 63 61   of code, testca
3ff0: 73 65 28 29 0a 2a 2a 20 63 61 6e 20 69 6e 73 75  se().** can insu
4000: 72 65 20 74 68 61 74 20 61 6c 6c 20 63 61 73 65  re that all case
4010: 73 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 2e  s are evaluated.
4020: 0a 2a 2a 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51  .**.*/.#ifdef SQ
4030: 4c 49 54 45 5f 43 4f 56 45 52 41 47 45 5f 54 45  LITE_COVERAGE_TE
4040: 53 54 0a 53 51 4c 49 54 45 5f 50 52 49 56 41 54  ST.SQLITE_PRIVAT
4050: 45 20 20 20 76 6f 69 64 20 73 71 6c 69 74 65 33  E   void sqlite3
4060: 43 6f 76 65 72 61 67 65 28 69 6e 74 29 3b 0a 23  Coverage(int);.#
4070: 20 64 65 66 69 6e 65 20 74 65 73 74 63 61 73 65   define testcase
4080: 28 58 29 20 20 69 66 28 20 58 20 29 7b 20 73 71  (X)  if( X ){ sq
4090: 6c 69 74 65 33 43 6f 76 65 72 61 67 65 28 5f 5f  lite3Coverage(__
40a0: 4c 49 4e 45 5f 5f 29 3b 20 7d 0a 23 65 6c 73 65  LINE__); }.#else
40b0: 0a 23 20 64 65 66 69 6e 65 20 74 65 73 74 63 61  .# define testca
40c0: 73 65 28 58 29 0a 23 65 6e 64 69 66 0a 0a 2f 2a  se(X).#endif../*
40d0: 0a 2a 2a 20 54 68 65 20 54 45 53 54 4f 4e 4c 59  .** The TESTONLY
40e0: 20 6d 61 63 72 6f 20 69 73 20 75 73 65 64 20 74   macro is used t
40f0: 6f 20 65 6e 63 6c 6f 73 65 20 76 61 72 69 61 62  o enclose variab
4100: 6c 65 20 64 65 63 6c 61 72 61 74 69 6f 6e 73 20  le declarations 
4110: 6f 72 0a 2a 2a 20 6f 74 68 65 72 20 62 69 74 73  or.** other bits
4120: 20 6f 66 20 63 6f 64 65 20 74 68 61 74 20 61 72   of code that ar
4130: 65 20 6e 65 65 64 65 64 20 74 6f 20 73 75 70 70  e needed to supp
4140: 6f 72 74 20 74 68 65 20 61 72 67 75 6d 65 6e 74  ort the argument
4150: 73 0a 2a 2a 20 77 69 74 68 69 6e 20 74 65 73 74  s.** within test
4160: 63 61 73 65 28 29 20 61 6e 64 20 61 73 73 65 72  case() and asser
4170: 74 28 29 20 6d 61 63 72 6f 73 2e 0a 2a 2f 0a 23  t() macros..*/.#
4180: 69 66 20 21 64 65 66 69 6e 65 64 28 4e 44 45 42  if !defined(NDEB
4190: 55 47 29 20 7c 7c 20 64 65 66 69 6e 65 64 28 53  UG) || defined(S
41a0: 51 4c 49 54 45 5f 43 4f 56 45 52 41 47 45 5f 54  QLITE_COVERAGE_T
41b0: 45 53 54 29 0a 23 20 64 65 66 69 6e 65 20 54 45  EST).# define TE
41c0: 53 54 4f 4e 4c 59 28 58 29 20 20 58 0a 23 65 6c  STONLY(X)  X.#el
41d0: 73 65 0a 23 20 64 65 66 69 6e 65 20 54 45 53 54  se.# define TEST
41e0: 4f 4e 4c 59 28 58 29 0a 23 65 6e 64 69 66 0a 0a  ONLY(X).#endif..
41f0: 2f 2a 0a 2a 2a 20 53 6f 6d 65 74 69 6d 65 73 20  /*.** Sometimes 
4200: 77 65 20 6e 65 65 64 20 61 20 73 6d 61 6c 6c 20  we need a small 
4210: 61 6d 6f 75 6e 74 20 6f 66 20 63 6f 64 65 20 73  amount of code s
4220: 75 63 68 20 61 73 20 61 20 76 61 72 69 61 62 6c  uch as a variabl
4230: 65 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  e initialization
4240: 0a 2a 2a 20 74 6f 20 73 65 74 75 70 20 66 6f 72  .** to setup for
4250: 20 61 20 6c 61 74 65 72 20 61 73 73 65 72 74 28   a later assert(
4260: 29 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 57 65  ) statement.  We
4270: 20 64 6f 20 6e 6f 74 20 77 61 6e 74 20 74 68 69   do not want thi
4280: 73 20 63 6f 64 65 20 74 6f 0a 2a 2a 20 61 70 70  s code to.** app
4290: 65 61 72 20 77 68 65 6e 20 61 73 73 65 72 74 28  ear when assert(
42a0: 29 20 69 73 20 64 69 73 61 62 6c 65 64 2e 20 20  ) is disabled.  
42b0: 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 6d 61  The following ma
42c0: 63 72 6f 20 69 73 20 74 68 65 72 65 66 6f 72 65  cro is therefore
42d0: 0a 2a 2a 20 75 73 65 64 20 74 6f 20 63 6f 6e 74  .** used to cont
42e0: 61 69 6e 20 74 68 61 74 20 73 65 74 75 70 20 63  ain that setup c
42f0: 6f 64 65 2e 20 20 54 68 65 20 22 56 56 41 22 20  ode.  The "VVA" 
4300: 61 63 72 6f 6e 79 6d 20 73 74 61 6e 64 73 20 66  acronym stands f
4310: 6f 72 0a 2a 2a 20 22 56 65 72 69 66 69 63 61 74  or.** "Verificat
4320: 69 6f 6e 2c 20 56 61 6c 69 64 61 74 69 6f 6e 2c  ion, Validation,
4330: 20 61 6e 64 20 41 63 63 72 65 64 69 74 61 74 69   and Accreditati
4340: 6f 6e 22 2e 20 20 49 6e 20 6f 74 68 65 72 20 77  on".  In other w
4350: 6f 72 64 73 2c 20 74 68 65 0a 2a 2a 20 63 6f 64  ords, the.** cod
4360: 65 20 77 69 74 68 69 6e 20 56 56 41 5f 4f 4e 4c  e within VVA_ONL
4370: 59 28 29 20 77 69 6c 6c 20 6f 6e 6c 79 20 72 75  Y() will only ru
4380: 6e 20 64 75 72 69 6e 67 20 76 65 72 69 66 69 63  n during verific
4390: 61 74 69 6f 6e 20 70 72 6f 63 65 73 73 65 73 2e  ation processes.
43a0: 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 4e 44 45 42  .*/.#ifndef NDEB
43b0: 55 47 0a 23 20 64 65 66 69 6e 65 20 56 56 41 5f  UG.# define VVA_
43c0: 4f 4e 4c 59 28 58 29 20 20 58 0a 23 65 6c 73 65  ONLY(X)  X.#else
43d0: 0a 23 20 64 65 66 69 6e 65 20 56 56 41 5f 4f 4e  .# define VVA_ON
43e0: 4c 59 28 58 29 0a 23 65 6e 64 69 66 0a 0a 2f 2a  LY(X).#endif../*
43f0: 0a 2a 2a 20 54 68 65 20 41 4c 57 41 59 53 20 61  .** The ALWAYS a
4400: 6e 64 20 4e 45 56 45 52 20 6d 61 63 72 6f 73 20  nd NEVER macros 
4410: 73 75 72 72 6f 75 6e 64 20 62 6f 6f 6c 65 61 6e  surround boolean
4420: 20 65 78 70 72 65 73 73 69 6f 6e 73 20 77 68 69   expressions whi
4430: 63 68 20 0a 2a 2a 20 61 72 65 20 69 6e 74 65 6e  ch .** are inten
4440: 64 65 64 20 74 6f 20 61 6c 77 61 79 73 20 62 65  ded to always be
4450: 20 74 72 75 65 20 6f 72 20 66 61 6c 73 65 2c 20   true or false, 
4460: 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20 20 53  respectively.  S
4470: 75 63 68 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f  uch.** expressio
4480: 6e 73 20 63 6f 75 6c 64 20 62 65 20 6f 6d 69 74  ns could be omit
4490: 74 65 64 20 66 72 6f 6d 20 74 68 65 20 63 6f 64  ted from the cod
44a0: 65 20 63 6f 6d 70 6c 65 74 65 6c 79 2e 20 20 42  e completely.  B
44b0: 75 74 20 74 68 65 79 0a 2a 2a 20 61 72 65 20 69  ut they.** are i
44c0: 6e 63 6c 75 64 65 64 20 69 6e 20 61 20 66 65 77  ncluded in a few
44d0: 20 63 61 73 65 73 20 69 6e 20 6f 72 64 65 72 20   cases in order 
44e0: 74 6f 20 65 6e 68 61 6e 63 65 20 74 68 65 20 72  to enhance the r
44f0: 65 73 69 6c 69 65 6e 63 65 0a 2a 2a 20 6f 66 20  esilience.** of 
4500: 53 51 4c 69 74 65 20 74 6f 20 75 6e 65 78 70 65  SQLite to unexpe
4510: 63 74 65 64 20 62 65 68 61 76 69 6f 72 20 2d 20  cted behavior - 
4520: 74 6f 20 6d 61 6b 65 20 74 68 65 20 63 6f 64 65  to make the code
4530: 20 22 73 65 6c 66 2d 68 65 61 6c 69 6e 67 22 0a   "self-healing".
4540: 2a 2a 20 6f 72 20 22 64 75 63 74 69 6c 65 22 20  ** or "ductile" 
4550: 72 61 74 68 65 72 20 74 68 61 6e 20 62 65 69 6e  rather than bein
4560: 67 20 22 62 72 69 74 74 6c 65 22 20 61 6e 64 20  g "brittle" and 
4570: 63 72 61 73 68 69 6e 67 20 61 74 20 74 68 65 20  crashing at the 
4580: 66 69 72 73 74 0a 2a 2a 20 68 69 6e 74 20 6f 66  first.** hint of
4590: 20 75 6e 70 6c 61 6e 6e 65 64 20 62 65 68 61 76   unplanned behav
45a0: 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74  ior..**.** In ot
45b0: 68 65 72 20 77 6f 72 64 73 2c 20 41 4c 57 41 59  her words, ALWAY
45c0: 53 20 61 6e 64 20 4e 45 56 45 52 20 61 72 65 20  S and NEVER are 
45d0: 61 64 64 65 64 20 66 6f 72 20 64 65 66 65 6e 73  added for defens
45e0: 69 76 65 20 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20  ive code..**.** 
45f0: 57 68 65 6e 20 64 6f 69 6e 67 20 63 6f 76 65 72  When doing cover
4600: 61 67 65 20 74 65 73 74 69 6e 67 20 41 4c 57 41  age testing ALWA
4610: 59 53 20 61 6e 64 20 4e 45 56 45 52 20 61 72 65  YS and NEVER are
4620: 20 68 61 72 64 2d 63 6f 64 65 64 20 74 6f 0a 2a   hard-coded to.*
4630: 2a 20 62 65 20 74 72 75 65 20 61 6e 64 20 66 61  * be true and fa
4640: 6c 73 65 20 73 6f 20 74 68 61 74 20 74 68 65 20  lse so that the 
4650: 75 6e 72 65 61 63 68 61 62 6c 65 20 63 6f 64 65  unreachable code
4660: 20 74 68 65 79 20 73 70 65 63 69 66 79 20 77 69   they specify wi
4670: 6c 6c 0a 2a 2a 20 6e 6f 74 20 62 65 20 63 6f 75  ll.** not be cou
4680: 6e 74 65 64 20 61 73 20 75 6e 74 65 73 74 65 64  nted as untested
4690: 20 63 6f 64 65 2e 0a 2a 2f 0a 23 69 66 20 64 65   code..*/.#if de
46a0: 66 69 6e 65 64 28 53 51 4c 49 54 45 5f 43 4f 56  fined(SQLITE_COV
46b0: 45 52 41 47 45 5f 54 45 53 54 29 0a 23 20 64 65  ERAGE_TEST).# de
46c0: 66 69 6e 65 20 41 4c 57 41 59 53 28 58 29 20 20  fine ALWAYS(X)  
46d0: 20 20 20 20 28 31 29 0a 23 20 64 65 66 69 6e 65      (1).# define
46e0: 20 4e 45 56 45 52 28 58 29 20 20 20 20 20 20 20   NEVER(X)       
46f0: 28 30 29 0a 23 65 6c 69 66 20 21 64 65 66 69 6e  (0).#elif !defin
4700: 65 64 28 4e 44 45 42 55 47 29 0a 23 20 64 65 66  ed(NDEBUG).# def
4710: 69 6e 65 20 41 4c 57 41 59 53 28 58 29 20 20 20  ine ALWAYS(X)   
4720: 20 20 20 28 28 58 29 3f 31 3a 28 61 73 73 65 72     ((X)?1:(asser
4730: 74 28 30 29 2c 30 29 29 0a 23 20 64 65 66 69 6e  t(0),0)).# defin
4740: 65 20 4e 45 56 45 52 28 58 29 20 20 20 20 20 20  e NEVER(X)      
4750: 20 28 28 58 29 3f 28 61 73 73 65 72 74 28 30 29   ((X)?(assert(0)
4760: 2c 31 29 3a 30 29 0a 23 65 6c 73 65 0a 23 20 64  ,1):0).#else.# d
4770: 65 66 69 6e 65 20 41 4c 57 41 59 53 28 58 29 20  efine ALWAYS(X) 
4780: 20 20 20 20 20 28 58 29 0a 23 20 64 65 66 69 6e       (X).# defin
4790: 65 20 4e 45 56 45 52 28 58 29 20 20 20 20 20 20  e NEVER(X)      
47a0: 20 28 58 29 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a   (X).#endif../*.
47b0: 2a 2a 20 52 65 74 75 72 6e 20 74 72 75 65 20 28  ** Return true (
47c0: 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 20 74 68 65  non-zero) if the
47d0: 20 69 6e 70 75 74 20 69 73 20 61 20 69 6e 74 65   input is a inte
47e0: 67 65 72 20 74 68 61 74 20 69 73 20 74 6f 6f 20  ger that is too 
47f0: 6c 61 72 67 65 0a 2a 2a 20 74 6f 20 66 69 74 20  large.** to fit 
4800: 69 6e 20 33 32 2d 62 69 74 73 2e 20 20 54 68 69  in 32-bits.  Thi
4810: 73 20 6d 61 63 72 6f 20 69 73 20 75 73 65 64 20  s macro is used 
4820: 69 6e 73 69 64 65 20 6f 66 20 76 61 72 69 6f 75  inside of variou
4830: 73 20 74 65 73 74 63 61 73 65 28 29 0a 2a 2a 20  s testcase().** 
4840: 6d 61 63 72 6f 73 20 74 6f 20 76 65 72 69 66 79  macros to verify
4850: 20 74 68 61 74 20 77 65 20 68 61 76 65 20 74 65   that we have te
4860: 73 74 65 64 20 53 51 4c 69 74 65 20 66 6f 72 20  sted SQLite for 
4870: 6c 61 72 67 65 2d 66 69 6c 65 20 73 75 70 70 6f  large-file suppo
4880: 72 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 49  rt..*/.#define I
4890: 53 5f 42 49 47 5f 49 4e 54 28 58 29 20 20 28 28  S_BIG_INT(X)  ((
48a0: 28 58 29 26 7e 28 69 36 34 29 30 78 66 66 66 66  (X)&~(i64)0xffff
48b0: 66 66 66 66 29 21 3d 30 29 0a 0a 2f 2a 0a 2a 2a  ffff)!=0)../*.**
48c0: 20 54 68 65 20 6d 61 63 72 6f 20 75 6e 6c 69 6b   The macro unlik
48d0: 65 6c 79 28 29 20 69 73 20 61 20 68 69 6e 74 20  ely() is a hint 
48e0: 74 68 61 74 20 73 75 72 72 6f 75 6e 64 73 20 61  that surrounds a
48f0: 20 62 6f 6f 6c 65 61 6e 0a 2a 2a 20 65 78 70 72   boolean.** expr
4900: 65 73 73 69 6f 6e 20 74 68 61 74 20 69 73 20 75  ession that is u
4910: 73 75 61 6c 6c 79 20 66 61 6c 73 65 2e 20 20 4d  sually false.  M
4920: 61 63 72 6f 20 6c 69 6b 65 6c 79 28 29 20 73 75  acro likely() su
4930: 72 72 6f 75 6e 64 73 0a 2a 2a 20 61 20 62 6f 6f  rrounds.** a boo
4940: 6c 65 61 6e 20 65 78 70 72 65 73 73 69 6f 6e 20  lean expression 
4950: 74 68 61 74 20 69 73 20 75 73 75 61 6c 6c 79 20  that is usually 
4960: 74 72 75 65 2e 20 20 54 68 65 73 65 20 68 69 6e  true.  These hin
4970: 74 73 20 63 6f 75 6c 64 2c 0a 2a 2a 20 69 6e 20  ts could,.** in 
4980: 74 68 65 6f 72 79 2c 20 62 65 20 75 73 65 64 20  theory, be used 
4990: 62 79 20 74 68 65 20 63 6f 6d 70 69 6c 65 72 20  by the compiler 
49a0: 74 6f 20 67 65 6e 65 72 61 74 65 20 62 65 74 74  to generate bett
49b0: 65 72 20 63 6f 64 65 2c 20 62 75 74 0a 2a 2a 20  er code, but.** 
49c0: 63 75 72 72 65 6e 74 6c 79 20 74 68 65 79 20 61  currently they a
49d0: 72 65 20 6a 75 73 74 20 63 6f 6d 6d 65 6e 74 73  re just comments
49e0: 20 66 6f 72 20 68 75 6d 61 6e 20 72 65 61 64 65   for human reade
49f0: 72 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 6c  rs..*/.#define l
4a00: 69 6b 65 6c 79 28 58 29 20 20 20 20 28 58 29 0a  ikely(X)    (X).
4a10: 23 64 65 66 69 6e 65 20 75 6e 6c 69 6b 65 6c 79  #define unlikely
4a20: 28 58 29 20 20 28 58 29 0a 0a 2f 2a 2a 2a 2a 2a  (X)  (X)../*****
4a30: 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 49 6e 63 6c 75 64  ********* Includ
4a40: 65 20 73 71 6c 69 74 65 33 2e 68 20 69 6e 20 74  e sqlite3.h in t
4a50: 68 65 20 6d 69 64 64 6c 65 20 6f 66 20 73 71 6c  he middle of sql
4a60: 69 74 65 49 6e 74 2e 68 20 2a 2a 2a 2a 2a 2a 2a  iteInt.h *******
4a70: 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a 2a 2a 2a 2a  ********/./*****
4a80: 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 42 65 67 69 6e 20  ********* Begin 
4a90: 66 69 6c 65 20 73 71 6c 69 74 65 33 2e 68 20 2a  file sqlite3.h *
4aa0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
4ab0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
4ac0: 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a 0a 2a 2a 20  ********/./*.** 
4ad0: 32 30 30 31 20 53 65 70 74 65 6d 62 65 72 20 31  2001 September 1
4ae0: 35 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68  5.**.** The auth
4af0: 6f 72 20 64 69 73 63 6c 61 69 6d 73 20 63 6f 70  or disclaims cop
4b00: 79 72 69 67 68 74 20 74 6f 20 74 68 69 73 20 73  yright to this s
4b10: 6f 75 72 63 65 20 63 6f 64 65 2e 20 20 49 6e 20  ource code.  In 
4b20: 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 61 20 6c 65  place of.** a le
4b30: 67 61 6c 20 6e 6f 74 69 63 65 2c 20 68 65 72 65  gal notice, here
4b40: 20 69 73 20 61 20 62 6c 65 73 73 69 6e 67 3a 0a   is a blessing:.
4b50: 2a 2a 0a 2a 2a 20 20 20 20 4d 61 79 20 79 6f 75  **.**    May you
4b60: 20 64 6f 20 67 6f 6f 64 20 61 6e 64 20 6e 6f 74   do good and not
4b70: 20 65 76 69 6c 2e 0a 2a 2a 20 20 20 20 4d 61 79   evil..**    May
4b80: 20 79 6f 75 20 66 69 6e 64 20 66 6f 72 67 69 76   you find forgiv
4b90: 65 6e 65 73 73 20 66 6f 72 20 79 6f 75 72 73 65  eness for yourse
4ba0: 6c 66 20 61 6e 64 20 66 6f 72 67 69 76 65 20 6f  lf and forgive o
4bb0: 74 68 65 72 73 2e 0a 2a 2a 20 20 20 20 4d 61 79  thers..**    May
4bc0: 20 79 6f 75 20 73 68 61 72 65 20 66 72 65 65 6c   you share freel
4bd0: 79 2c 20 6e 65 76 65 72 20 74 61 6b 69 6e 67 20  y, never taking 
4be0: 6d 6f 72 65 20 74 68 61 6e 20 79 6f 75 20 67 69  more than you gi
4bf0: 76 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ve..**.*********
4c00: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
4c10: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
4c20: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
4c30: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
4c40: 0a 2a 2a 20 54 68 69 73 20 68 65 61 64 65 72 20  .** This header 
4c50: 66 69 6c 65 20 64 65 66 69 6e 65 73 20 74 68 65  file defines the
4c60: 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20   interface that 
4c70: 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61  the SQLite libra
4c80: 72 79 0a 2a 2a 20 70 72 65 73 65 6e 74 73 20 74  ry.** presents t
4c90: 6f 20 63 6c 69 65 6e 74 20 70 72 6f 67 72 61 6d  o client program
4ca0: 73 2e 20 20 49 66 20 61 20 43 2d 66 75 6e 63 74  s.  If a C-funct
4cb0: 69 6f 6e 2c 20 73 74 72 75 63 74 75 72 65 2c 20  ion, structure, 
4cc0: 64 61 74 61 74 79 70 65 2c 0a 2a 2a 20 6f 72 20  datatype,.** or 
4cd0: 63 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e 69 74  constant definit
4ce0: 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 61 70 70  ion does not app
4cf0: 65 61 72 20 69 6e 20 74 68 69 73 20 66 69 6c 65  ear in this file
4d00: 2c 20 74 68 65 6e 20 69 74 20 69 73 0a 2a 2a 20  , then it is.** 
4d10: 6e 6f 74 20 61 20 70 75 62 6c 69 73 68 65 64 20  not a published 
4d20: 41 50 49 20 6f 66 20 53 51 4c 69 74 65 2c 20 69  API of SQLite, i
4d30: 73 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61  s subject to cha
4d40: 6e 67 65 20 77 69 74 68 6f 75 74 0a 2a 2a 20 6e  nge without.** n
4d50: 6f 74 69 63 65 2c 20 61 6e 64 20 73 68 6f 75 6c  otice, and shoul
4d60: 64 20 6e 6f 74 20 62 65 20 72 65 66 65 72 65 6e  d not be referen
4d70: 63 65 64 20 62 79 20 70 72 6f 67 72 61 6d 73 20  ced by programs 
4d80: 74 68 61 74 20 75 73 65 20 53 51 4c 69 74 65 2e  that use SQLite.
4d90: 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74  .**.** Some of t
4da0: 68 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 20 74  he definitions t
4db0: 68 61 74 20 61 72 65 20 69 6e 20 74 68 69 73 20  hat are in this 
4dc0: 66 69 6c 65 20 61 72 65 20 6d 61 72 6b 65 64 20  file are marked 
4dd0: 61 73 0a 2a 2a 20 22 65 78 70 65 72 69 6d 65 6e  as.** "experimen
4de0: 74 61 6c 22 2e 20 20 45 78 70 65 72 69 6d 65 6e  tal".  Experimen
4df0: 74 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61  tal interfaces a
4e00: 72 65 20 6e 6f 72 6d 61 6c 6c 79 20 6e 65 77 0a  re normally new.
4e10: 2a 2a 20 66 65 61 74 75 72 65 73 20 72 65 63 65  ** features rece
4e20: 6e 74 6c 79 20 61 64 64 65 64 20 74 6f 20 53 51  ntly added to SQ
4e30: 4c 69 74 65 2e 20 20 57 65 20 64 6f 20 6e 6f 74  Lite.  We do not
4e40: 20 61 6e 74 69 63 69 70 61 74 65 20 63 68 61 6e   anticipate chan
4e50: 67 65 73 0a 2a 2a 20 74 6f 20 65 78 70 65 72 69  ges.** to experi
4e60: 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66 61 63 65  mental interface
4e70: 73 20 62 75 74 20 72 65 73 65 72 76 65 20 74 68  s but reserve th
4e80: 65 20 72 69 67 68 74 20 74 6f 20 6d 61 6b 65 20  e right to make 
4e90: 6d 69 6e 6f 72 20 63 68 61 6e 67 65 73 0a 2a 2a  minor changes.**
4ea0: 20 69 66 20 65 78 70 65 72 69 65 6e 63 65 20 66   if experience f
4eb0: 72 6f 6d 20 75 73 65 20 22 69 6e 20 74 68 65 20  rom use "in the 
4ec0: 77 69 6c 64 22 20 73 75 67 67 65 73 74 20 73 75  wild" suggest su
4ed0: 63 68 20 63 68 61 6e 67 65 73 20 61 72 65 20 70  ch changes are p
4ee0: 72 75 64 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68  rudent..**.** Th
4ef0: 65 20 6f 66 66 69 63 69 61 6c 20 43 2d 6c 61 6e  e official C-lan
4f00: 67 75 61 67 65 20 41 50 49 20 64 6f 63 75 6d 65  guage API docume
4f10: 6e 74 61 74 69 6f 6e 20 66 6f 72 20 53 51 4c 69  ntation for SQLi
4f20: 74 65 20 69 73 20 64 65 72 69 76 65 64 0a 2a 2a  te is derived.**
4f30: 20 66 72 6f 6d 20 63 6f 6d 6d 65 6e 74 73 20 69   from comments i
4f40: 6e 20 74 68 69 73 20 66 69 6c 65 2e 20 20 54 68  n this file.  Th
4f50: 69 73 20 66 69 6c 65 20 69 73 20 74 68 65 20 61  is file is the a
4f60: 75 74 68 6f 72 69 74 61 74 69 76 65 20 73 6f 75  uthoritative sou
4f70: 72 63 65 0a 2a 2a 20 6f 6e 20 68 6f 77 20 53 51  rce.** on how SQ
4f80: 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20  Lite interfaces 
4f90: 61 72 65 20 73 75 70 70 6f 73 65 20 74 6f 20 6f  are suppose to o
4fa0: 70 65 72 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  perate..**.** Th
4fb0: 65 20 6e 61 6d 65 20 6f 66 20 74 68 69 73 20 66  e name of this f
4fc0: 69 6c 65 20 75 6e 64 65 72 20 63 6f 6e 66 69 67  ile under config
4fd0: 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65  uration manageme
4fe0: 6e 74 20 69 73 20 22 73 71 6c 69 74 65 2e 68 2e  nt is "sqlite.h.
4ff0: 69 6e 22 2e 0a 2a 2a 20 54 68 65 20 6d 61 6b 65  in"..** The make
5000: 66 69 6c 65 20 6d 61 6b 65 73 20 73 6f 6d 65 20  file makes some 
5010: 6d 69 6e 6f 72 20 63 68 61 6e 67 65 73 20 74 6f  minor changes to
5020: 20 74 68 69 73 20 66 69 6c 65 20 28 73 75 63 68   this file (such
5030: 20 61 73 20 69 6e 73 65 72 74 69 6e 67 0a 2a 2a   as inserting.**
5040: 20 74 68 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d   the version num
5050: 62 65 72 29 20 61 6e 64 20 63 68 61 6e 67 65 73  ber) and changes
5060: 20 69 74 73 20 6e 61 6d 65 20 74 6f 20 22 73 71   its name to "sq
5070: 6c 69 74 65 33 2e 68 22 20 61 73 0a 2a 2a 20 70  lite3.h" as.** p
5080: 61 72 74 20 6f 66 20 74 68 65 20 62 75 69 6c 64  art of the build
5090: 20 70 72 6f 63 65 73 73 2e 0a 2a 2f 0a 23 69 66   process..*/.#if
50a0: 6e 64 65 66 20 5f 53 51 4c 49 54 45 33 5f 48 5f  ndef _SQLITE3_H_
50b0: 0a 23 64 65 66 69 6e 65 20 5f 53 51 4c 49 54 45  .#define _SQLITE
50c0: 33 5f 48 5f 0a 23 69 6e 63 6c 75 64 65 20 3c 73  3_H_.#include <s
50d0: 74 64 61 72 67 2e 68 3e 20 20 20 20 20 2f 2a 20  tdarg.h>     /* 
50e0: 4e 65 65 64 65 64 20 66 6f 72 20 74 68 65 20 64  Needed for the d
50f0: 65 66 69 6e 69 74 69 6f 6e 20 6f 66 20 76 61 5f  efinition of va_
5100: 6c 69 73 74 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 4d  list */../*.** M
5110: 61 6b 65 20 73 75 72 65 20 77 65 20 63 61 6e 20  ake sure we can 
5120: 63 61 6c 6c 20 74 68 69 73 20 73 74 75 66 66 20  call this stuff 
5130: 66 72 6f 6d 20 43 2b 2b 2e 0a 2a 2f 0a 23 69 66  from C++..*/.#if
5140: 20 30 0a 65 78 74 65 72 6e 20 22 43 22 20 7b 0a   0.extern "C" {.
5150: 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a 2a 20 41  #endif.../*.** A
5160: 64 64 20 74 68 65 20 61 62 69 6c 69 74 79 20 74  dd the ability t
5170: 6f 20 6f 76 65 72 72 69 64 65 20 27 65 78 74 65  o override 'exte
5180: 72 6e 27 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53  rn'.*/.#ifndef S
5190: 51 4c 49 54 45 5f 45 58 54 45 52 4e 0a 23 20 64  QLITE_EXTERN.# d
51a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 54  efine SQLITE_EXT
51b0: 45 52 4e 20 65 78 74 65 72 6e 0a 23 65 6e 64 69  ERN extern.#endi
51c0: 66 0a 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54  f..#ifndef SQLIT
51d0: 45 5f 41 50 49 0a 23 20 64 65 66 69 6e 65 20 53  E_API.# define S
51e0: 51 4c 49 54 45 5f 41 50 49 0a 23 65 6e 64 69 66  QLITE_API.#endif
51f0: 0a 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 73 65 20 6e  .../*.** These n
5200: 6f 2d 6f 70 20 6d 61 63 72 6f 73 20 61 72 65 20  o-op macros are 
5210: 75 73 65 64 20 69 6e 20 66 72 6f 6e 74 20 6f 66  used in front of
5220: 20 69 6e 74 65 72 66 61 63 65 73 20 74 6f 20 6d   interfaces to m
5230: 61 72 6b 20 74 68 6f 73 65 0a 2a 2a 20 69 6e 74  ark those.** int
5240: 65 72 66 61 63 65 73 20 61 73 20 65 69 74 68 65  erfaces as eithe
5250: 72 20 64 65 70 72 65 63 61 74 65 64 20 6f 72 20  r deprecated or 
5260: 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e 20 20 4e  experimental.  N
5270: 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a  ew applications.
5280: 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74 20 75 73  ** should not us
5290: 65 20 64 65 70 72 65 63 61 74 65 64 20 69 6e 74  e deprecated int
52a0: 65 72 66 61 63 65 73 20 2d 20 74 68 65 79 20 61  erfaces - they a
52b0: 72 65 20 73 75 70 70 6f 72 74 20 66 6f 72 20 62  re support for b
52c0: 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70  ackwards.** comp
52d0: 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 20  atibility only. 
52e0: 20 41 70 70 6c 69 63 61 74 69 6f 6e 20 77 72 69   Application wri
52f0: 74 65 72 73 20 73 68 6f 75 6c 64 20 62 65 20 61  ters should be a
5300: 77 61 72 65 20 74 68 61 74 0a 2a 2a 20 65 78 70  ware that.** exp
5310: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
5320: 61 63 65 73 20 61 72 65 20 73 75 62 6a 65 63 74  aces are subject
5330: 20 74 6f 20 63 68 61 6e 67 65 20 69 6e 20 70 6f   to change in po
5340: 69 6e 74 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a  int releases..**
5350: 0a 2a 2a 20 54 68 65 73 65 20 6d 61 63 72 6f 73  .** These macros
5360: 20 75 73 65 64 20 74 6f 20 72 65 73 6f 6c 76 65   used to resolve
5370: 20 74 6f 20 76 61 72 69 6f 75 73 20 6b 69 6e 64   to various kind
5380: 73 20 6f 66 20 63 6f 6d 70 69 6c 65 72 20 6d 61  s of compiler ma
5390: 67 69 63 20 74 68 61 74 0a 2a 2a 20 77 6f 75 6c  gic that.** woul
53a0: 64 20 67 65 6e 65 72 61 74 65 20 77 61 72 6e 69  d generate warni
53b0: 6e 67 20 6d 65 73 73 61 67 65 73 20 77 68 65 6e  ng messages when
53c0: 20 74 68 65 79 20 77 65 72 65 20 75 73 65 64 2e   they were used.
53d0: 20 20 42 75 74 20 74 68 61 74 0a 2a 2a 20 63 6f    But that.** co
53e0: 6d 70 69 6c 65 72 20 6d 61 67 69 63 20 65 6e 64  mpiler magic end
53f0: 65 64 20 75 70 20 67 65 6e 65 72 61 74 69 6e 67  ed up generating
5400: 20 73 75 63 68 20 61 20 66 6c 75 72 72 79 20 6f   such a flurry o
5410: 66 20 62 75 67 20 72 65 70 6f 72 74 73 0a 2a 2a  f bug reports.**
5420: 20 74 68 61 74 20 77 65 20 68 61 76 65 20 74 61   that we have ta
5430: 6b 65 6e 20 69 74 20 61 6c 6c 20 6f 75 74 20 61  ken it all out a
5440: 6e 64 20 67 6f 6e 65 20 62 61 63 6b 20 74 6f 20  nd gone back to 
5450: 75 73 69 6e 67 20 73 69 6d 70 6c 65 0a 2a 2a 20  using simple.** 
5460: 6e 6f 6f 70 20 6d 61 63 72 6f 73 2e 0a 2a 2f 0a  noop macros..*/.
5470: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
5480: 45 50 52 45 43 41 54 45 44 0a 23 64 65 66 69 6e  EPRECATED.#defin
5490: 65 20 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d  e SQLITE_EXPERIM
54a0: 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a 2a 20 45 6e 73  ENTAL../*.** Ens
54b0: 75 72 65 20 74 68 65 73 65 20 73 79 6d 62 6f 6c  ure these symbol
54c0: 73 20 77 65 72 65 20 6e 6f 74 20 64 65 66 69 6e  s were not defin
54d0: 65 64 20 62 79 20 73 6f 6d 65 20 70 72 65 76 69  ed by some previ
54e0: 6f 75 73 20 68 65 61 64 65 72 20 66 69 6c 65 2e  ous header file.
54f0: 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54  .*/.#ifdef SQLIT
5500: 45 5f 56 45 52 53 49 4f 4e 0a 23 20 75 6e 64 65  E_VERSION.# unde
5510: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
5520: 0a 23 65 6e 64 69 66 0a 23 69 66 64 65 66 20 53  .#endif.#ifdef S
5530: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
5540: 4d 42 45 52 0a 23 20 75 6e 64 65 66 20 53 51 4c  MBER.# undef SQL
5550: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42  ITE_VERSION_NUMB
5560: 45 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a  ER.#endif../*.**
5570: 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69   CAPI3REF: Compi
5580: 6c 65 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20  le-Time Library 
5590: 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73 0a  Version Numbers.
55a0: 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c  **.** ^(The [SQL
55b0: 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20 43 20 70  ITE_VERSION] C p
55c0: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
55d0: 6f 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33  o in the sqlite3
55e0: 2e 68 20 68 65 61 64 65 72 0a 2a 2a 20 65 76 61  .h header.** eva
55f0: 6c 75 61 74 65 73 20 74 6f 20 61 20 73 74 72 69  luates to a stri
5600: 6e 67 20 6c 69 74 65 72 61 6c 20 74 68 61 74 20  ng literal that 
5610: 69 73 20 74 68 65 20 53 51 4c 69 74 65 20 76 65  is the SQLite ve
5620: 72 73 69 6f 6e 20 69 6e 20 74 68 65 0a 2a 2a 20  rsion in the.** 
5630: 66 6f 72 6d 61 74 20 22 58 2e 59 2e 5a 22 20 77  format "X.Y.Z" w
5640: 68 65 72 65 20 58 20 69 73 20 74 68 65 20 6d 61  here X is the ma
5650: 6a 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62  jor version numb
5660: 65 72 20 28 61 6c 77 61 79 73 20 33 20 66 6f 72  er (always 3 for
5670: 0a 2a 2a 20 53 51 4c 69 74 65 33 29 20 61 6e 64  .** SQLite3) and
5680: 20 59 20 69 73 20 74 68 65 20 6d 69 6e 6f 72 20   Y is the minor 
5690: 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 61  version number a
56a0: 6e 64 20 5a 20 69 73 20 74 68 65 20 72 65 6c 65  nd Z is the rele
56b0: 61 73 65 20 6e 75 6d 62 65 72 2e 29 5e 0a 2a 2a  ase number.)^.**
56c0: 20 5e 28 54 68 65 20 5b 53 51 4c 49 54 45 5f 56   ^(The [SQLITE_V
56d0: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 20 43  ERSION_NUMBER] C
56e0: 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61   preprocessor ma
56f0: 63 72 6f 20 72 65 73 6f 6c 76 65 73 20 74 6f 20  cro resolves to 
5700: 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 77 69  an integer.** wi
5710: 74 68 20 74 68 65 20 76 61 6c 75 65 20 28 58 2a  th the value (X*
5720: 31 30 30 30 30 30 30 20 2b 20 59 2a 31 30 30 30  1000000 + Y*1000
5730: 20 2b 20 5a 29 20 77 68 65 72 65 20 58 2c 20 59   + Z) where X, Y
5740: 2c 20 61 6e 64 20 5a 20 61 72 65 20 74 68 65 20  , and Z are the 
5750: 73 61 6d 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20  same.** numbers 
5760: 75 73 65 64 20 69 6e 20 5b 53 51 4c 49 54 45 5f  used in [SQLITE_
5770: 56 45 52 53 49 4f 4e 5d 2e 29 5e 0a 2a 2a 20 54  VERSION].)^.** T
5780: 68 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  he SQLITE_VERSIO
5790: 4e 5f 4e 55 4d 42 45 52 20 66 6f 72 20 61 6e 79  N_NUMBER for any
57a0: 20 67 69 76 65 6e 20 72 65 6c 65 61 73 65 20 6f   given release o
57b0: 66 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c  f SQLite will al
57c0: 73 6f 0a 2a 2a 20 62 65 20 6c 61 72 67 65 72 20  so.** be larger 
57d0: 74 68 61 6e 20 74 68 65 20 72 65 6c 65 61 73 65  than the release
57e0: 20 66 72 6f 6d 20 77 68 69 63 68 20 69 74 20 69   from which it i
57f0: 73 20 64 65 72 69 76 65 64 2e 20 20 45 69 74 68  s derived.  Eith
5800: 65 72 20 59 20 77 69 6c 6c 0a 2a 2a 20 62 65 20  er Y will.** be 
5810: 68 65 6c 64 20 63 6f 6e 73 74 61 6e 74 20 61 6e  held constant an
5820: 64 20 5a 20 77 69 6c 6c 20 62 65 20 69 6e 63 72  d Z will be incr
5830: 65 6d 65 6e 74 65 64 20 6f 72 20 65 6c 73 65 20  emented or else 
5840: 59 20 77 69 6c 6c 20 62 65 20 69 6e 63 72 65 6d  Y will be increm
5850: 65 6e 74 65 64 0a 2a 2a 20 61 6e 64 20 5a 20 77  ented.** and Z w
5860: 69 6c 6c 20 62 65 20 72 65 73 65 74 20 74 6f 20  ill be reset to 
5870: 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 69 6e 63  zero..**.** Sinc
5880: 65 20 76 65 72 73 69 6f 6e 20 33 2e 36 2e 31 38  e version 3.6.18
5890: 2c 20 53 51 4c 69 74 65 20 73 6f 75 72 63 65 20  , SQLite source 
58a0: 63 6f 64 65 20 68 61 73 20 62 65 65 6e 20 73 74  code has been st
58b0: 6f 72 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20 3c  ored in the.** <
58c0: 61 20 68 72 65 66 3d 22 68 74 74 70 3a 2f 2f 77  a href="http://w
58d0: 77 77 2e 66 6f 73 73 69 6c 2d 73 63 6d 2e 6f 72  ww.fossil-scm.or
58e0: 67 2f 22 3e 46 6f 73 73 69 6c 20 63 6f 6e 66 69  g/">Fossil confi
58f0: 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d  guration managem
5900: 65 6e 74 0a 2a 2a 20 73 79 73 74 65 6d 3c 2f 61  ent.** system</a
5910: 3e 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f  >.  ^The SQLITE_
5920: 53 4f 55 52 43 45 5f 49 44 20 6d 61 63 72 6f 20  SOURCE_ID macro 
5930: 65 76 61 6c 75 61 74 65 73 20 74 6f 0a 2a 2a 20  evaluates to.** 
5940: 61 20 73 74 72 69 6e 67 20 77 68 69 63 68 20 69  a string which i
5950: 64 65 6e 74 69 66 69 65 73 20 61 20 70 61 72 74  dentifies a part
5960: 69 63 75 6c 61 72 20 63 68 65 63 6b 2d 69 6e 20  icular check-in 
5970: 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 74  of SQLite.** wit
5980: 68 69 6e 20 69 74 73 20 63 6f 6e 66 69 67 75 72  hin its configur
5990: 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74  ation management
59a0: 20 73 79 73 74 65 6d 2e 20 20 5e 54 68 65 20 53   system.  ^The S
59b0: 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 0a  QLITE_SOURCE_ID.
59c0: 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69  ** string contai
59d0: 6e 73 20 74 68 65 20 64 61 74 65 20 61 6e 64 20  ns the date and 
59e0: 74 69 6d 65 20 6f 66 20 74 68 65 20 63 68 65 63  time of the chec
59f0: 6b 2d 69 6e 20 28 55 54 43 29 20 61 6e 64 20 61  k-in (UTC) and a
5a00: 6e 20 53 48 41 31 0a 2a 2a 20 68 61 73 68 20 6f  n SHA1.** hash o
5a10: 66 20 74 68 65 20 65 6e 74 69 72 65 20 73 6f 75  f the entire sou
5a20: 72 63 65 20 74 72 65 65 2e 0a 2a 2a 0a 2a 2a 20  rce tree..**.** 
5a30: 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
5a40: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 5d  e3_libversion()]
5a50: 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 69  ,.** [sqlite3_li
5a60: 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28  bversion_number(
5a70: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6f 75  )], [sqlite3_sou
5a80: 72 63 65 69 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71  rceid()],.** [sq
5a90: 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28 29 5d 20  lite_version()] 
5aa0: 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73 6f 75 72  and [sqlite_sour
5ab0: 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a 23 64 65  ce_id()]..*/.#de
5ac0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 45 52 53  fine SQLITE_VERS
5ad0: 49 4f 4e 20 20 20 20 20 20 20 20 22 33 2e 38 2e  ION        "3.8.
5ae0: 31 22 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  1".#define SQLIT
5af0: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
5b00: 20 33 30 30 38 30 30 31 0a 23 64 65 66 69 6e 65   3008001.#define
5b10: 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49   SQLITE_SOURCE_I
5b20: 44 20 20 20 20 20 20 22 32 30 31 33 2d 30 38 2d  D      "2013-08-
5b30: 32 39 20 30 31 3a 30 39 3a 31 34 20 39 32 32 39  29 01:09:14 9229
5b40: 61 65 62 33 36 31 66 39 38 30 35 38 39 34 33 32  aeb361f980589432
5b50: 31 33 32 37 64 30 35 61 62 61 38 35 35 62 38 37  1327d05aba855b87
5b60: 39 39 66 33 22 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  99f3"../*.** CAP
5b70: 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20  I3REF: Run-Time 
5b80: 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f 6e 20  Library Version 
5b90: 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b 45 59 57 4f  Numbers.** KEYWO
5ba0: 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76 65 72  RDS: sqlite3_ver
5bb0: 73 69 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 73 6f  sion, sqlite3_so
5bc0: 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a 20 54 68 65  urceid.**.** The
5bd0: 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 70 72  se interfaces pr
5be0: 6f 76 69 64 65 20 74 68 65 20 73 61 6d 65 20 69  ovide the same i
5bf0: 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20 74 68  nformation as th
5c00: 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  e [SQLITE_VERSIO
5c10: 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56  N],.** [SQLITE_V
5c20: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2c 20  ERSION_NUMBER], 
5c30: 61 6e 64 20 5b 53 51 4c 49 54 45 5f 53 4f 55 52  and [SQLITE_SOUR
5c40: 43 45 5f 49 44 5d 20 43 20 70 72 65 70 72 6f 63  CE_ID] C preproc
5c50: 65 73 73 6f 72 20 6d 61 63 72 6f 73 0a 2a 2a 20  essor macros.** 
5c60: 62 75 74 20 61 72 65 20 61 73 73 6f 63 69 61 74  but are associat
5c70: 65 64 20 77 69 74 68 20 74 68 65 20 6c 69 62 72  ed with the libr
5c80: 61 72 79 20 69 6e 73 74 65 61 64 20 6f 66 20 74  ary instead of t
5c90: 68 65 20 68 65 61 64 65 72 20 66 69 6c 65 2e 20  he header file. 
5ca0: 20 5e 28 43 61 75 74 69 6f 75 73 0a 2a 2a 20 70   ^(Cautious.** p
5cb0: 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68 74  rogrammers might
5cc0: 20 69 6e 63 6c 75 64 65 20 61 73 73 65 72 74 28   include assert(
5cd0: 29 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20  ) statements in 
5ce0: 74 68 65 69 72 20 61 70 70 6c 69 63 61 74 69 6f  their applicatio
5cf0: 6e 20 74 6f 0a 2a 2a 20 76 65 72 69 66 79 20 74  n to.** verify t
5d00: 68 61 74 20 76 61 6c 75 65 73 20 72 65 74 75 72  hat values retur
5d10: 6e 65 64 20 62 79 20 74 68 65 73 65 20 69 6e 74  ned by these int
5d20: 65 72 66 61 63 65 73 20 6d 61 74 63 68 20 74 68  erfaces match th
5d30: 65 20 6d 61 63 72 6f 73 20 69 6e 0a 2a 2a 20 74  e macros in.** t
5d40: 68 65 20 68 65 61 64 65 72 2c 20 61 6e 64 20 74  he header, and t
5d50: 68 75 73 20 69 6e 73 75 72 65 20 74 68 61 74 20  hus insure that 
5d60: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
5d70: 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77  is.** compiled w
5d80: 69 74 68 20 6d 61 74 63 68 69 6e 67 20 6c 69 62  ith matching lib
5d90: 72 61 72 79 20 61 6e 64 20 68 65 61 64 65 72 20  rary and header 
5da0: 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62 6c  files..**.** <bl
5db0: 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
5dc0: 2a 20 61 73 73 65 72 74 28 20 73 71 6c 69 74 65  * assert( sqlite
5dd0: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d  3_libversion_num
5de0: 62 65 72 28 29 3d 3d 53 51 4c 49 54 45 5f 56 45  ber()==SQLITE_VE
5df0: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 29 3b 0a  RSION_NUMBER );.
5e00: 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72 63 6d  ** assert( strcm
5e10: 70 28 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 65  p(sqlite3_source
5e20: 69 64 28 29 2c 53 51 4c 49 54 45 5f 53 4f 55 52  id(),SQLITE_SOUR
5e30: 43 45 5f 49 44 29 3d 3d 30 20 29 3b 0a 2a 2a 20  CE_ID)==0 );.** 
5e40: 61 73 73 65 72 74 28 20 73 74 72 63 6d 70 28 73  assert( strcmp(s
5e50: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
5e60: 6e 28 29 2c 53 51 4c 49 54 45 5f 56 45 52 53 49  n(),SQLITE_VERSI
5e70: 4f 4e 29 3d 3d 30 20 29 3b 0a 2a 2a 20 3c 2f 70  ON)==0 );.** </p
5e80: 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
5e90: 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  )^.**.** ^The sq
5ea0: 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20  lite3_version[] 
5eb0: 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 20  string constant 
5ec0: 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 74 65 78  contains the tex
5ed0: 74 20 6f 66 20 5b 53 51 4c 49 54 45 5f 56 45 52  t of [SQLITE_VER
5ee0: 53 49 4f 4e 5d 0a 2a 2a 20 6d 61 63 72 6f 2e 20  SION].** macro. 
5ef0: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 69   ^The sqlite3_li
5f00: 62 76 65 72 73 69 6f 6e 28 29 20 66 75 6e 63 74  bversion() funct
5f10: 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ion returns a po
5f20: 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20  inter to the.** 
5f30: 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  to the sqlite3_v
5f40: 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e 67 20  ersion[] string 
5f50: 63 6f 6e 73 74 61 6e 74 2e 20 20 54 68 65 20 73  constant.  The s
5f60: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
5f70: 6e 28 29 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  n().** function 
5f80: 69 73 20 70 72 6f 76 69 64 65 64 20 66 6f 72 20  is provided for 
5f90: 75 73 65 20 69 6e 20 44 4c 4c 73 20 73 69 6e 63  use in DLLs sinc
5fa0: 65 20 44 4c 4c 20 75 73 65 72 73 20 75 73 75 61  e DLL users usua
5fb0: 6c 6c 79 20 64 6f 20 6e 6f 74 20 68 61 76 65 0a  lly do not have.
5fc0: 2a 2a 20 64 69 72 65 63 74 20 61 63 63 65 73 73  ** direct access
5fd0: 20 74 6f 20 73 74 72 69 6e 67 20 63 6f 6e 73 74   to string const
5fe0: 61 6e 74 73 20 77 69 74 68 69 6e 20 74 68 65 20  ants within the 
5ff0: 44 4c 4c 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71  DLL.  ^The.** sq
6000: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
6010: 5f 6e 75 6d 62 65 72 28 29 20 66 75 6e 63 74 69  _number() functi
6020: 6f 6e 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e  on returns an in
6030: 74 65 67 65 72 20 65 71 75 61 6c 20 74 6f 0a 2a  teger equal to.*
6040: 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  * [SQLITE_VERSIO
6050: 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20 5e 54 68 65  N_NUMBER].  ^The
6060: 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69   sqlite3_sourcei
6070: 64 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  d() function ret
6080: 75 72 6e 73 20 0a 2a 2a 20 61 20 70 6f 69 6e 74  urns .** a point
6090: 65 72 20 74 6f 20 61 20 73 74 72 69 6e 67 20 63  er to a string c
60a0: 6f 6e 73 74 61 6e 74 20 77 68 6f 73 65 20 76 61  onstant whose va
60b0: 6c 75 65 20 69 73 20 74 68 65 20 73 61 6d 65 20  lue is the same 
60c0: 61 73 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49  as the .** [SQLI
60d0: 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20 43 20  TE_SOURCE_ID] C 
60e0: 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63  preprocessor mac
60f0: 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ro..**.** See al
6100: 73 6f 3a 20 5b 73 71 6c 69 74 65 5f 76 65 72 73  so: [sqlite_vers
6110: 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ion()] and [sqli
6120: 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29 5d 2e  te_source_id()].
6130: 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  .*/.SQLITE_API c
6140: 6f 6e 73 74 20 63 68 61 72 20 73 71 6c 69 74 65  onst char sqlite
6150: 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 3d 20 53 51  3_version[] = SQ
6160: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 3b 0a 53 51  LITE_VERSION;.SQ
6170: 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63  LITE_API const c
6180: 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6c 69 62  har *sqlite3_lib
6190: 76 65 72 73 69 6f 6e 28 76 6f 69 64 29 3b 0a 53  version(void);.S
61a0: 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
61b0: 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f  char *sqlite3_so
61c0: 75 72 63 65 69 64 28 76 6f 69 64 29 3b 0a 53 51  urceid(void);.SQ
61d0: 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
61e0: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f  ite3_libversion_
61f0: 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b 0a 0a 2f  number(void);../
6200: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
6210: 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20  un-Time Library 
6220: 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f 70 74 69  Compilation Opti
6230: 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69 63 73 0a  ons Diagnostics.
6240: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
6250: 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e  e3_compileoption
6260: 5f 75 73 65 64 28 29 20 66 75 6e 63 74 69 6f 6e  _used() function
6270: 20 72 65 74 75 72 6e 73 20 30 20 6f 72 20 31 20   returns 0 or 1 
6280: 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67 20 77  .** indicating w
6290: 68 65 74 68 65 72 20 74 68 65 20 73 70 65 63 69  hether the speci
62a0: 66 69 65 64 20 6f 70 74 69 6f 6e 20 77 61 73 20  fied option was 
62b0: 64 65 66 69 6e 65 64 20 61 74 20 0a 2a 2a 20 63  defined at .** c
62c0: 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 20 5e 54  ompile time.  ^T
62d0: 68 65 20 53 51 4c 49 54 45 5f 20 70 72 65 66 69  he SQLITE_ prefi
62e0: 78 20 6d 61 79 20 62 65 20 6f 6d 69 74 74 65 64  x may be omitted
62f0: 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a 20 6f 70   from the .** op
6300: 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73 73 65 64  tion name passed
6310: 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70   to sqlite3_comp
6320: 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29  ileoption_used()
6330: 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  .  .**.** ^The s
6340: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
6350: 74 69 6f 6e 5f 67 65 74 28 29 20 66 75 6e 63 74  tion_get() funct
6360: 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 74 65 72 61  ion allows itera
6370: 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20 74 68 65  ting.** over the
6380: 20 6c 69 73 74 20 6f 66 20 6f 70 74 69 6f 6e 73   list of options
6390: 20 74 68 61 74 20 77 65 72 65 20 64 65 66 69 6e   that were defin
63a0: 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69  ed at compile ti
63b0: 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75 72 6e 69  me by.** returni
63c0: 6e 67 20 74 68 65 20 4e 2d 74 68 20 63 6f 6d 70  ng the N-th comp
63d0: 69 6c 65 20 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile time option 
63e0: 73 74 72 69 6e 67 2e 20 20 5e 49 66 20 4e 20 69  string.  ^If N i
63f0: 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 0a  s out of range,.
6400: 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69  ** sqlite3_compi
6410: 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 72  leoption_get() r
6420: 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f  eturns a NULL po
6430: 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 53 51 4c  inter.  ^The SQL
6440: 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66 69 78 20  ITE_ .** prefix 
6450: 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20  is omitted from 
6460: 61 6e 79 20 73 74 72 69 6e 67 73 20 72 65 74 75  any strings retu
6470: 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69  rned by .** sqli
6480: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
6490: 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  n_get()..**.** ^
64a0: 53 75 70 70 6f 72 74 20 66 6f 72 20 74 68 65 20  Support for the 
64b0: 64 69 61 67 6e 6f 73 74 69 63 20 66 75 6e 63 74  diagnostic funct
64c0: 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f 63 6f 6d  ions sqlite3_com
64d0: 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28  pileoption_used(
64e0: 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33  ).** and sqlite3
64f0: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67  _compileoption_g
6500: 65 74 28 29 20 6d 61 79 20 62 65 20 6f 6d 69 74  et() may be omit
6510: 74 65 64 20 62 79 20 73 70 65 63 69 66 79 69 6e  ted by specifyin
6520: 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54  g the .** [SQLIT
6530: 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45 4f 50  E_OMIT_COMPILEOP
6540: 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f 70 74 69  TION_DIAGS] opti
6550: 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69  on at compile ti
6560: 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  me..**.** See al
6570: 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  so: SQL function
6580: 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70 69 6c  s [sqlite_compil
6590: 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 5d 20  eoption_used()] 
65a0: 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 63  and.** [sqlite_c
65b0: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74  ompileoption_get
65c0: 28 29 5d 20 61 6e 64 20 74 68 65 20 5b 63 6f 6d  ()] and the [com
65d0: 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20 70 72 61  pile_options pra
65e0: 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66  gma]..*/.#ifndef
65f0: 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d   SQLITE_OMIT_COM
6600: 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53  PILEOPTION_DIAGS
6610: 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
6620: 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f  sqlite3_compileo
6630: 70 74 69 6f 6e 5f 75 73 65 64 28 63 6f 6e 73 74  ption_used(const
6640: 20 63 68 61 72 20 2a 7a 4f 70 74 4e 61 6d 65 29   char *zOptName)
6650: 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  ;.SQLITE_API con
6660: 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
6670: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67  _compileoption_g
6680: 65 74 28 69 6e 74 20 4e 29 3b 0a 23 65 6e 64 69  et(int N);.#endi
6690: 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  f../*.** CAPI3RE
66a0: 46 3a 20 54 65 73 74 20 54 6f 20 53 65 65 20 49  F: Test To See I
66b0: 66 20 54 68 65 20 4c 69 62 72 61 72 79 20 49 73  f The Library Is
66c0: 20 54 68 72 65 61 64 73 61 66 65 0a 2a 2a 0a 2a   Threadsafe.**.*
66d0: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74  * ^The sqlite3_t
66e0: 68 72 65 61 64 73 61 66 65 28 29 20 66 75 6e 63  hreadsafe() func
66f0: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 7a 65 72  tion returns zer
6700: 6f 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66  o if and only if
6710: 0a 2a 2a 20 53 51 4c 69 74 65 20 77 61 73 20 63  .** SQLite was c
6720: 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6d 75 74  ompiled with mut
6730: 65 78 69 6e 67 20 63 6f 64 65 20 6f 6d 69 74 74  exing code omitt
6740: 65 64 20 64 75 65 20 74 6f 20 74 68 65 0a 2a 2a  ed due to the.**
6750: 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
6760: 41 46 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  AFE] compile-tim
6770: 65 20 6f 70 74 69 6f 6e 20 62 65 69 6e 67 20 73  e option being s
6780: 65 74 20 74 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53  et to 0..**.** S
6790: 51 4c 69 74 65 20 63 61 6e 20 62 65 20 63 6f 6d  QLite can be com
67a0: 70 69 6c 65 64 20 77 69 74 68 20 6f 72 20 77 69  piled with or wi
67b0: 74 68 6f 75 74 20 6d 75 74 65 78 65 73 2e 20 20  thout mutexes.  
67c0: 57 68 65 6e 0a 2a 2a 20 74 68 65 20 5b 53 51 4c  When.** the [SQL
67d0: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20  ITE_THREADSAFE] 
67e0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
67f0: 61 63 72 6f 20 69 73 20 31 20 6f 72 20 32 2c 20  acro is 1 or 2, 
6800: 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65  mutexes.** are e
6810: 6e 61 62 6c 65 64 20 61 6e 64 20 53 51 4c 69 74  nabled and SQLit
6820: 65 20 69 73 20 74 68 72 65 61 64 73 61 66 65 2e  e is threadsafe.
6830: 20 20 57 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 53    When the.** [S
6840: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
6850: 5d 20 6d 61 63 72 6f 20 69 73 20 30 2c 20 0a 2a  ] macro is 0, .*
6860: 2a 20 74 68 65 20 6d 75 74 65 78 65 73 20 61 72  * the mutexes ar
6870: 65 20 6f 6d 69 74 74 65 64 2e 20 20 57 69 74 68  e omitted.  With
6880: 6f 75 74 20 74 68 65 20 6d 75 74 65 78 65 73 2c  out the mutexes,
6890: 20 69 74 20 69 73 20 6e 6f 74 20 73 61 66 65 0a   it is not safe.
68a0: 2a 2a 20 74 6f 20 75 73 65 20 53 51 4c 69 74 65  ** to use SQLite
68b0: 20 63 6f 6e 63 75 72 72 65 6e 74 6c 79 20 66 72   concurrently fr
68c0: 6f 6d 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65  om more than one
68d0: 20 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45   thread..**.** E
68e0: 6e 61 62 6c 69 6e 67 20 6d 75 74 65 78 65 73 20  nabling mutexes 
68f0: 69 6e 63 75 72 73 20 61 20 6d 65 61 73 75 72 61  incurs a measura
6900: 62 6c 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20  ble performance 
6910: 70 65 6e 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69  penalty..** So i
6920: 66 20 73 70 65 65 64 20 69 73 20 6f 66 20 75 74  f speed is of ut
6930: 6d 6f 73 74 20 69 6d 70 6f 72 74 61 6e 63 65 2c  most importance,
6940: 20 69 74 20 6d 61 6b 65 73 20 73 65 6e 73 65 20   it makes sense 
6950: 74 6f 20 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68  to disable.** th
6960: 65 20 6d 75 74 65 78 65 73 2e 20 20 42 75 74 20  e mutexes.  But 
6970: 66 6f 72 20 6d 61 78 69 6d 75 6d 20 73 61 66 65  for maximum safe
6980: 74 79 2c 20 6d 75 74 65 78 65 73 20 73 68 6f 75  ty, mutexes shou
6990: 6c 64 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a  ld be enabled..*
69a0: 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 62  * ^The default b
69b0: 65 68 61 76 69 6f 72 20 69 73 20 66 6f 72 20 6d  ehavior is for m
69c0: 75 74 65 78 65 73 20 74 6f 20 62 65 20 65 6e 61  utexes to be ena
69d0: 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  bled..**.** This
69e0: 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62   interface can b
69f0: 65 20 75 73 65 64 20 62 79 20 61 6e 20 61 70 70  e used by an app
6a00: 6c 69 63 61 74 69 6f 6e 20 74 6f 20 6d 61 6b 65  lication to make
6a10: 20 73 75 72 65 20 74 68 61 74 20 74 68 65 0a 2a   sure that the.*
6a20: 2a 20 76 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c  * version of SQL
6a30: 69 74 65 20 74 68 61 74 20 69 74 20 69 73 20 6c  ite that it is l
6a40: 69 6e 6b 69 6e 67 20 61 67 61 69 6e 73 74 20 77  inking against w
6a50: 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  as compiled with
6a60: 0a 2a 2a 20 74 68 65 20 64 65 73 69 72 65 64 20  .** the desired 
6a70: 73 65 74 74 69 6e 67 20 6f 66 20 74 68 65 20 5b  setting of the [
6a80: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
6a90: 45 5d 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20  E] macro..**.** 
6aa0: 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 6f  This interface o
6ab0: 6e 6c 79 20 72 65 70 6f 72 74 73 20 6f 6e 20 74  nly reports on t
6ac0: 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  he compile-time 
6ad0: 6d 75 74 65 78 20 73 65 74 74 69 6e 67 0a 2a 2a  mutex setting.**
6ae0: 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   of the [SQLITE_
6af0: 54 48 52 45 41 44 53 41 46 45 5d 20 66 6c 61 67  THREADSAFE] flag
6b00: 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69 73 20  .  If SQLite is 
6b10: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
6b20: 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41   SQLITE_THREADSA
6b30: 46 45 3d 31 20 6f 72 20 3d 32 20 74 68 65 6e 20  FE=1 or =2 then 
6b40: 6d 75 74 65 78 65 73 20 61 72 65 20 65 6e 61 62  mutexes are enab
6b50: 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 62  led by default b
6b60: 75 74 0a 2a 2a 20 63 61 6e 20 62 65 20 66 75 6c  ut.** can be ful
6b70: 6c 79 20 6f 72 20 70 61 72 74 69 61 6c 6c 79 20  ly or partially 
6b80: 64 69 73 61 62 6c 65 64 20 75 73 69 6e 67 20 61  disabled using a
6b90: 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
6ba0: 33 5f 63 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20 77  3_config()].** w
6bb0: 69 74 68 20 74 68 65 20 76 65 72 62 73 20 5b 53  ith the verbs [S
6bc0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
6bd0: 47 4c 45 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c  GLETHREAD], [SQL
6be0: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49  ITE_CONFIG_MULTI
6bf0: 54 48 52 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b  THREAD],.** or [
6c00: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
6c10: 54 45 58 5d 2e 20 20 5e 28 54 68 65 20 72 65 74  TEX].  ^(The ret
6c20: 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 65  urn value of the
6c30: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 74 68 72 65  .** sqlite3_thre
6c40: 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f  adsafe() functio
6c50: 6e 20 73 68 6f 77 73 20 6f 6e 6c 79 20 74 68 65  n shows only the
6c60: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 73 65   compile-time se
6c70: 74 74 69 6e 67 20 6f 66 0a 2a 2a 20 74 68 72 65  tting of.** thre
6c80: 61 64 20 73 61 66 65 74 79 2c 20 6e 6f 74 20 61  ad safety, not a
6c90: 6e 79 20 72 75 6e 2d 74 69 6d 65 20 63 68 61 6e  ny run-time chan
6ca0: 67 65 73 20 74 6f 20 74 68 61 74 20 73 65 74 74  ges to that sett
6cb0: 69 6e 67 20 6d 61 64 65 20 62 79 0a 2a 2a 20 73  ing made by.** s
6cc0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e  qlite3_config().
6cd0: 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
6ce0: 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
6cf0: 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 74  e from sqlite3_t
6d00: 68 72 65 61 64 73 61 66 65 28 29 0a 2a 2a 20 69  hreadsafe().** i
6d10: 73 20 75 6e 63 68 61 6e 67 65 64 20 62 79 20 63  s unchanged by c
6d20: 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
6d30: 63 6f 6e 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a 2a  config().)^.**.*
6d40: 2a 20 53 65 65 20 74 68 65 20 5b 74 68 72 65 61  * See the [threa
6d50: 64 69 6e 67 20 6d 6f 64 65 5d 20 64 6f 63 75 6d  ding mode] docum
6d60: 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 64  entation for add
6d70: 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74  itional informat
6d80: 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ion..*/.SQLITE_A
6d90: 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 74  PI int sqlite3_t
6da0: 68 72 65 61 64 73 61 66 65 28 76 6f 69 64 29 3b  hreadsafe(void);
6db0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
6dc0: 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65  : Database Conne
6dd0: 63 74 69 6f 6e 20 48 61 6e 64 6c 65 0a 2a 2a 20  ction Handle.** 
6de0: 4b 45 59 57 4f 52 44 53 3a 20 7b 64 61 74 61 62  KEYWORDS: {datab
6df0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 7d 20  ase connection} 
6e00: 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  {database connec
6e10: 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45 61 63  tions}.**.** Eac
6e20: 68 20 6f 70 65 6e 20 53 51 4c 69 74 65 20 64 61  h open SQLite da
6e30: 74 61 62 61 73 65 20 69 73 20 72 65 70 72 65 73  tabase is repres
6e40: 65 6e 74 65 64 20 62 79 20 61 20 70 6f 69 6e 74  ented by a point
6e50: 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63  er to an instanc
6e60: 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6f 70 61 71  e of.** the opaq
6e70: 75 65 20 73 74 72 75 63 74 75 72 65 20 6e 61 6d  ue structure nam
6e80: 65 64 20 22 73 71 6c 69 74 65 33 22 2e 20 20 49  ed "sqlite3".  I
6e90: 74 20 69 73 20 75 73 65 66 75 6c 20 74 6f 20 74  t is useful to t
6ea0: 68 69 6e 6b 20 6f 66 20 61 6e 20 73 71 6c 69 74  hink of an sqlit
6eb0: 65 33 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 61 73  e3.** pointer as
6ec0: 20 61 6e 20 6f 62 6a 65 63 74 2e 20 20 54 68 65   an object.  The
6ed0: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
6ee0: 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ], [sqlite3_open
6ef0: 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73  16()], and.** [s
6f00: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
6f10: 5d 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  ] interfaces are
6f20: 20 69 74 73 20 63 6f 6e 73 74 72 75 63 74 6f 72   its constructor
6f30: 73 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  s, and [sqlite3_
6f40: 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20 61 6e 64 20  close()].** and 
6f50: 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76  [sqlite3_close_v
6f60: 32 28 29 5d 20 61 72 65 20 69 74 73 20 64 65 73  2()] are its des
6f70: 74 72 75 63 74 6f 72 73 2e 20 20 54 68 65 72 65  tructors.  There
6f80: 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65 72 0a   are many other.
6f90: 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 28 73  ** interfaces (s
6fa0: 75 63 68 20 61 73 0a 2a 2a 20 5b 73 71 6c 69 74  uch as.** [sqlit
6fb0: 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
6fc0: 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  , [sqlite3_creat
6fd0: 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 61  e_function()], a
6fe0: 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  nd.** [sqlite3_b
6ff0: 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 74  usy_timeout()] t
7000: 6f 20 6e 61 6d 65 20 62 75 74 20 74 68 72 65 65  o name but three
7010: 29 20 74 68 61 74 20 61 72 65 20 6d 65 74 68 6f  ) that are metho
7020: 64 73 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69  ds on an.** sqli
7030: 74 65 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 74  te3 object..*/.t
7040: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
7050: 6c 69 74 65 33 20 73 71 6c 69 74 65 33 3b 0a 0a  lite3 sqlite3;..
7060: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
7070: 36 34 2d 42 69 74 20 49 6e 74 65 67 65 72 20 54  64-Bit Integer T
7080: 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ypes.** KEYWORDS
7090: 3a 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 73  : sqlite_int64 s
70a0: 71 6c 69 74 65 5f 75 69 6e 74 36 34 0a 2a 2a 0a  qlite_uint64.**.
70b0: 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65 72 65  ** Because there
70c0: 20 69 73 20 6e 6f 20 63 72 6f 73 73 2d 70 6c 61   is no cross-pla
70d0: 74 66 6f 72 6d 20 77 61 79 20 74 6f 20 73 70 65  tform way to spe
70e0: 63 69 66 79 20 36 34 2d 62 69 74 20 69 6e 74 65  cify 64-bit inte
70f0: 67 65 72 20 74 79 70 65 73 0a 2a 2a 20 53 51 4c  ger types.** SQL
7100: 69 74 65 20 69 6e 63 6c 75 64 65 73 20 74 79 70  ite includes typ
7110: 65 64 65 66 73 20 66 6f 72 20 36 34 2d 62 69 74  edefs for 64-bit
7120: 20 73 69 67 6e 65 64 20 61 6e 64 20 75 6e 73 69   signed and unsi
7130: 67 6e 65 64 20 69 6e 74 65 67 65 72 73 2e 0a 2a  gned integers..*
7140: 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
7150: 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74  _int64 and sqlit
7160: 65 33 5f 75 69 6e 74 36 34 20 61 72 65 20 74 68  e3_uint64 are th
7170: 65 20 70 72 65 66 65 72 72 65 64 20 74 79 70 65  e preferred type
7180: 20 64 65 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a 2a   definitions..**
7190: 20 54 68 65 20 73 71 6c 69 74 65 5f 69 6e 74 36   The sqlite_int6
71a0: 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e  4 and sqlite_uin
71b0: 74 36 34 20 74 79 70 65 73 20 61 72 65 20 73 75  t64 types are su
71c0: 70 70 6f 72 74 65 64 20 66 6f 72 20 62 61 63 6b  pported for back
71d0: 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69  wards.** compati
71e0: 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a  bility only..**.
71f0: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
7200: 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65  int64 and sqlite
7210: 5f 69 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e  _int64 types can
7220: 20 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76   store integer v
7230: 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e  alues.** between
7240: 20 2d 39 32 32 33 33 37 32 30 33 36 38 35 34 37   -92233720368547
7250: 37 35 38 30 38 20 61 6e 64 20 2b 39 32 32 33 33  75808 and +92233
7260: 37 32 30 33 36 38 35 34 37 37 35 38 30 37 20 69  72036854775807 i
7270: 6e 63 6c 75 73 69 76 65 2e 20 20 5e 54 68 65 0a  nclusive.  ^The.
7280: 2a 2a 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  ** sqlite3_uint6
7290: 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e  4 and sqlite_uin
72a0: 74 36 34 20 74 79 70 65 73 20 63 61 6e 20 73 74  t64 types can st
72b0: 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75  ore integer valu
72c0: 65 73 20 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30  es .** between 0
72d0: 20 61 6e 64 20 2b 31 38 34 34 36 37 34 34 30 37   and +1844674407
72e0: 33 37 30 39 35 35 31 36 31 35 20 69 6e 63 6c 75  3709551615 inclu
72f0: 73 69 76 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20  sive..*/.#ifdef 
7300: 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50  SQLITE_INT64_TYP
7310: 45 0a 20 20 74 79 70 65 64 65 66 20 53 51 4c 49  E.  typedef SQLI
7320: 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71  TE_INT64_TYPE sq
7330: 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79  lite_int64;.  ty
7340: 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 53  pedef unsigned S
7350: 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45  QLITE_INT64_TYPE
7360: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a   sqlite_uint64;.
7370: 23 65 6c 69 66 20 64 65 66 69 6e 65 64 28 5f 4d  #elif defined(_M
7380: 53 43 5f 56 45 52 29 20 7c 7c 20 64 65 66 69 6e  SC_VER) || defin
7390: 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29  ed(__BORLANDC__)
73a0: 0a 20 20 74 79 70 65 64 65 66 20 5f 5f 69 6e 74  .  typedef __int
73b0: 36 34 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b  64 sqlite_int64;
73c0: 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67  .  typedef unsig
73d0: 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69  ned __int64 sqli
73e0: 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 73 65  te_uint64;.#else
73f0: 0a 20 20 74 79 70 65 64 65 66 20 6c 6f 6e 67 20  .  typedef long 
7400: 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f  long int sqlite_
7410: 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66  int64;.  typedef
7420: 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67 20 6c   unsigned long l
7430: 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 75  ong int sqlite_u
7440: 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a 74 79  int64;.#endif.ty
7450: 70 65 64 65 66 20 73 71 6c 69 74 65 5f 69 6e 74  pedef sqlite_int
7460: 36 34 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  64 sqlite3_int64
7470: 3b 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74 65  ;.typedef sqlite
7480: 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  _uint64 sqlite3_
7490: 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49  uint64;../*.** I
74a0: 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f 72 20  f compiling for 
74b0: 61 20 70 72 6f 63 65 73 73 6f 72 20 74 68 61 74  a processor that
74c0: 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e 67 20   lacks floating 
74d0: 70 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c 0a 2a  point support,.*
74e0: 2a 20 73 75 62 73 74 69 74 75 74 65 20 69 6e 74  * substitute int
74f0: 65 67 65 72 20 66 6f 72 20 66 6c 6f 61 74 69 6e  eger for floatin
7500: 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69 66 64  g-point..*/.#ifd
7510: 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46  ef SQLITE_OMIT_F
7520: 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 20  LOATING_POINT.# 
7530: 64 65 66 69 6e 65 20 64 6f 75 62 6c 65 20 73 71  define double sq
7540: 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23 65 6e 64  lite3_int64.#end
7550: 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  if../*.** CAPI3R
7560: 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20 44 61  EF: Closing A Da
7570: 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f  tabase Connectio
7580: 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  n.**.** ^The sql
7590: 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 61 6e 64  ite3_close() and
75a0: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76   sqlite3_close_v
75b0: 32 28 29 20 72 6f 75 74 69 6e 65 73 20 61 72 65  2() routines are
75c0: 20 64 65 73 74 72 75 63 74 6f 72 73 0a 2a 2a 20   destructors.** 
75d0: 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33  for the [sqlite3
75e0: 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 43 61  ] object..** ^Ca
75f0: 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  lls to sqlite3_c
7600: 6c 6f 73 65 28 29 20 61 6e 64 20 73 71 6c 69 74  lose() and sqlit
7610: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 72 65  e3_close_v2() re
7620: 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69  turn SQLITE_OK i
7630: 66 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65  f.** the [sqlite
7640: 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 73 75 63  3] object is suc
7650: 63 65 73 73 66 75 6c 6c 79 20 64 65 73 74 72 6f  cessfully destro
7660: 79 65 64 20 61 6e 64 20 61 6c 6c 20 61 73 73 6f  yed and all asso
7670: 63 69 61 74 65 64 0a 2a 2a 20 72 65 73 6f 75 72  ciated.** resour
7680: 63 65 73 20 61 72 65 20 64 65 61 6c 6c 6f 63 61  ces are dealloca
7690: 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ted..**.** ^If t
76a0: 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
76b0: 65 63 74 69 6f 6e 20 69 73 20 61 73 73 6f 63 69  ection is associ
76c0: 61 74 65 64 20 77 69 74 68 20 75 6e 66 69 6e 61  ated with unfina
76d0: 6c 69 7a 65 64 20 70 72 65 70 61 72 65 64 0a 2a  lized prepared.*
76e0: 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 72 20  * statements or 
76f0: 75 6e 66 69 6e 69 73 68 65 64 20 73 71 6c 69 74  unfinished sqlit
7700: 65 33 5f 62 61 63 6b 75 70 20 6f 62 6a 65 63 74  e3_backup object
7710: 73 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  s then sqlite3_c
7720: 6c 6f 73 65 28 29 0a 2a 2a 20 77 69 6c 6c 20 6c  lose().** will l
7730: 65 61 76 65 20 74 68 65 20 64 61 74 61 62 61 73  eave the databas
7740: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65  e connection ope
7750: 6e 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51  n and return [SQ
7760: 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 20 5e  LITE_BUSY]..** ^
7770: 49 66 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  If sqlite3_close
7780: 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65 64 20  _v2() is called 
7790: 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a 65 64  with unfinalized
77a0: 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
77b0: 65 6e 74 73 0a 2a 2a 20 61 6e 64 20 75 6e 66 69  ents.** and unfi
77c0: 6e 69 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62  nished sqlite3_b
77d0: 61 63 6b 75 70 73 2c 20 74 68 65 6e 20 74 68 65  ackups, then the
77e0: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
77f0: 74 69 6f 6e 20 62 65 63 6f 6d 65 73 0a 2a 2a 20  tion becomes.** 
7800: 61 6e 20 75 6e 75 73 61 62 6c 65 20 22 7a 6f 6d  an unusable "zom
7810: 62 69 65 22 20 77 68 69 63 68 20 77 69 6c 6c 20  bie" which will 
7820: 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 65  automatically be
7830: 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 77 68 65   deallocated whe
7840: 6e 20 74 68 65 0a 2a 2a 20 6c 61 73 74 20 70 72  n the.** last pr
7850: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
7860: 20 69 73 20 66 69 6e 61 6c 69 7a 65 64 20 6f 72   is finalized or
7870: 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65   the last sqlite
7880: 33 5f 62 61 63 6b 75 70 20 69 73 0a 2a 2a 20 66  3_backup is.** f
7890: 69 6e 69 73 68 65 64 2e 20 20 54 68 65 20 73 71  inished.  The sq
78a0: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29  lite3_close_v2()
78b0: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 69 6e   interface is in
78c0: 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 77  tended for use w
78d0: 69 74 68 0a 2a 2a 20 68 6f 73 74 20 6c 61 6e 67  ith.** host lang
78e0: 75 61 67 65 73 20 74 68 61 74 20 61 72 65 20 67  uages that are g
78f0: 61 72 62 61 67 65 20 63 6f 6c 6c 65 63 74 65 64  arbage collected
7900: 2c 20 61 6e 64 20 77 68 65 72 65 20 74 68 65 20  , and where the 
7910: 6f 72 64 65 72 20 69 6e 20 77 68 69 63 68 0a 2a  order in which.*
7920: 2a 20 64 65 73 74 72 75 63 74 6f 72 73 20 61 72  * destructors ar
7930: 65 20 63 61 6c 6c 65 64 20 69 73 20 61 72 62 69  e called is arbi
7940: 74 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 41 70 70  trary..**.** App
7950: 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64  lications should
7960: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
7970: 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 5d 20 61  ze | finalize] a
7980: 6c 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ll [prepared sta
7990: 74 65 6d 65 6e 74 73 5d 2c 0a 2a 2a 20 5b 73 71  tements],.** [sq
79a0: 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65  lite3_blob_close
79b0: 20 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42   | close] all [B
79c0: 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61 6e  LOB handles], an
79d0: 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  d .** [sqlite3_b
79e0: 61 63 6b 75 70 5f 66 69 6e 69 73 68 20 7c 20 66  ackup_finish | f
79f0: 69 6e 69 73 68 5d 20 61 6c 6c 20 5b 73 71 6c 69  inish] all [sqli
7a00: 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65  te3_backup] obje
7a10: 63 74 73 20 61 73 73 6f 63 69 61 74 65 64 0a 2a  cts associated.*
7a20: 2a 20 77 69 74 68 20 74 68 65 20 5b 73 71 6c 69  * with the [sqli
7a30: 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 72 69 6f  te3] object prio
7a40: 72 20 74 6f 20 61 74 74 65 6d 70 74 69 6e 67 20  r to attempting 
7a50: 74 6f 20 63 6c 6f 73 65 20 74 68 65 20 6f 62 6a  to close the obj
7a60: 65 63 74 2e 20 20 5e 49 66 0a 2a 2a 20 73 71 6c  ect.  ^If.** sql
7a70: 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20  ite3_close_v2() 
7a80: 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b  is called on a [
7a90: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
7aa0: 69 6f 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c 20  ion] that still 
7ab0: 68 61 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64 69  has.** outstandi
7ac0: 6e 67 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ng [prepared sta
7ad0: 74 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20  tements], [BLOB 
7ae0: 68 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 2f 6f 72  handles], and/or
7af0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63  .** [sqlite3_bac
7b00: 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20 74 68 65  kup] objects the
7b10: 6e 20 69 74 20 72 65 74 75 72 6e 73 20 53 51 4c  n it returns SQL
7b20: 49 54 45 5f 4f 4b 20 62 75 74 20 74 68 65 20 64  ITE_OK but the d
7b30: 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f  eallocation.** o
7b40: 66 20 72 65 73 6f 75 72 63 65 73 20 69 73 20 64  f resources is d
7b50: 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61 6c  eferred until al
7b60: 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  l [prepared stat
7b70: 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68  ements], [BLOB h
7b80: 61 6e 64 6c 65 73 5d 2c 0a 2a 2a 20 61 6e 64 20  andles],.** and 
7b90: 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d  [sqlite3_backup]
7ba0: 20 6f 62 6a 65 63 74 73 20 61 72 65 20 61 6c 73   objects are als
7bb0: 6f 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 0a  o destroyed..**.
7bc0: 2a 2a 20 5e 49 66 20 61 6e 20 5b 73 71 6c 69 74  ** ^If an [sqlit
7bd0: 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 64 65  e3] object is de
7be0: 73 74 72 6f 79 65 64 20 77 68 69 6c 65 20 61 20  stroyed while a 
7bf0: 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 6f  transaction is o
7c00: 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61 6e  pen,.** the tran
7c10: 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74 6f 6d  saction is autom
7c20: 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20  atically rolled 
7c30: 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  back..**.** The 
7c40: 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  C parameter to [
7c50: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29  sqlite3_close(C)
7c60: 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  ] and [sqlite3_c
7c70: 6c 6f 73 65 5f 76 32 28 43 29 5d 0a 2a 2a 20 6d  lose_v2(C)].** m
7c80: 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61 20  ust be either a 
7c90: 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  NULL.** pointer 
7ca0: 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20  or an [sqlite3] 
7cb0: 6f 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 6f  object pointer o
7cc0: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
7cd0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
7ce0: 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  , [sqlite3_open1
7cf0: 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c  6()], or.** [sql
7d00: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c  ite3_open_v2()],
7d10: 20 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f 75   and not previou
7d20: 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e  sly closed..** ^
7d30: 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f  Calling sqlite3_
7d40: 63 6c 6f 73 65 28 29 20 6f 72 20 73 71 6c 69 74  close() or sqlit
7d50: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 77 69  e3_close_v2() wi
7d60: 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  th a NULL pointe
7d70: 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73  r.** argument is
7d80: 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f   a harmless no-o
7d90: 70 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  p..*/.SQLITE_API
7da0: 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f   int sqlite3_clo
7db0: 73 65 28 73 71 6c 69 74 65 33 2a 29 3b 0a 53 51  se(sqlite3*);.SQ
7dc0: 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
7dd0: 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 73 71  ite3_close_v2(sq
7de0: 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
7df0: 54 68 65 20 74 79 70 65 20 66 6f 72 20 61 20 63  The type for a c
7e00: 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
7e10: 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 6c 65 67  ..** This is leg
7e20: 61 63 79 20 61 6e 64 20 64 65 70 72 65 63 61 74  acy and deprecat
7e30: 65 64 2e 20 20 49 74 20 69 73 20 69 6e 63 6c 75  ed.  It is inclu
7e40: 64 65 64 20 66 6f 72 20 68 69 73 74 6f 72 69 63  ded for historic
7e50: 61 6c 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c  al.** compatibil
7e60: 69 74 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 64  ity and is not d
7e70: 6f 63 75 6d 65 6e 74 65 64 2e 0a 2a 2f 0a 74 79  ocumented..*/.ty
7e80: 70 65 64 65 66 20 69 6e 74 20 28 2a 73 71 6c 69  pedef int (*sqli
7e90: 74 65 33 5f 63 61 6c 6c 62 61 63 6b 29 28 76 6f  te3_callback)(vo
7ea0: 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 20  id*,int,char**, 
7eb0: 63 68 61 72 2a 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  char**);../*.** 
7ec0: 43 41 50 49 33 52 45 46 3a 20 4f 6e 65 2d 53 74  CAPI3REF: One-St
7ed0: 65 70 20 51 75 65 72 79 20 45 78 65 63 75 74 69  ep Query Executi
7ee0: 6f 6e 20 49 6e 74 65 72 66 61 63 65 0a 2a 2a 0a  on Interface.**.
7ef0: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65  ** The sqlite3_e
7f00: 78 65 63 28 29 20 69 6e 74 65 72 66 61 63 65 20  xec() interface 
7f10: 69 73 20 61 20 63 6f 6e 76 65 6e 69 65 6e 63 65  is a convenience
7f20: 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a   wrapper around.
7f30: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
7f40: 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69  are_v2()], [sqli
7f50: 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 61 6e 64  te3_step()], and
7f60: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
7f70: 7a 65 28 29 5d 2c 0a 2a 2a 20 74 68 61 74 20 61  ze()],.** that a
7f80: 6c 6c 6f 77 73 20 61 6e 20 61 70 70 6c 69 63 61  llows an applica
7f90: 74 69 6f 6e 20 74 6f 20 72 75 6e 20 6d 75 6c 74  tion to run mult
7fa0: 69 70 6c 65 20 73 74 61 74 65 6d 65 6e 74 73 20  iple statements 
7fb0: 6f 66 20 53 51 4c 0a 2a 2a 20 77 69 74 68 6f 75  of SQL.** withou
7fc0: 74 20 68 61 76 69 6e 67 20 74 6f 20 75 73 65 20  t having to use 
7fd0: 61 20 6c 6f 74 20 6f 66 20 43 20 63 6f 64 65 2e  a lot of C code.
7fe0: 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c   .**.** ^The sql
7ff0: 69 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65  ite3_exec() inte
8000: 72 66 61 63 65 20 72 75 6e 73 20 7a 65 72 6f 20  rface runs zero 
8010: 6f 72 20 6d 6f 72 65 20 55 54 46 2d 38 20 65 6e  or more UTF-8 en
8020: 63 6f 64 65 64 2c 0a 2a 2a 20 73 65 6d 69 63 6f  coded,.** semico
8030: 6c 6f 6e 2d 73 65 70 61 72 61 74 65 20 53 51 4c  lon-separate SQL
8040: 20 73 74 61 74 65 6d 65 6e 74 73 20 70 61 73 73   statements pass
8050: 65 64 20 69 6e 74 6f 20 69 74 73 20 32 6e 64 20  ed into its 2nd 
8060: 61 72 67 75 6d 65 6e 74 2c 0a 2a 2a 20 69 6e 20  argument,.** in 
8070: 74 68 65 20 63 6f 6e 74 65 78 74 20 6f 66 20 74  the context of t
8080: 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
8090: 6e 65 63 74 69 6f 6e 5d 20 70 61 73 73 65 64 20  nection] passed 
80a0: 69 6e 20 61 73 20 69 74 73 20 31 73 74 0a 2a 2a  in as its 1st.**
80b0: 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 49 66 20   argument.  ^If 
80c0: 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  the callback fun
80d0: 63 74 69 6f 6e 20 6f 66 20 74 68 65 20 33 72 64  ction of the 3rd
80e0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
80f0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
8100: 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e  s not NULL, then
8110: 20 69 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 66   it is invoked f
8120: 6f 72 20 65 61 63 68 20 72 65 73 75 6c 74 20 72  or each result r
8130: 6f 77 0a 2a 2a 20 63 6f 6d 69 6e 67 20 6f 75 74  ow.** coming out
8140: 20 6f 66 20 74 68 65 20 65 76 61 6c 75 61 74 65   of the evaluate
8150: 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  d SQL statements
8160: 2e 20 20 5e 54 68 65 20 34 74 68 20 61 72 67 75  .  ^The 4th argu
8170: 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  ment to.** sqlit
8180: 65 33 5f 65 78 65 63 28 29 20 69 73 20 72 65 6c  e3_exec() is rel
8190: 61 79 65 64 20 74 68 72 6f 75 67 68 20 74 6f 20  ayed through to 
81a0: 74 68 65 20 31 73 74 20 61 72 67 75 6d 65 6e 74  the 1st argument
81b0: 20 6f 66 20 65 61 63 68 0a 2a 2a 20 63 61 6c 6c   of each.** call
81c0: 62 61 63 6b 20 69 6e 76 6f 63 61 74 69 6f 6e 2e  back invocation.
81d0: 20 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61    ^If the callba
81e0: 63 6b 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71  ck pointer to sq
81f0: 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20  lite3_exec().** 
8200: 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 6e 6f  is NULL, then no
8210: 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 65 76 65   callback is eve
8220: 72 20 69 6e 76 6f 6b 65 64 20 61 6e 64 20 72 65  r invoked and re
8230: 73 75 6c 74 20 72 6f 77 73 20 61 72 65 0a 2a 2a  sult rows are.**
8240: 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20   ignored..**.** 
8250: 5e 49 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63  ^If an error occ
8260: 75 72 73 20 77 68 69 6c 65 20 65 76 61 6c 75 61  urs while evalua
8270: 74 69 6e 67 20 74 68 65 20 53 51 4c 20 73 74 61  ting the SQL sta
8280: 74 65 6d 65 6e 74 73 20 70 61 73 73 65 64 20 69  tements passed i
8290: 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65  nto.** sqlite3_e
82a0: 78 65 63 28 29 2c 20 74 68 65 6e 20 65 78 65 63  xec(), then exec
82b0: 75 74 69 6f 6e 20 6f 66 20 74 68 65 20 63 75 72  ution of the cur
82c0: 72 65 6e 74 20 73 74 61 74 65 6d 65 6e 74 20 73  rent statement s
82d0: 74 6f 70 73 20 61 6e 64 0a 2a 2a 20 73 75 62 73  tops and.** subs
82e0: 65 71 75 65 6e 74 20 73 74 61 74 65 6d 65 6e 74  equent statement
82f0: 73 20 61 72 65 20 73 6b 69 70 70 65 64 2e 20 20  s are skipped.  
8300: 5e 49 66 20 74 68 65 20 35 74 68 20 70 61 72 61  ^If the 5th para
8310: 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
8320: 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73 20 6e 6f  _exec().** is no
8330: 74 20 4e 55 4c 4c 20 74 68 65 6e 20 61 6e 79 20  t NULL then any 
8340: 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 69 73  error message is
8350: 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65   written into me
8360: 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 0a 2a 2a  mory obtained.**
8370: 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
8380: 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 70 61 73  alloc()] and pas
8390: 73 65 64 20 62 61 63 6b 20 74 68 72 6f 75 67 68  sed back through
83a0: 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74   the 5th paramet
83b0: 65 72 2e 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20  er..** To avoid 
83c0: 6d 65 6d 6f 72 79 20 6c 65 61 6b 73 2c 20 74 68  memory leaks, th
83d0: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
83e0: 6f 75 6c 64 20 69 6e 76 6f 6b 65 20 5b 73 71 6c  ould invoke [sql
83f0: 69 74 65 33 5f 66 72 65 65 28 29 5d 0a 2a 2a 20  ite3_free()].** 
8400: 6f 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  on error message
8410: 20 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65   strings returne
8420: 64 20 74 68 72 6f 75 67 68 20 74 68 65 20 35 74  d through the 5t
8430: 68 20 70 61 72 61 6d 65 74 65 72 20 6f 66 0a 2a  h parameter of.*
8440: 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 65 78 65  * of sqlite3_exe
8450: 63 28 29 20 61 66 74 65 72 20 74 68 65 20 65 72  c() after the er
8460: 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69  ror message stri
8470: 6e 67 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20  ng is no longer 
8480: 6e 65 65 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 74  needed..** ^If t
8490: 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
84a0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63   to sqlite3_exec
84b0: 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61  () is not NULL a
84c0: 6e 64 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20  nd no errors.** 
84d0: 6f 63 63 75 72 2c 20 74 68 65 6e 20 73 71 6c 69  occur, then sqli
84e0: 74 65 33 5f 65 78 65 63 28 29 20 73 65 74 73 20  te3_exec() sets 
84f0: 74 68 65 20 70 6f 69 6e 74 65 72 20 69 6e 20 69  the pointer in i
8500: 74 73 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  ts 5th parameter
8510: 20 74 6f 0a 2a 2a 20 4e 55 4c 4c 20 62 65 66 6f   to.** NULL befo
8520: 72 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a  re returning..**
8530: 0a 2a 2a 20 5e 49 66 20 61 6e 20 73 71 6c 69 74  .** ^If an sqlit
8540: 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61  e3_exec() callba
8550: 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a  ck returns non-z
8560: 65 72 6f 2c 20 74 68 65 20 73 71 6c 69 74 65 33  ero, the sqlite3
8570: 5f 65 78 65 63 28 29 0a 2a 2a 20 72 6f 75 74 69  _exec().** routi
8580: 6e 65 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54  ne returns SQLIT
8590: 45 5f 41 42 4f 52 54 20 77 69 74 68 6f 75 74 20  E_ABORT without 
85a0: 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 63 61 6c  invoking the cal
85b0: 6c 62 61 63 6b 20 61 67 61 69 6e 20 61 6e 64 0a  lback again and.
85c0: 2a 2a 20 77 69 74 68 6f 75 74 20 72 75 6e 6e 69  ** without runni
85d0: 6e 67 20 61 6e 79 20 73 75 62 73 65 71 75 65 6e  ng any subsequen
85e0: 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  t SQL statements
85f0: 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 32 6e 64  ..**.** ^The 2nd
8600: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
8610: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
8620: 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
8630: 6e 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62  n is the.** numb
8640: 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
8650: 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20 5e 54   the result.  ^T
8660: 68 65 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20  he 3rd argument 
8670: 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65  to the sqlite3_e
8680: 78 65 63 28 29 0a 2a 2a 20 63 61 6c 6c 62 61 63  xec().** callbac
8690: 6b 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66  k is an array of
86a0: 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72   pointers to str
86b0: 69 6e 67 73 20 6f 62 74 61 69 6e 65 64 20 61 73  ings obtained as
86c0: 20 69 66 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c   if from.** [sql
86d0: 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
86e0: 28 29 5d 2c 20 6f 6e 65 20 66 6f 72 20 65 61 63  ()], one for eac
86f0: 68 20 63 6f 6c 75 6d 6e 2e 20 20 5e 49 66 20 61  h column.  ^If a
8700: 6e 20 65 6c 65 6d 65 6e 74 20 6f 66 20 61 0a 2a  n element of a.*
8710: 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 69 73 20  * result row is 
8720: 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 63 6f  NULL then the co
8730: 72 72 65 73 70 6f 6e 64 69 6e 67 20 73 74 72 69  rresponding stri
8740: 6e 67 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74  ng pointer for t
8750: 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78  he.** sqlite3_ex
8760: 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73  ec() callback is
8770: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
8780: 20 20 5e 54 68 65 20 34 74 68 20 61 72 67 75 6d    ^The 4th argum
8790: 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20 73 71  ent to the.** sq
87a0: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c  lite3_exec() cal
87b0: 6c 62 61 63 6b 20 69 73 20 61 6e 20 61 72 72 61  lback is an arra
87c0: 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f  y of pointers to
87d0: 20 73 74 72 69 6e 67 73 20 77 68 65 72 65 20 65   strings where e
87e0: 61 63 68 0a 2a 2a 20 65 6e 74 72 79 20 72 65 70  ach.** entry rep
87f0: 72 65 73 65 6e 74 73 20 74 68 65 20 6e 61 6d 65  resents the name
8800: 20 6f 66 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e   of correspondin
8810: 67 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  g result column 
8820: 61 73 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66  as obtained.** f
8830: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  rom [sqlite3_col
8840: 75 6d 6e 5f 6e 61 6d 65 28 29 5d 2e 0a 2a 2a 0a  umn_name()]..**.
8850: 2a 2a 20 5e 49 66 20 74 68 65 20 32 6e 64 20 70  ** ^If the 2nd p
8860: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
8870: 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 61 20  te3_exec() is a 
8880: 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 61 20  NULL pointer, a 
8890: 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 61 6e  pointer.** to an
88a0: 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 6f   empty string, o
88b0: 72 20 61 20 70 6f 69 6e 74 65 72 20 74 68 61 74  r a pointer that
88c0: 20 63 6f 6e 74 61 69 6e 73 20 6f 6e 6c 79 20 77   contains only w
88d0: 68 69 74 65 73 70 61 63 65 20 61 6e 64 2f 6f 72  hitespace and/or
88e0: 20 0a 2a 2a 20 53 51 4c 20 63 6f 6d 6d 65 6e 74   .** SQL comment
88f0: 73 2c 20 74 68 65 6e 20 6e 6f 20 53 51 4c 20 73  s, then no SQL s
8900: 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 65 76  tatements are ev
8910: 61 6c 75 61 74 65 64 20 61 6e 64 20 74 68 65 20  aluated and the 
8920: 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 6e  database.** is n
8930: 6f 74 20 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a  ot changed..**.*
8940: 2a 20 52 65 73 74 72 69 63 74 69 6f 6e 73 3a 0a  * Restrictions:.
8950: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
8960: 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  i> The applicati
8970: 6f 6e 20 6d 75 73 74 20 69 6e 73 75 72 65 20 74  on must insure t
8980: 68 61 74 20 74 68 65 20 31 73 74 20 70 61 72 61  hat the 1st para
8990: 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
89a0: 5f 65 78 65 63 28 29 0a 2a 2a 20 20 20 20 20 20  _exec().**      
89b0: 69 73 20 61 20 76 61 6c 69 64 20 61 6e 64 20 6f  is a valid and o
89c0: 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f  pen [database co
89d0: 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 3c 6c  nnection]..** <l
89e0: 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  i> The applicati
89f0: 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73  on must not clos
8a00: 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
8a10: 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65  ection] specifie
8a20: 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 74 68 65  d by.**      the
8a30: 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 20 74   1st parameter t
8a40: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  o sqlite3_exec()
8a50: 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65   while sqlite3_e
8a60: 78 65 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67  xec() is running
8a70: 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70  ..** <li> The ap
8a80: 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e  plication must n
8a90: 6f 74 20 6d 6f 64 69 66 79 20 74 68 65 20 53 51  ot modify the SQ
8aa0: 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74  L statement text
8ab0: 20 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20   passed into.** 
8ac0: 20 20 20 20 20 74 68 65 20 32 6e 64 20 70 61 72       the 2nd par
8ad0: 61 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65  ameter of sqlite
8ae0: 33 5f 65 78 65 63 28 29 20 77 68 69 6c 65 20 73  3_exec() while s
8af0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73  qlite3_exec() is
8b00: 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75   running..** </u
8b10: 6c 3e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  l>.*/.SQLITE_API
8b20: 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 65   int sqlite3_exe
8b30: 63 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 20  c(.  sqlite3*,  
8b40: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
8b50: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
8b60: 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62  /* An open datab
8b70: 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  ase */.  const c
8b80: 68 61 72 20 2a 73 71 6c 2c 20 20 20 20 20 20 20  har *sql,       
8b90: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
8ba0: 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65      /* SQL to be
8bb0: 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20   evaluated */.  
8bc0: 69 6e 74 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28  int (*callback)(
8bd0: 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a  void*,int,char**
8be0: 2c 63 68 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61  ,char**),  /* Ca
8bf0: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
8c00: 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20 20 20 20  */.  void *,    
8c10: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
8c20: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
8c30: 2f 2a 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20  /* 1st argument 
8c40: 74 6f 20 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20  to callback */. 
8c50: 20 63 68 61 72 20 2a 2a 65 72 72 6d 73 67 20 20   char **errmsg  
8c60: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
8c70: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 45              /* E
8c80: 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e  rror msg written
8c90: 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a   here */.);../*.
8ca0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73  ** CAPI3REF: Res
8cb0: 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59  ult Codes.** KEY
8cc0: 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 4f 4b  WORDS: SQLITE_OK
8cd0: 20 7b 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65   {error code} {e
8ce0: 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b  rror codes}.** K
8cf0: 45 59 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74  EYWORDS: {result
8d00: 20 63 6f 64 65 7d 20 7b 72 65 73 75 6c 74 20 63   code} {result c
8d10: 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79  odes}.**.** Many
8d20: 20 53 51 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e   SQLite function
8d30: 73 20 72 65 74 75 72 6e 20 61 6e 20 69 6e 74 65  s return an inte
8d40: 67 65 72 20 72 65 73 75 6c 74 20 63 6f 64 65 20  ger result code 
8d50: 66 72 6f 6d 20 74 68 65 20 73 65 74 20 73 68 6f  from the set sho
8d60: 77 6e 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72  wn.** here in or
8d70: 64 65 72 20 74 6f 20 69 6e 64 69 63 61 74 65 20  der to indicate 
8d80: 73 75 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75  success or failu
8d90: 72 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72  re..**.** New er
8da0: 72 6f 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65  ror codes may be
8db0: 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
8dc0: 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
8dd0: 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ite..**.** See a
8de0: 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 45  lso: [SQLITE_IOE
8df0: 52 52 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64  RR_READ | extend
8e00: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d  ed result codes]
8e10: 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 74  ,.** [sqlite3_vt
8e20: 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29  ab_on_conflict()
8e30: 5d 20 5b 53 51 4c 49 54 45 5f 52 4f 4c 4c 42 41  ] [SQLITE_ROLLBA
8e40: 43 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65  CK | result code
8e50: 73 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  s]..*/.#define S
8e60: 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20 20 20  QLITE_OK        
8e70: 20 20 20 30 20 20 20 2f 2a 20 53 75 63 63 65 73     0   /* Succes
8e80: 73 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a 2f  sful result */./
8e90: 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d 65  * beginning-of-e
8ea0: 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 23 64  rror-codes */.#d
8eb0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 52 52  efine SQLITE_ERR
8ec0: 4f 52 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a  OR        1   /*
8ed0: 20 53 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d 69   SQL error or mi
8ee0: 73 73 69 6e 67 20 64 61 74 61 62 61 73 65 20 2a  ssing database *
8ef0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
8f00: 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20 20 32 20  _INTERNAL     2 
8f10: 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 6c 6f    /* Internal lo
8f20: 67 69 63 20 65 72 72 6f 72 20 69 6e 20 53 51 4c  gic error in SQL
8f30: 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ite */.#define S
8f40: 51 4c 49 54 45 5f 50 45 52 4d 20 20 20 20 20 20  QLITE_PERM      
8f50: 20 20 20 33 20 20 20 2f 2a 20 41 63 63 65 73 73     3   /* Access
8f60: 20 70 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e 69   permission deni
8f70: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
8f80: 4c 49 54 45 5f 41 42 4f 52 54 20 20 20 20 20 20  LITE_ABORT      
8f90: 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61 63    4   /* Callbac
8fa0: 6b 20 72 6f 75 74 69 6e 65 20 72 65 71 75 65 73  k routine reques
8fb0: 74 65 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f 0a  ted an abort */.
8fc0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42  #define SQLITE_B
8fd0: 55 53 59 20 20 20 20 20 20 20 20 20 35 20 20 20  USY         5   
8fe0: 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20  /* The database 
8ff0: 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a  file is locked *
9000: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
9010: 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 36 20  _LOCKED       6 
9020: 20 20 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e 20    /* A table in 
9030: 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  the database is 
9040: 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e  locked */.#defin
9050: 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 20  e SQLITE_NOMEM  
9060: 20 20 20 20 20 20 37 20 20 20 2f 2a 20 41 20 6d        7   /* A m
9070: 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64 20 2a  alloc() failed *
9080: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
9090: 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 38 20  _READONLY     8 
90a0: 20 20 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f 20    /* Attempt to 
90b0: 77 72 69 74 65 20 61 20 72 65 61 64 6f 6e 6c 79  write a readonly
90c0: 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65   database */.#de
90d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45  fine SQLITE_INTE
90e0: 52 52 55 50 54 20 20 20 20 39 20 20 20 2f 2a 20  RRUPT    9   /* 
90f0: 4f 70 65 72 61 74 69 6f 6e 20 74 65 72 6d 69 6e  Operation termin
9100: 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  ated by sqlite3_
9110: 69 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a 23 64  interrupt()*/.#d
9120: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
9130: 52 52 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a  RR       10   /*
9140: 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64 69   Some kind of di
9150: 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63 63  sk I/O error occ
9160: 75 72 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  urred */.#define
9170: 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20   SQLITE_CORRUPT 
9180: 20 20 20 20 31 31 20 20 20 2f 2a 20 54 68 65 20      11   /* The 
9190: 64 61 74 61 62 61 73 65 20 64 69 73 6b 20 69 6d  database disk im
91a0: 61 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65 64  age is malformed
91b0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
91c0: 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20 31  TE_NOTFOUND    1
91d0: 32 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e 20 6f  2   /* Unknown o
91e0: 70 63 6f 64 65 20 69 6e 20 73 71 6c 69 74 65 33  pcode in sqlite3
91f0: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 20  _file_control() 
9200: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
9210: 45 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 31 33  E_FULL        13
9220: 20 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e 20     /* Insertion 
9230: 66 61 69 6c 65 64 20 62 65 63 61 75 73 65 20 64  failed because d
9240: 61 74 61 62 61 73 65 20 69 73 20 66 75 6c 6c 20  atabase is full 
9250: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
9260: 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20 31 34  E_CANTOPEN    14
9270: 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f 20     /* Unable to 
9280: 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  open the databas
9290: 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e  e file */.#defin
92a0: 65 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43 4f  e SQLITE_PROTOCO
92b0: 4c 20 20 20 20 31 35 20 20 20 2f 2a 20 44 61 74  L    15   /* Dat
92c0: 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74 6f  abase lock proto
92d0: 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65  col error */.#de
92e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50 54  fine SQLITE_EMPT
92f0: 59 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20  Y       16   /* 
9300: 44 61 74 61 62 61 73 65 20 69 73 20 65 6d 70 74  Database is empt
9310: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
9320: 49 54 45 5f 53 43 48 45 4d 41 20 20 20 20 20 20  ITE_SCHEMA      
9330: 31 37 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61  17   /* The data
9340: 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e  base schema chan
9350: 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ged */.#define S
9360: 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20 20 20  QLITE_TOOBIG    
9370: 20 20 31 38 20 20 20 2f 2a 20 53 74 72 69 6e 67    18   /* String
9380: 20 6f 72 20 42 4c 4f 42 20 65 78 63 65 65 64 73   or BLOB exceeds
9390: 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a 23   size limit */.#
93a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
93b0: 4e 53 54 52 41 49 4e 54 20 20 31 39 20 20 20 2f  NSTRAINT  19   /
93c0: 2a 20 41 62 6f 72 74 20 64 75 65 20 74 6f 20 63  * Abort due to c
93d0: 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74  onstraint violat
93e0: 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ion */.#define S
93f0: 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48 20 20  QLITE_MISMATCH  
9400: 20 20 32 30 20 20 20 2f 2a 20 44 61 74 61 20 74    20   /* Data t
9410: 79 70 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f 0a  ype mismatch */.
9420: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d  #define SQLITE_M
9430: 49 53 55 53 45 20 20 20 20 20 20 32 31 20 20 20  ISUSE      21   
9440: 2f 2a 20 4c 69 62 72 61 72 79 20 75 73 65 64 20  /* Library used 
9450: 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a 23  incorrectly */.#
9460: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
9470: 4c 46 53 20 20 20 20 20 20 20 32 32 20 20 20 2f  LFS       22   /
9480: 2a 20 55 73 65 73 20 4f 53 20 66 65 61 74 75 72  * Uses OS featur
9490: 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 65 64  es not supported
94a0: 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65 66   on host */.#def
94b0: 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48 20  ine SQLITE_AUTH 
94c0: 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 41         23   /* A
94d0: 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65 6e  uthorization den
94e0: 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ied */.#define S
94f0: 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20 20 20  QLITE_FORMAT    
9500: 20 20 32 34 20 20 20 2f 2a 20 41 75 78 69 6c 69    24   /* Auxili
9510: 61 72 79 20 64 61 74 61 62 61 73 65 20 66 6f 72  ary database for
9520: 6d 61 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65  mat error */.#de
9530: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e 47  fine SQLITE_RANG
9540: 45 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20  E       25   /* 
9550: 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  2nd parameter to
9560: 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f 75   sqlite3_bind ou
9570: 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23 64  t of range */.#d
9580: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54  efine SQLITE_NOT
9590: 41 44 42 20 20 20 20 20 20 32 36 20 20 20 2f 2a  ADB      26   /*
95a0: 20 46 69 6c 65 20 6f 70 65 6e 65 64 20 74 68 61   File opened tha
95b0: 74 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62  t is not a datab
95c0: 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66  ase file */.#def
95d0: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43  ine SQLITE_NOTIC
95e0: 45 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20 4e  E      27   /* N
95f0: 6f 74 69 66 69 63 61 74 69 6f 6e 73 20 66 72 6f  otifications fro
9600: 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 20  m sqlite3_log() 
9610: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
9620: 45 5f 57 41 52 4e 49 4e 47 20 20 20 20 20 32 38  E_WARNING     28
9630: 20 20 20 2f 2a 20 57 61 72 6e 69 6e 67 73 20 66     /* Warnings f
9640: 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67 28  rom sqlite3_log(
9650: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
9660: 49 54 45 5f 52 4f 57 20 20 20 20 20 20 20 20 20  ITE_ROW         
9670: 31 30 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f  100  /* sqlite3_
9680: 73 74 65 70 28 29 20 68 61 73 20 61 6e 6f 74 68  step() has anoth
9690: 65 72 20 72 6f 77 20 72 65 61 64 79 20 2a 2f 0a  er row ready */.
96a0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
96b0: 4f 4e 45 20 20 20 20 20 20 20 20 31 30 31 20 20  ONE        101  
96c0: 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  /* sqlite3_step(
96d0: 29 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 65  ) has finished e
96e0: 78 65 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20 65  xecuting */./* e
96f0: 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65  nd-of-error-code
9700: 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  s */../*.** CAPI
9710: 33 52 45 46 3a 20 45 78 74 65 6e 64 65 64 20 52  3REF: Extended R
9720: 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b  esult Codes.** K
9730: 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64  EYWORDS: {extend
9740: 65 64 20 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b  ed error code} {
9750: 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63  extended error c
9760: 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  odes}.** KEYWORD
9770: 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 72 65 73  S: {extended res
9780: 75 6c 74 20 63 6f 64 65 7d 20 7b 65 78 74 65 6e  ult code} {exten
9790: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
97a0: 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 69 74 73 20 64  }.**.** In its d
97b0: 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61  efault configura
97c0: 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20 41 50 49  tion, SQLite API
97d0: 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
97e0: 20 6f 6e 65 20 6f 66 20 32 36 20 69 6e 74 65 67   one of 26 integ
97f0: 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b  er.** [SQLITE_OK
9800: 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d   | result codes]
9810: 2e 20 20 48 6f 77 65 76 65 72 2c 20 65 78 70 65  .  However, expe
9820: 72 69 65 6e 63 65 20 68 61 73 20 73 68 6f 77 6e  rience has shown
9830: 20 74 68 61 74 20 6d 61 6e 79 20 6f 66 0a 2a 2a   that many of.**
9840: 20 74 68 65 73 65 20 72 65 73 75 6c 74 20 63 6f   these result co
9850: 64 65 73 20 61 72 65 20 74 6f 6f 20 63 6f 61 72  des are too coar
9860: 73 65 2d 67 72 61 69 6e 65 64 2e 20 20 54 68 65  se-grained.  The
9870: 79 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69 64 65  y do not provide
9880: 20 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e 66 6f   as.** much info
9890: 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 70 72  rmation about pr
98a0: 6f 62 6c 65 6d 73 20 61 73 20 70 72 6f 67 72 61  oblems as progra
98b0: 6d 6d 65 72 73 20 6d 69 67 68 74 20 6c 69 6b 65  mmers might like
98c0: 2e 20 20 49 6e 20 61 6e 20 65 66 66 6f 72 74 20  .  In an effort 
98d0: 74 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20 74 68  to.** address th
98e0: 69 73 2c 20 6e 65 77 65 72 20 76 65 72 73 69 6f  is, newer versio
98f0: 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 28 76 65  ns of SQLite (ve
9900: 72 73 69 6f 6e 20 33 2e 33 2e 38 20 61 6e 64 20  rsion 3.3.8 and 
9910: 6c 61 74 65 72 29 20 69 6e 63 6c 75 64 65 0a 2a  later) include.*
9920: 2a 20 73 75 70 70 6f 72 74 20 66 6f 72 20 61 64  * support for ad
9930: 64 69 74 69 6f 6e 61 6c 20 72 65 73 75 6c 74 20  ditional result 
9940: 63 6f 64 65 73 20 74 68 61 74 20 70 72 6f 76 69  codes that provi
9950: 64 65 20 6d 6f 72 65 20 64 65 74 61 69 6c 65 64  de more detailed
9960: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20   information.** 
9970: 61 62 6f 75 74 20 65 72 72 6f 72 73 2e 20 54 68  about errors. Th
9980: 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c  e extended resul
9990: 74 20 63 6f 64 65 73 20 61 72 65 20 65 6e 61 62  t codes are enab
99a0: 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 0a  led or disabled.
99b0: 2a 2a 20 6f 6e 20 61 20 70 65 72 20 64 61 74 61  ** on a per data
99c0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
99d0: 62 61 73 69 73 20 75 73 69 6e 67 20 74 68 65 0a  basis using the.
99e0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 65  ** [sqlite3_exte
99f0: 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65  nded_result_code
9a00: 73 28 29 5d 20 41 50 49 2e 0a 2a 2a 0a 2a 2a 20  s()] API..**.** 
9a10: 53 6f 6d 65 20 6f 66 20 74 68 65 20 61 76 61 69  Some of the avai
9a20: 6c 61 62 6c 65 20 65 78 74 65 6e 64 65 64 20 72  lable extended r
9a30: 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20  esult codes are 
9a40: 6c 69 73 74 65 64 20 68 65 72 65 2e 0a 2a 2a 20  listed here..** 
9a50: 4f 6e 65 20 6d 61 79 20 65 78 70 65 63 74 20 74  One may expect t
9a60: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 78 74  he number of ext
9a70: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
9a80: 65 73 20 77 69 6c 6c 20 62 65 20 65 78 70 61 6e  es will be expan
9a90: 64 0a 2a 2a 20 6f 76 65 72 20 74 69 6d 65 2e 20  d.** over time. 
9aa0: 20 53 6f 66 74 77 61 72 65 20 74 68 61 74 20 75   Software that u
9ab0: 73 65 73 20 65 78 74 65 6e 64 65 64 20 72 65 73  ses extended res
9ac0: 75 6c 74 20 63 6f 64 65 73 20 73 68 6f 75 6c 64  ult codes should
9ad0: 20 65 78 70 65 63 74 0a 2a 2a 20 74 6f 20 73 65   expect.** to se
9ae0: 65 20 6e 65 77 20 72 65 73 75 6c 74 20 63 6f 64  e new result cod
9af0: 65 73 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  es in future rel
9b00: 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e  eases of SQLite.
9b10: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54  .**.** The SQLIT
9b20: 45 5f 4f 4b 20 72 65 73 75 6c 74 20 63 6f 64 65  E_OK result code
9b30: 20 77 69 6c 6c 20 6e 65 76 65 72 20 62 65 20 65   will never be e
9b40: 78 74 65 6e 64 65 64 2e 20 20 49 74 20 77 69 6c  xtended.  It wil
9b50: 6c 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20 65  l always.** be e
9b60: 78 61 63 74 6c 79 20 7a 65 72 6f 2e 0a 2a 2f 0a  xactly zero..*/.
9b70: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
9b80: 4f 45 52 52 5f 52 45 41 44 20 20 20 20 20 20 20  OERR_READ       
9b90: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
9ba0: 4f 45 52 52 20 7c 20 28 31 3c 3c 38 29 29 0a 23  OERR | (1<<8)).#
9bb0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
9bc0: 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 20  ERR_SHORT_READ  
9bd0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
9be0: 45 52 52 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64  ERR | (2<<8)).#d
9bf0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
9c00: 52 52 5f 57 52 49 54 45 20 20 20 20 20 20 20 20  RR_WRITE        
9c10: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
9c20: 52 52 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65  RR | (3<<8)).#de
9c30: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
9c40: 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20 20  R_FSYNC         
9c50: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
9c60: 52 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 66  R | (4<<8)).#def
9c70: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
9c80: 5f 44 49 52 5f 46 53 59 4e 43 20 20 20 20 20 20  _DIR_FSYNC      
9c90: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
9ca0: 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69   | (5<<8)).#defi
9cb0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
9cc0: 54 52 55 4e 43 41 54 45 20 20 20 20 20 20 20 20  TRUNCATE        
9cd0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
9ce0: 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (6<<8)).#defin
9cf0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46  e SQLITE_IOERR_F
9d00: 53 54 41 54 20 20 20 20 20 20 20 20 20 20 20 20  STAT            
9d10: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
9d20: 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (7<<8)).#define
9d30: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 55 4e   SQLITE_IOERR_UN
9d40: 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 20  LOCK            
9d50: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
9d60: 28 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (8<<8)).#define 
9d70: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 44 4c  SQLITE_IOERR_RDL
9d80: 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 20 28  OCK            (
9d90: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
9da0: 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  9<<8)).#define S
9db0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45  QLITE_IOERR_DELE
9dc0: 54 45 20 20 20 20 20 20 20 20 20 20 20 20 28 53  TE            (S
9dd0: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31  QLITE_IOERR | (1
9de0: 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  0<<8)).#define S
9df0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43  QLITE_IOERR_BLOC
9e00: 4b 45 44 20 20 20 20 20 20 20 20 20 20 20 28 53  KED           (S
9e10: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31  QLITE_IOERR | (1
9e20: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
9e30: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4e 4f 4d 45  QLITE_IOERR_NOME
9e40: 4d 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53  M             (S
9e50: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31  QLITE_IOERR | (1
9e60: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  2<<8)).#define S
9e70: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 41 43 43 45  QLITE_IOERR_ACCE
9e80: 53 53 20 20 20 20 20 20 20 20 20 20 20 20 28 53  SS            (S
9e90: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31  QLITE_IOERR | (1
9ea0: 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  3<<8)).#define S
9eb0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 48 45 43  QLITE_IOERR_CHEC
9ec0: 4b 52 45 53 45 52 56 45 44 4c 4f 43 4b 20 28 53  KRESERVEDLOCK (S
9ed0: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31  QLITE_IOERR | (1
9ee0: 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  4<<8)).#define S
9ef0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4c 4f 43 4b  QLITE_IOERR_LOCK
9f00: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53                (S
9f10: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31  QLITE_IOERR | (1
9f20: 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  5<<8)).#define S
9f30: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 4c 4f 53  QLITE_IOERR_CLOS
9f40: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53  E             (S
9f50: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31  QLITE_IOERR | (1
9f60: 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  6<<8)).#define S
9f70: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f  QLITE_IOERR_DIR_
9f80: 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 28 53  CLOSE         (S
9f90: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31  QLITE_IOERR | (1
9fa0: 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  7<<8)).#define S
9fb0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4f  QLITE_IOERR_SHMO
9fc0: 50 45 4e 20 20 20 20 20 20 20 20 20 20 20 28 53  PEN           (S
9fd0: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31  QLITE_IOERR | (1
9fe0: 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  8<<8)).#define S
9ff0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 53  QLITE_IOERR_SHMS
a000: 49 5a 45 20 20 20 20 20 20 20 20 20 20 20 28 53  IZE           (S
a010: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31  QLITE_IOERR | (1
a020: 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  9<<8)).#define S
a030: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4c  QLITE_IOERR_SHML
a040: 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 28 53  OCK           (S
a050: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32  QLITE_IOERR | (2
a060: 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  0<<8)).#define S
a070: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4d  QLITE_IOERR_SHMM
a080: 41 50 20 20 20 20 20 20 20 20 20 20 20 20 28 53  AP            (S
a090: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32  QLITE_IOERR | (2
a0a0: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
a0b0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 45 45 4b  QLITE_IOERR_SEEK
a0c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53                (S
a0d0: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32  QLITE_IOERR | (2
a0e0: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  2<<8)).#define S
a0f0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45  QLITE_IOERR_DELE
a100: 54 45 5f 4e 4f 45 4e 54 20 20 20 20 20 20 28 53  TE_NOENT      (S
a110: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32  QLITE_IOERR | (2
a120: 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  3<<8)).#define S
a130: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4d 4d 41 50  QLITE_IOERR_MMAP
a140: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53                (S
a150: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32  QLITE_IOERR | (2
a160: 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  4<<8)).#define S
a170: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 47 45 54 54  QLITE_IOERR_GETT
a180: 45 4d 50 50 41 54 48 20 20 20 20 20 20 20 28 53  EMPPATH       (S
a190: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32  QLITE_IOERR | (2
a1a0: 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  5<<8)).#define S
a1b0: 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 5f 53 48 41  QLITE_LOCKED_SHA
a1c0: 52 45 44 43 41 43 48 45 20 20 20 20 20 20 28 53  REDCACHE      (S
a1d0: 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 7c 20 20  QLITE_LOCKED |  
a1e0: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (1<<8)).#define 
a1f0: 53 51 4c 49 54 45 5f 42 55 53 59 5f 52 45 43 4f  SQLITE_BUSY_RECO
a200: 56 45 52 59 20 20 20 20 20 20 20 20 20 20 20 28  VERY           (
a210: 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20 7c 20  SQLITE_BUSY   | 
a220: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (1<<8)).#define
a230: 20 53 51 4c 49 54 45 5f 42 55 53 59 5f 53 4e 41   SQLITE_BUSY_SNA
a240: 50 53 48 4f 54 20 20 20 20 20 20 20 20 20 20 20  PSHOT           
a250: 28 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20 7c  (SQLITE_BUSY   |
a260: 20 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e    (2<<8)).#defin
a270: 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45  e SQLITE_CANTOPE
a280: 4e 5f 4e 4f 54 45 4d 50 44 49 52 20 20 20 20 20  N_NOTEMPDIR     
a290: 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45   (SQLITE_CANTOPE
a2a0: 4e 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66  N | (1<<8)).#def
a2b0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f  ine SQLITE_CANTO
a2c0: 50 45 4e 5f 49 53 44 49 52 20 20 20 20 20 20 20  PEN_ISDIR       
a2d0: 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f     (SQLITE_CANTO
a2e0: 50 45 4e 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64  PEN | (2<<8)).#d
a2f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e  efine SQLITE_CAN
a300: 54 4f 50 45 4e 5f 46 55 4c 4c 50 41 54 48 20 20  TOPEN_FULLPATH  
a310: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e       (SQLITE_CAN
a320: 54 4f 50 45 4e 20 7c 20 28 33 3c 3c 38 29 29 0a  TOPEN | (3<<8)).
a330: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
a340: 4f 52 52 55 50 54 5f 56 54 41 42 20 20 20 20 20  ORRUPT_VTAB     
a350: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43         (SQLITE_C
a360: 4f 52 52 55 50 54 20 7c 20 28 31 3c 3c 38 29 29  ORRUPT | (1<<8))
a370: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
a380: 52 45 41 44 4f 4e 4c 59 5f 52 45 43 4f 56 45 52  READONLY_RECOVER
a390: 59 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  Y       (SQLITE_
a3a0: 52 45 41 44 4f 4e 4c 59 20 7c 20 28 31 3c 3c 38  READONLY | (1<<8
a3b0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
a3c0: 45 5f 52 45 41 44 4f 4e 4c 59 5f 43 41 4e 54 4c  E_READONLY_CANTL
a3d0: 4f 43 4b 20 20 20 20 20 20 20 28 53 51 4c 49 54  OCK       (SQLIT
a3e0: 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 32 3c  E_READONLY | (2<
a3f0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
a400: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 52 4f 4c  ITE_READONLY_ROL
a410: 4c 42 41 43 4b 20 20 20 20 20 20 20 28 53 51 4c  LBACK       (SQL
a420: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28  ITE_READONLY | (
a430: 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  3<<8)).#define S
a440: 51 4c 49 54 45 5f 41 42 4f 52 54 5f 52 4f 4c 4c  QLITE_ABORT_ROLL
a450: 42 41 43 4b 20 20 20 20 20 20 20 20 20 20 28 53  BACK          (S
a460: 51 4c 49 54 45 5f 41 42 4f 52 54 20 7c 20 28 32  QLITE_ABORT | (2
a470: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
a480: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
a490: 43 48 45 43 4b 20 20 20 20 20 20 20 20 28 53 51  CHECK        (SQ
a4a0: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
a4b0: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
a4c0: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
a4d0: 49 4e 54 5f 43 4f 4d 4d 49 54 48 4f 4f 4b 20 20  INT_COMMITHOOK  
a4e0: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41   (SQLITE_CONSTRA
a4f0: 49 4e 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64  INT | (2<<8)).#d
a500: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
a510: 53 54 52 41 49 4e 54 5f 46 4f 52 45 49 47 4e 4b  STRAINT_FOREIGNK
a520: 45 59 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e  EY   (SQLITE_CON
a530: 53 54 52 41 49 4e 54 20 7c 20 28 33 3c 3c 38 29  STRAINT | (3<<8)
a540: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
a550: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 46 55 4e 43  _CONSTRAINT_FUNC
a560: 54 49 4f 4e 20 20 20 20 20 28 53 51 4c 49 54 45  TION     (SQLITE
a570: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 34  _CONSTRAINT | (4
a580: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
a590: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
a5a0: 4e 4f 54 4e 55 4c 4c 20 20 20 20 20 20 28 53 51  NOTNULL      (SQ
a5b0: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
a5c0: 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (5<<8)).#defin
a5d0: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
a5e0: 49 4e 54 5f 50 52 49 4d 41 52 59 4b 45 59 20 20  INT_PRIMARYKEY  
a5f0: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41   (SQLITE_CONSTRA
a600: 49 4e 54 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64  INT | (6<<8)).#d
a610: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
a620: 53 54 52 41 49 4e 54 5f 54 52 49 47 47 45 52 20  STRAINT_TRIGGER 
a630: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e       (SQLITE_CON
a640: 53 54 52 41 49 4e 54 20 7c 20 28 37 3c 3c 38 29  STRAINT | (7<<8)
a650: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
a660: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 55 4e 49 51  _CONSTRAINT_UNIQ
a670: 55 45 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  UE       (SQLITE
a680: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 38  _CONSTRAINT | (8
a690: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
a6a0: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
a6b0: 56 54 41 42 20 20 20 20 20 20 20 20 20 28 53 51  VTAB         (SQ
a6c0: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
a6d0: 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (9<<8)).#defin
a6e0: 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 5f  e SQLITE_NOTICE_
a6f0: 52 45 43 4f 56 45 52 5f 57 41 4c 20 20 20 20 20  RECOVER_WAL     
a700: 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20   (SQLITE_NOTICE 
a710: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
a720: 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 5f  e SQLITE_NOTICE_
a730: 52 45 43 4f 56 45 52 5f 52 4f 4c 4c 42 41 43 4b  RECOVER_ROLLBACK
a740: 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20   (SQLITE_NOTICE 
a750: 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (2<<8)).#defin
a760: 65 20 53 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47  e SQLITE_WARNING
a770: 5f 41 55 54 4f 49 4e 44 45 58 20 20 20 20 20 20  _AUTOINDEX      
a780: 20 28 53 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47   (SQLITE_WARNING
a790: 20 7c 20 28 31 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a   | (1<<8))../*.*
a7a0: 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67  * CAPI3REF: Flag
a7b0: 73 20 46 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20  s For File Open 
a7c0: 4f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a  Operations.**.**
a7d0: 20 54 68 65 73 65 20 62 69 74 20 76 61 6c 75 65   These bit value
a7e0: 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66  s are intended f
a7f0: 6f 72 20 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a  or use in the.**
a800: 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74   3rd parameter t
a810: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f  o the [sqlite3_o
a820: 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66  pen_v2()] interf
a830: 61 63 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68  ace and.** in th
a840: 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 4th parameter 
a850: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
a860: 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f  vfs.xOpen] metho
a870: 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  d..*/.#define SQ
a880: 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e  LITE_OPEN_READON
a890: 4c 59 20 20 20 20 20 20 20 20 20 30 78 30 30 30  LY         0x000
a8a0: 30 30 30 30 31 20 20 2f 2a 20 4f 6b 20 66 6f 72  00001  /* Ok for
a8b0: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
a8c0: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
a8d0: 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
a8e0: 49 54 45 20 20 20 20 20 20 20 20 30 78 30 30 30  ITE        0x000
a8f0: 30 30 30 30 32 20 20 2f 2a 20 4f 6b 20 66 6f 72  00002  /* Ok for
a900: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
a910: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
a920: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
a930: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
a940: 30 30 30 30 34 20 20 2f 2a 20 4f 6b 20 66 6f 72  00004  /* Ok for
a950: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
a960: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
a970: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
a980: 4f 4e 43 4c 4f 53 45 20 20 20 20 30 78 30 30 30  ONCLOSE    0x000
a990: 30 30 30 30 38 20 20 2f 2a 20 56 46 53 20 6f 6e  00008  /* VFS on
a9a0: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
a9b0: 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53  LITE_OPEN_EXCLUS
a9c0: 49 56 45 20 20 20 20 20 20 20 20 30 78 30 30 30  IVE        0x000
a9d0: 30 30 30 31 30 20 20 2f 2a 20 56 46 53 20 6f 6e  00010  /* VFS on
a9e0: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
a9f0: 4c 49 54 45 5f 4f 50 45 4e 5f 41 55 54 4f 50 52  LITE_OPEN_AUTOPR
aa00: 4f 58 59 20 20 20 20 20 20 20 20 30 78 30 30 30  OXY        0x000
aa10: 30 30 30 32 30 20 20 2f 2a 20 56 46 53 20 6f 6e  00020  /* VFS on
aa20: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
aa30: 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 20 20  LITE_OPEN_URI   
aa40: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
aa50: 30 30 30 34 30 20 20 2f 2a 20 4f 6b 20 66 6f 72  00040  /* Ok for
aa60: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
aa70: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
aa80: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 45 4d 4f 52 59  LITE_OPEN_MEMORY
aa90: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
aaa0: 30 30 30 38 30 20 20 2f 2a 20 4f 6b 20 66 6f 72  00080  /* Ok for
aab0: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
aac0: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
aad0: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44  LITE_OPEN_MAIN_D
aae0: 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30  B          0x000
aaf0: 30 30 31 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e  00100  /* VFS on
ab00: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
ab10: 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44  LITE_OPEN_TEMP_D
ab20: 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30  B          0x000
ab30: 30 30 32 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e  00200  /* VFS on
ab40: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
ab50: 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49  LITE_OPEN_TRANSI
ab60: 45 4e 54 5f 44 42 20 20 20 20 20 30 78 30 30 30  ENT_DB     0x000
ab70: 30 30 34 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e  00400  /* VFS on
ab80: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
ab90: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a  LITE_OPEN_MAIN_J
aba0: 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30  OURNAL     0x000
abb0: 30 30 38 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e  00800  /* VFS on
abc0: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
abd0: 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a  LITE_OPEN_TEMP_J
abe0: 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30  OURNAL     0x000
abf0: 30 31 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e  01000  /* VFS on
ac00: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
ac10: 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55  LITE_OPEN_SUBJOU
ac20: 52 4e 41 4c 20 20 20 20 20 20 20 30 78 30 30 30  RNAL       0x000
ac30: 30 32 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e  02000  /* VFS on
ac40: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
ac50: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52  LITE_OPEN_MASTER
ac60: 5f 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30 30 30  _JOURNAL   0x000
ac70: 30 34 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e  04000  /* VFS on
ac80: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
ac90: 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45  LITE_OPEN_NOMUTE
aca0: 58 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30  X          0x000
acb0: 30 38 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72  08000  /* Ok for
acc0: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
acd0: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
ace0: 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55  LITE_OPEN_FULLMU
acf0: 54 45 58 20 20 20 20 20 20 20 20 30 78 30 30 30  TEX        0x000
ad00: 31 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72  10000  /* Ok for
ad10: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
ad20: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
ad30: 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44  LITE_OPEN_SHARED
ad40: 43 41 43 48 45 20 20 20 20 20 20 30 78 30 30 30  CACHE      0x000
ad50: 32 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72  20000  /* Ok for
ad60: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
ad70: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
ad80: 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54  LITE_OPEN_PRIVAT
ad90: 45 43 41 43 48 45 20 20 20 20 20 30 78 30 30 30  ECACHE     0x000
ada0: 34 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72  40000  /* Ok for
adb0: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
adc0: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
add0: 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 20 20 20  LITE_OPEN_WAL   
ade0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
adf0: 38 30 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e  80000  /* VFS on
ae00: 6c 79 20 2a 2f 0a 0a 2f 2a 20 52 65 73 65 72 76  ly */../* Reserv
ae10: 65 64 3a 20 20 20 20 20 20 20 20 20 20 20 20 20  ed:             
ae20: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
ae30: 46 30 30 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  F00000 */../*.**
ae40: 20 43 41 50 49 33 52 45 46 3a 20 44 65 76 69 63   CAPI3REF: Devic
ae50: 65 20 43 68 61 72 61 63 74 65 72 69 73 74 69 63  e Characteristic
ae60: 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76  s.**.** The xDev
ae70: 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69  iceCharacteristi
ae80: 63 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65  cs method of the
ae90: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
aea0: 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20  hods].** object 
aeb0: 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67  returns an integ
aec0: 65 72 20 77 68 69 63 68 20 69 73 20 61 20 76 65  er which is a ve
aed0: 63 74 6f 72 20 6f 66 20 74 68 65 73 65 0a 2a 2a  ctor of these.**
aee0: 20 62 69 74 20 76 61 6c 75 65 73 20 65 78 70 72   bit values expr
aef0: 65 73 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 61  essing I/O chara
af00: 63 74 65 72 69 73 74 69 63 73 20 6f 66 20 74 68  cteristics of th
af10: 65 20 6d 61 73 73 20 73 74 6f 72 61 67 65 0a 2a  e mass storage.*
af20: 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 68 6f  * device that ho
af30: 6c 64 73 20 74 68 65 20 66 69 6c 65 20 74 68 61  lds the file tha
af40: 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69  t the [sqlite3_i
af50: 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65  o_methods].** re
af60: 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54  fers to..**.** T
af70: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
af80: 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20  ATOMIC property 
af90: 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77  means that all w
afa0: 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20  rites of.** any 
afb0: 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e  size are atomic.
afc0: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
afd0: 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c  AP_ATOMICnnn val
afe0: 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74  ues.** mean that
aff0: 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b   writes of block
b000: 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62  s that are nnn b
b010: 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64  ytes in size and
b020: 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20  .** are aligned 
b030: 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 68  to an address wh
b040: 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ich is an intege
b050: 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a  r multiple of.**
b060: 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e   nnn are atomic.
b070: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
b080: 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76  AP_SAFE_APPEND v
b090: 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68  alue means.** th
b0a0: 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 20  at when data is 
b0b0: 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69  appended to a fi
b0c0: 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 20  le, the data is 
b0d0: 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73  appended.** firs
b0e0: 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20  t then the size 
b0f0: 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 65  of the file is e
b100: 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74  xtended, never t
b110: 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20  he other.** way 
b120: 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c  around.  The SQL
b130: 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e  ITE_IOCAP_SEQUEN
b140: 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65  TIAL property me
b150: 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f  ans that.** info
b160: 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74  rmation is writt
b170: 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68  en to disk in th
b180: 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20  e same order as 
b190: 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69  calls.** to xWri
b1a0: 74 65 28 29 2e 20 20 54 68 65 20 53 51 4c 49 54  te().  The SQLIT
b1b0: 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46  E_IOCAP_POWERSAF
b1c0: 45 5f 4f 56 45 52 57 52 49 54 45 20 70 72 6f 70  E_OVERWRITE prop
b1d0: 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a  erty means that.
b1e0: 2a 2a 20 61 66 74 65 72 20 72 65 62 6f 6f 74 20  ** after reboot 
b1f0: 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 72 61 73  following a cras
b200: 68 20 6f 72 20 70 6f 77 65 72 20 6c 6f 73 73 2c  h or power loss,
b210: 20 74 68 65 20 6f 6e 6c 79 20 62 79 74 65 73 20   the only bytes 
b220: 69 6e 20 61 0a 2a 2a 20 66 69 6c 65 20 74 68 61  in a.** file tha
b230: 74 20 77 65 72 65 20 77 72 69 74 74 65 6e 20 61  t were written a
b240: 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  t the applicatio
b250: 6e 20 6c 65 76 65 6c 20 6d 69 67 68 74 20 68 61  n level might ha
b260: 76 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 61 6e  ve changed.** an
b270: 64 20 74 68 61 74 20 61 64 6a 61 63 65 6e 74 20  d that adjacent 
b280: 62 79 74 65 73 2c 20 65 76 65 6e 20 62 79 74 65  bytes, even byte
b290: 73 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d  s within the sam
b2a0: 65 20 73 65 63 74 6f 72 20 61 72 65 0a 2a 2a 20  e sector are.** 
b2b0: 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65  guaranteed to be
b2c0: 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2f 0a 23   unchanged..*/.#
b2d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
b2e0: 43 41 50 5f 41 54 4f 4d 49 43 20 20 20 20 20 20  CAP_ATOMIC      
b2f0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
b300: 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53 51  00001.#define SQ
b310: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
b320: 43 35 31 32 20 20 20 20 20 20 20 20 20 20 20 20  C512            
b330: 20 20 30 78 30 30 30 30 30 30 30 32 0a 23 64 65    0x00000002.#de
b340: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
b350: 50 5f 41 54 4f 4d 49 43 31 4b 20 20 20 20 20 20  P_ATOMIC1K      
b360: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
b370: 30 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  004.#define SQLI
b380: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32  TE_IOCAP_ATOMIC2
b390: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  K               
b3a0: 30 78 30 30 30 30 30 30 30 38 0a 23 64 65 66 69  0x00000008.#defi
b3b0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
b3c0: 41 54 4f 4d 49 43 34 4b 20 20 20 20 20 20 20 20  ATOMIC4K        
b3d0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31         0x0000001
b3e0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
b3f0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20  _IOCAP_ATOMIC8K 
b400: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
b410: 30 30 30 30 30 30 32 30 0a 23 64 65 66 69 6e 65  00000020.#define
b420: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
b430: 4f 4d 49 43 31 36 4b 20 20 20 20 20 20 20 20 20  OMIC16K         
b440: 20 20 20 20 20 30 78 30 30 30 30 30 30 34 30 0a       0x00000040.
b450: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
b460: 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20  OCAP_ATOMIC32K  
b470: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
b480: 30 30 30 30 38 30 0a 23 64 65 66 69 6e 65 20 53  000080.#define S
b490: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
b4a0: 49 43 36 34 4b 20 20 20 20 20 20 20 20 20 20 20  IC64K           
b4b0: 20 20 20 30 78 30 30 30 30 30 31 30 30 0a 23 64     0x00000100.#d
b4c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
b4d0: 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 20  AP_SAFE_APPEND  
b4e0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
b4f0: 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0200.#define SQL
b500: 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e  ITE_IOCAP_SEQUEN
b510: 54 49 41 4c 20 20 20 20 20 20 20 20 20 20 20 20  TIAL            
b520: 20 30 78 30 30 30 30 30 34 30 30 0a 23 64 65 66   0x00000400.#def
b530: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
b540: 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45  _UNDELETABLE_WHE
b550: 4e 5f 4f 50 45 4e 20 20 30 78 30 30 30 30 30 38  N_OPEN  0x000008
b560: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  00.#define SQLIT
b570: 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46  E_IOCAP_POWERSAF
b580: 45 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20 30  E_OVERWRITE    0
b590: 78 30 30 30 30 31 30 30 30 0a 0a 2f 2a 0a 2a 2a  x00001000../*.**
b5a0: 20 43 41 50 49 33 52 45 46 3a 20 46 69 6c 65 20   CAPI3REF: File 
b5b0: 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a 2a  Locking Levels.*
b5c0: 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73  *.** SQLite uses
b5d0: 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e   one of these in
b5e0: 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 20  teger values as 
b5f0: 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72  the second.** ar
b600: 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20  gument to calls 
b610: 69 74 20 6d 61 6b 65 73 20 74 6f 20 74 68 65 20  it makes to the 
b620: 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c  xLock() and xUnl
b630: 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a  ock() methods.**
b640: 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   of an [sqlite3_
b650: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
b660: 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ct..*/.#define S
b670: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20  QLITE_LOCK_NONE 
b680: 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69           0.#defi
b690: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53  ne SQLITE_LOCK_S
b6a0: 48 41 52 45 44 20 20 20 20 20 20 20 20 31 0a 23  HARED        1.#
b6b0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
b6c0: 43 4b 5f 52 45 53 45 52 56 45 44 20 20 20 20 20  CK_RESERVED     
b6d0: 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
b6e0: 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20  E_LOCK_PENDING  
b6f0: 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53       3.#define S
b700: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55  QLITE_LOCK_EXCLU
b710: 53 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a  SIVE     4../*.*
b720: 2a 20 43 41 50 49 33 52 45 46 3a 20 53 79 6e 63  * CAPI3REF: Sync
b730: 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65  hronization Type
b740: 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65   Flags.**.** Whe
b750: 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73  n SQLite invokes
b760: 20 74 68 65 20 78 53 79 6e 63 28 29 20 6d 65 74   the xSync() met
b770: 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71  hod of an.** [sq
b780: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
b790: 5d 20 6f 62 6a 65 63 74 20 69 74 20 75 73 65 73  ] object it uses
b7a0: 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f   a combination o
b7b0: 66 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74 65 67  f.** these integ
b7c0: 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 65  er values as the
b7d0: 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
b7e0: 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65  ..**.** When the
b7f0: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54   SQLITE_SYNC_DAT
b800: 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20 75 73  AONLY flag is us
b810: 65 64 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61  ed, it means tha
b820: 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70  t the.** sync op
b830: 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65  eration only nee
b840: 64 73 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61  ds to flush data
b850: 20 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 67 65   to mass storage
b860: 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f  .  Inode.** info
b870: 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74  rmation need not
b880: 20 62 65 20 66 6c 75 73 68 65 64 2e 20 49 66 20   be flushed. If 
b890: 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62  the lower four b
b8a0: 69 74 73 20 6f 66 20 74 68 65 20 66 6c 61 67 0a  its of the flag.
b8b0: 2a 2a 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f  ** equal SQLITE_
b8c0: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61  SYNC_NORMAL, tha
b8d0: 74 20 6d 65 61 6e 73 20 74 6f 20 75 73 65 20 6e  t means to use n
b8e0: 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 20 73 65  ormal fsync() se
b8f0: 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74  mantics..** If t
b900: 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69  he lower four bi
b910: 74 73 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f  ts equal SQLITE_
b920: 53 59 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20  SYNC_FULL, that 
b930: 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20  means.** to use 
b940: 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66  Mac OS X style f
b950: 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61 64 20  ullsync instead 
b960: 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a  of fsync()..**.*
b970: 2a 20 44 6f 20 6e 6f 74 20 63 6f 6e 66 75 73 65  * Do not confuse
b980: 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43   the SQLITE_SYNC
b990: 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49  _NORMAL and SQLI
b9a0: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61  TE_SYNC_FULL fla
b9b0: 67 73 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b  gs.** with the [
b9c0: 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f  PRAGMA synchrono
b9d0: 75 73 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b  us]=NORMAL and [
b9e0: 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f  PRAGMA synchrono
b9f0: 75 73 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74 74  us]=FULL.** sett
ba00: 69 6e 67 73 2e 20 20 54 68 65 20 5b 73 79 6e 63  ings.  The [sync
ba10: 68 72 6f 6e 6f 75 73 20 70 72 61 67 6d 61 5d 20  hronous pragma] 
ba20: 64 65 74 65 72 6d 69 6e 65 73 20 77 68 65 6e 20  determines when 
ba30: 63 61 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20  calls to the.** 
ba40: 78 53 79 6e 63 20 56 46 53 20 6d 65 74 68 6f 64  xSync VFS method
ba50: 20 6f 63 63 75 72 20 61 6e 64 20 61 70 70 6c 69   occur and appli
ba60: 65 73 20 75 6e 69 66 6f 72 6d 6c 79 20 61 63 72  es uniformly acr
ba70: 6f 73 73 20 61 6c 6c 20 70 6c 61 74 66 6f 72 6d  oss all platform
ba80: 73 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  s..** The SQLITE
ba90: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64  _SYNC_NORMAL and
baa0: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c   SQLITE_SYNC_FUL
bab0: 4c 20 66 6c 61 67 73 20 64 65 74 65 72 6d 69 6e  L flags determin
bac0: 65 20 68 6f 77 0a 2a 2a 20 65 6e 65 72 67 65 74  e how.** energet
bad0: 69 63 20 6f 72 20 72 69 67 6f 72 6f 75 73 20 6f  ic or rigorous o
bae0: 72 20 66 6f 72 63 65 66 75 6c 20 74 68 65 20 73  r forceful the s
baf0: 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 73 20 61  ync operations a
bb00: 72 65 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d  re and.** only m
bb10: 61 6b 65 20 61 20 64 69 66 66 65 72 65 6e 63 65  ake a difference
bb20: 20 6f 6e 20 4d 61 63 20 4f 53 58 20 66 6f 72 20   on Mac OSX for 
bb30: 74 68 65 20 64 65 66 61 75 6c 74 20 53 51 4c 69  the default SQLi
bb40: 74 65 20 63 6f 64 65 2e 0a 2a 2a 20 28 54 68 69  te code..** (Thi
bb50: 72 64 2d 70 61 72 74 79 20 56 46 53 20 69 6d 70  rd-party VFS imp
bb60: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 69 67  lementations mig
bb70: 68 74 20 61 6c 73 6f 20 6d 61 6b 65 20 74 68 65  ht also make the
bb80: 20 64 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20   distinction.** 
bb90: 62 65 74 77 65 65 6e 20 53 51 4c 49 54 45 5f 53  between SQLITE_S
bba0: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53  YNC_NORMAL and S
bbb0: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c  QLITE_SYNC_FULL,
bbc0: 20 62 75 74 20 61 6d 6f 6e 67 20 74 68 65 0a 2a   but among the.*
bbd0: 2a 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  * operating syst
bbe0: 65 6d 73 20 6e 61 74 69 76 65 6c 79 20 73 75 70  ems natively sup
bbf0: 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74 65  ported by SQLite
bc00: 2c 20 6f 6e 6c 79 20 4d 61 63 20 4f 53 58 0a 2a  , only Mac OSX.*
bc10: 2a 20 63 61 72 65 73 20 61 62 6f 75 74 20 74 68  * cares about th
bc20: 65 20 64 69 66 66 65 72 65 6e 63 65 2e 29 0a 2a  e difference.).*
bc30: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
bc40: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20  _SYNC_NORMAL    
bc50: 20 20 20 20 30 78 30 30 30 30 32 0a 23 64 65 66      0x00002.#def
bc60: 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  ine SQLITE_SYNC_
bc70: 46 55 4c 4c 20 20 20 20 20 20 20 20 20 20 30 78  FULL          0x
bc80: 30 30 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51  00003.#define SQ
bc90: 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e  LITE_SYNC_DATAON
bca0: 4c 59 20 20 20 20 20 20 30 78 30 30 30 31 30 0a  LY      0x00010.
bcb0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
bcc0: 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70   OS Interface Op
bcd0: 65 6e 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a  en File Handle.*
bce0: 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33  *.** An [sqlite3
bcf0: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65  _file] object re
bd00: 70 72 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e  presents an open
bd10: 20 66 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a   file in the .**
bd20: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20   [sqlite3_vfs | 
bd30: 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79  OS interface lay
bd40: 65 72 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 6c  er].  Individual
bd50: 20 4f 53 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a   OS interface.**
bd60: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
bd70: 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f   will.** want to
bd80: 20 73 75 62 63 6c 61 73 73 20 74 68 69 73 20 6f   subclass this o
bd90: 62 6a 65 63 74 20 62 79 20 61 70 70 65 6e 64 69  bject by appendi
bda0: 6e 67 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69  ng additional fi
bdb0: 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69  elds.** for thei
bdc0: 72 20 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20  r own use.  The 
bdd0: 70 4d 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69  pMethods entry i
bde0: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
bdf0: 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f  n.** [sqlite3_io
be00: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
be10: 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65   that defines me
be20: 74 68 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72  thods for perfor
be30: 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72  ming.** I/O oper
be40: 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70  ations on the op
be50: 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65  en file..*/.type
be60: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
be70: 65 33 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f  e3_file sqlite3_
be80: 66 69 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c  file;.struct sql
be90: 69 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f  ite3_file {.  co
bea0: 6e 73 74 20 73 74 72 75 63 74 20 73 71 6c 69 74  nst struct sqlit
beb0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70  e3_io_methods *p
bec0: 4d 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74  Methods;  /* Met
bed0: 68 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e  hods for an open
bee0: 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a   file */.};../*.
bef0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20  ** CAPI3REF: OS 
bf00: 49 6e 74 65 72 66 61 63 65 20 46 69 6c 65 20 56  Interface File V
bf10: 69 72 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f  irtual Methods O
bf20: 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72  bject.**.** Ever
bf30: 79 20 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 79  y file opened by
bf40: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   the [sqlite3_vf
bf50: 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20  s.xOpen] method 
bf60: 70 6f 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20  populates an.** 
bf70: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f  [sqlite3_file] o
bf80: 62 6a 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20  bject (or, more 
bf90: 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63  commonly, a subc
bfa0: 6c 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b  lass of the.** [
bfb0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62  sqlite3_file] ob
bfc0: 6a 65 63 74 29 20 77 69 74 68 20 61 20 70 6f 69  ject) with a poi
bfd0: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
bfe0: 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
bff0: 63 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65  ct..** This obje
c000: 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 6d  ct defines the m
c010: 65 74 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70  ethods used to p
c020: 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f  erform various o
c030: 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61  perations.** aga
c040: 69 6e 73 74 20 74 68 65 20 6f 70 65 6e 20 66 69  inst the open fi
c050: 6c 65 20 72 65 70 72 65 73 65 6e 74 65 64 20 62  le represented b
c060: 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66  y the [sqlite3_f
c070: 69 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a  ile] object..**.
c080: 2a 2a 20 49 66 20 74 68 65 20 5b 73 71 6c 69 74  ** If the [sqlit
c090: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65  e3_vfs.xOpen] me
c0a0: 74 68 6f 64 20 73 65 74 73 20 74 68 65 20 73 71  thod sets the sq
c0b0: 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68  lite3_file.pMeth
c0c0: 6f 64 73 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20  ods element .** 
c0d0: 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f  to a non-NULL po
c0e0: 69 6e 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20  inter, then the 
c0f0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
c100: 64 73 2e 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64  ds.xClose method
c110: 0a 2a 2a 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b  .** may be invok
c120: 65 64 20 65 76 65 6e 20 69 66 20 74 68 65 20 5b  ed even if the [
c130: 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65  sqlite3_vfs.xOpe
c140: 6e 5d 20 72 65 70 6f 72 74 65 64 20 74 68 61 74  n] reported that
c150: 20 69 74 20 66 61 69 6c 65 64 2e 20 20 54 68 65   it failed.  The
c160: 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20  .** only way to 
c170: 70 72 65 76 65 6e 74 20 61 20 63 61 6c 6c 20 74  prevent a call t
c180: 6f 20 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69  o xClose followi
c190: 6e 67 20 61 20 66 61 69 6c 65 64 20 5b 73 71 6c  ng a failed [sql
c1a0: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a  ite3_vfs.xOpen].
c1b0: 2a 2a 20 69 73 20 66 6f 72 20 74 68 65 20 5b 73  ** is for the [s
c1c0: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
c1d0: 5d 20 74 6f 20 73 65 74 20 74 68 65 20 73 71 6c  ] to set the sql
c1e0: 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f  ite3_file.pMetho
c1f0: 64 73 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f  ds element.** to
c200: 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   NULL..**.** The
c210: 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20   flags argument 
c220: 74 6f 20 78 53 79 6e 63 20 6d 61 79 20 62 65 20  to xSync may be 
c230: 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53  one of [SQLITE_S
c240: 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a  YNC_NORMAL] or.*
c250: 2a 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  * [SQLITE_SYNC_F
c260: 55 4c 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 74  ULL].  The first
c270: 20 63 68 6f 69 63 65 20 69 73 20 74 68 65 20 6e   choice is the n
c280: 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a  ormal fsync()..*
c290: 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 63 68 6f  * The second cho
c2a0: 69 63 65 20 69 73 20 61 20 4d 61 63 20 4f 53 20  ice is a Mac OS 
c2b0: 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63  X style fullsync
c2c0: 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 53  .  The [SQLITE_S
c2d0: 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a  YNC_DATAONLY].**
c2e0: 20 66 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 65   flag may be ORe
c2f0: 64 20 69 6e 20 74 6f 20 69 6e 64 69 63 61 74 65  d in to indicate
c300: 20 74 68 61 74 20 6f 6e 6c 79 20 74 68 65 20 64   that only the d
c310: 61 74 61 20 6f 66 20 74 68 65 20 66 69 6c 65 0a  ata of the file.
c320: 2a 2a 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 69  ** and not its i
c330: 6e 6f 64 65 20 6e 65 65 64 73 20 74 6f 20 62 65  node needs to be
c340: 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54   synced..**.** T
c350: 68 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65  he integer value
c360: 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64  s to xLock() and
c370: 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f   xUnlock() are o
c380: 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  ne of.** <ul>.**
c390: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f   <li> [SQLITE_LO
c3a0: 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69  CK_NONE],.** <li
c3b0: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53  > [SQLITE_LOCK_S
c3c0: 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20  HARED],.** <li> 
c3d0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53  [SQLITE_LOCK_RES
c3e0: 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20  ERVED],.** <li> 
c3f0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e  [SQLITE_LOCK_PEN
c400: 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69  DING], or.** <li
c410: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45  > [SQLITE_LOCK_E
c420: 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f  XCLUSIVE]..** </
c430: 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69  ul>.** xLock() i
c440: 6e 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63  ncreases the loc
c450: 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63  k. xUnlock() dec
c460: 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e  reases the lock.
c470: 0a 2a 2a 20 54 68 65 20 78 43 68 65 63 6b 52 65  .** The xCheckRe
c480: 73 65 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74  servedLock() met
c490: 68 6f 64 20 63 68 65 63 6b 73 20 77 68 65 74 68  hod checks wheth
c4a0: 65 72 20 61 6e 79 20 64 61 74 61 62 61 73 65 20  er any database 
c4b0: 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65  connection,.** e
c4c0: 69 74 68 65 72 20 69 6e 20 74 68 69 73 20 70 72  ither in this pr
c4d0: 6f 63 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65  ocess or in some
c4e0: 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 2c 20   other process, 
c4f0: 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 52 45 53  is holding a RES
c500: 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e  ERVED,.** PENDIN
c510: 47 2c 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20  G, or EXCLUSIVE 
c520: 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65  lock on the file
c530: 2e 20 20 49 74 20 72 65 74 75 72 6e 73 20 74 72  .  It returns tr
c540: 75 65 0a 2a 2a 20 69 66 20 73 75 63 68 20 61 20  ue.** if such a 
c550: 6c 6f 63 6b 20 65 78 69 73 74 73 20 61 6e 64 20  lock exists and 
c560: 66 61 6c 73 65 20 6f 74 68 65 72 77 69 73 65 2e  false otherwise.
c570: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65  .**.** The xFile
c580: 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64  Control() method
c590: 20 69 73 20 61 20 67 65 6e 65 72 69 63 20 69 6e   is a generic in
c5a0: 74 65 72 66 61 63 65 20 74 68 61 74 20 61 6c 6c  terface that all
c5b0: 6f 77 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46  ows custom.** VF
c5c0: 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
c5d0: 73 20 74 6f 20 64 69 72 65 63 74 6c 79 20 63 6f  s to directly co
c5e0: 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69  ntrol an open fi
c5f0: 6c 65 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  le using the.** 
c600: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
c610: 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61  ntrol()] interfa
c620: 63 65 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20  ce.  The second 
c630: 22 6f 70 22 20 61 72 67 75 6d 65 6e 74 20 69 73  "op" argument is
c640: 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f   an.** integer o
c650: 70 63 6f 64 65 2e 20 20 54 68 65 20 74 68 69 72  pcode.  The thir
c660: 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  d argument is a 
c670: 67 65 6e 65 72 69 63 20 70 6f 69 6e 74 65 72 20  generic pointer 
c680: 69 6e 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70  intended to.** p
c690: 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 75 63 74  oint to a struct
c6a0: 75 72 65 20 74 68 61 74 20 6d 61 79 20 63 6f 6e  ure that may con
c6b0: 74 61 69 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f  tain arguments o
c6c0: 72 20 73 70 61 63 65 20 69 6e 20 77 68 69 63 68  r space in which
c6d0: 20 74 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65 74   to.** write ret
c6e0: 75 72 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f 74  urn values.  Pot
c6f0: 65 6e 74 69 61 6c 20 75 73 65 73 20 66 6f 72 20  ential uses for 
c700: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d  xFileControl() m
c710: 69 67 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74  ight be.** funct
c720: 69 6f 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20 62  ions to enable b
c730: 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69  locking locks wi
c740: 74 68 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20  th timeouts, to 
c750: 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f  change the.** lo
c760: 63 6b 69 6e 67 20 73 74 72 61 74 65 67 79 20 28  cking strategy (
c770: 66 6f 72 20 65 78 61 6d 70 6c 65 20 74 6f 20 75  for example to u
c780: 73 65 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b  se dot-file lock
c790: 73 29 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a  s), to inquire.*
c7a0: 2a 20 61 62 6f 75 74 20 74 68 65 20 73 74 61 74  * about the stat
c7b0: 75 73 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72  us of a lock, or
c7c0: 20 74 6f 20 62 72 65 61 6b 20 73 74 61 6c 65 20   to break stale 
c7d0: 6c 6f 63 6b 73 2e 20 20 54 68 65 20 53 51 4c 69  locks.  The SQLi
c7e0: 74 65 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65 72  te.** core reser
c7f0: 76 65 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20  ves all opcodes 
c800: 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20 66 6f  less than 100 fo
c810: 72 20 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a  r its own use..*
c820: 2a 20 41 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  * A [SQLITE_FCNT
c830: 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 7c 20 6c 69  L_LOCKSTATE | li
c840: 73 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c  st of opcodes] l
c850: 65 73 73 20 74 68 61 6e 20 31 30 30 20 69 73 20  ess than 100 is 
c860: 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70  available..** Ap
c870: 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20  plications that 
c880: 64 65 66 69 6e 65 20 61 20 63 75 73 74 6f 6d 20  define a custom 
c890: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74  xFileControl met
c8a0: 68 6f 64 20 73 68 6f 75 6c 64 20 75 73 65 20 6f  hod should use o
c8b0: 70 63 6f 64 65 73 0a 2a 2a 20 67 72 65 61 74 65  pcodes.** greate
c8c0: 72 20 74 68 61 6e 20 31 30 30 20 74 6f 20 61 76  r than 100 to av
c8d0: 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e 20 20  oid conflicts.  
c8e0: 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  VFS implementati
c8f0: 6f 6e 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65  ons should.** re
c900: 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 54  turn [SQLITE_NOT
c910: 46 4f 55 4e 44 5d 20 66 6f 72 20 66 69 6c 65 20  FOUND] for file 
c920: 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20  control opcodes 
c930: 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74  that they do not
c940: 0a 2a 2a 20 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a  .** recognize..*
c950: 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63 74 6f 72  *.** The xSector
c960: 53 69 7a 65 28 29 20 6d 65 74 68 6f 64 20 72 65  Size() method re
c970: 74 75 72 6e 73 20 74 68 65 20 73 65 63 74 6f 72  turns the sector
c980: 20 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20   size of the.** 
c990: 64 65 76 69 63 65 20 74 68 61 74 20 75 6e 64 65  device that unde
c9a0: 72 6c 69 65 73 20 74 68 65 20 66 69 6c 65 2e 20  rlies the file. 
c9b0: 20 54 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65   The sector size
c9c0: 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d   is the.** minim
c9d0: 75 6d 20 77 72 69 74 65 20 74 68 61 74 20 63 61  um write that ca
c9e0: 6e 20 62 65 20 70 65 72 66 6f 72 6d 65 64 20 77  n be performed w
c9f0: 69 74 68 6f 75 74 20 64 69 73 74 75 72 62 69 6e  ithout disturbin
ca00: 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74 65 73  g.** other bytes
ca10: 20 69 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 54   in the file.  T
ca20: 68 65 20 78 44 65 76 69 63 65 43 68 61 72 61 63  he xDeviceCharac
ca30: 74 65 72 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d  teristics().** m
ca40: 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20  ethod returns a 
ca50: 62 69 74 20 76 65 63 74 6f 72 20 64 65 73 63 72  bit vector descr
ca60: 69 62 69 6e 67 20 62 65 68 61 76 69 6f 72 73 20  ibing behaviors 
ca70: 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c  of the.** underl
ca80: 79 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a  ying device:.**.
ca90: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
caa0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
cab0: 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  OMIC].** <li> [S
cac0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
cad0: 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  IC512].** <li> [
cae0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
caf0: 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  MIC1K].** <li> [
cb00: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
cb10: 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  MIC2K].** <li> [
cb20: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
cb30: 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  MIC4K].** <li> [
cb40: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
cb50: 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  MIC8K].** <li> [
cb60: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
cb70: 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  MIC16K].** <li> 
cb80: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
cb90: 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e  OMIC32K].** <li>
cba0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
cbb0: 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69  TOMIC64K].** <li
cbc0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
cbd0: 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20  SAFE_APPEND].** 
cbe0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
cbf0: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a  AP_SEQUENTIAL].*
cc00: 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68  * </ul>.**.** Th
cc10: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
cc20: 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d  TOMIC property m
cc30: 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72  eans that all wr
cc40: 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73  ites of.** any s
cc50: 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20  ize are atomic. 
cc60: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
cc70: 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75  P_ATOMICnnn valu
cc80: 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20  es.** mean that 
cc90: 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73  writes of blocks
cca0: 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79   that are nnn by
ccb0: 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a  tes in size and.
ccc0: 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74  ** are aligned t
ccd0: 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69  o an address whi
cce0: 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  ch is an integer
ccf0: 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20   multiple of.** 
cd00: 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20  nnn are atomic. 
cd10: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
cd20: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61  P_SAFE_APPEND va
cd30: 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61  lue means.** tha
cd40: 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61  t when data is a
cd50: 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c  ppended to a fil
cd60: 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61  e, the data is a
cd70: 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74  ppended.** first
cd80: 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f   then the size o
cd90: 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78  f the file is ex
cda0: 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68  tended, never th
cdb0: 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61  e other.** way a
cdc0: 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49  round.  The SQLI
cdd0: 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54  TE_IOCAP_SEQUENT
cde0: 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61  IAL property mea
cdf0: 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72  ns that.** infor
ce00: 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65  mation is writte
ce10: 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65  n to disk in the
ce20: 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63   same order as c
ce30: 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74  alls.** to xWrit
ce40: 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52  e()..**.** If xR
ce50: 65 61 64 28 29 20 72 65 74 75 72 6e 73 20 53 51  ead() returns SQ
ce60: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54  LITE_IOERR_SHORT
ce70: 5f 52 45 41 44 20 69 74 20 6d 75 73 74 20 61 6c  _READ it must al
ce80: 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68  so fill.** in th
ce90: 65 20 75 6e 72 65 61 64 20 70 6f 72 74 69 6f 6e  e unread portion
cea0: 73 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 20  s of the buffer 
ceb0: 77 69 74 68 20 7a 65 72 6f 73 2e 20 20 41 20 56  with zeros.  A V
cec0: 46 53 20 74 68 61 74 0a 2a 2a 20 66 61 69 6c 73  FS that.** fails
ced0: 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68   to zero-fill sh
cee0: 6f 72 74 20 72 65 61 64 73 20 6d 69 67 68 74 20  ort reads might 
cef0: 73 65 65 6d 20 74 6f 20 77 6f 72 6b 2e 20 20 48  seem to work.  H
cf00: 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 61 69 6c 75  owever,.** failu
cf10: 72 65 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20  re to zero-fill 
cf20: 73 68 6f 72 74 20 72 65 61 64 73 20 77 69 6c 6c  short reads will
cf30: 20 65 76 65 6e 74 75 61 6c 6c 79 20 6c 65 61 64   eventually lead
cf40: 20 74 6f 0a 2a 2a 20 64 61 74 61 62 61 73 65 20   to.** database 
cf50: 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74  corruption..*/.t
cf60: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
cf70: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
cf80: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68   sqlite3_io_meth
cf90: 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69  ods;.struct sqli
cfa0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 7b  te3_io_methods {
cfb0: 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b  .  int iVersion;
cfc0: 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29  .  int (*xClose)
cfd0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b  (sqlite3_file*);
cfe0: 0a 20 20 69 6e 74 20 28 2a 78 52 65 61 64 29 28  .  int (*xRead)(
cff0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 76  sqlite3_file*, v
d000: 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20  oid*, int iAmt, 
d010: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f  sqlite3_int64 iO
d020: 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 57  fst);.  int (*xW
d030: 72 69 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69  rite)(sqlite3_fi
d040: 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  le*, const void*
d050: 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69  , int iAmt, sqli
d060: 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29  te3_int64 iOfst)
d070: 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72 75 6e 63  ;.  int (*xTrunc
d080: 61 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ate)(sqlite3_fil
d090: 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  e*, sqlite3_int6
d0a0: 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28  4 size);.  int (
d0b0: 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f  *xSync)(sqlite3_
d0c0: 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c 61 67 73  file*, int flags
d0d0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65  );.  int (*xFile
d0e0: 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69  Size)(sqlite3_fi
d0f0: 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  le*, sqlite3_int
d100: 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20 20 69 6e  64 *pSize);.  in
d110: 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71 6c 69 74  t (*xLock)(sqlit
d120: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a  e3_file*, int);.
d130: 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b 29    int (*xUnlock)
d140: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
d150: 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43  int);.  int (*xC
d160: 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b  heckReservedLock
d170: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
d180: 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a   int *pResOut);.
d190: 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 43 6f 6e    int (*xFileCon
d1a0: 74 72 6f 6c 29 28 73 71 6c 69 74 65 33 5f 66 69  trol)(sqlite3_fi
d1b0: 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69  le*, int op, voi
d1c0: 64 20 2a 70 41 72 67 29 3b 0a 20 20 69 6e 74 20  d *pArg);.  int 
d1d0: 28 2a 78 53 65 63 74 6f 72 53 69 7a 65 29 28 73  (*xSectorSize)(s
d1e0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20  qlite3_file*);. 
d1f0: 20 69 6e 74 20 28 2a 78 44 65 76 69 63 65 43 68   int (*xDeviceCh
d200: 61 72 61 63 74 65 72 69 73 74 69 63 73 29 28 73  aracteristics)(s
d210: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20  qlite3_file*);. 
d220: 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76   /* Methods abov
d230: 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20  e are valid for 
d240: 76 65 72 73 69 6f 6e 20 31 20 2a 2f 0a 20 20 69  version 1 */.  i
d250: 6e 74 20 28 2a 78 53 68 6d 4d 61 70 29 28 73 71  nt (*xShmMap)(sq
d260: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
d270: 20 69 50 67 2c 20 69 6e 74 20 70 67 73 7a 2c 20   iPg, int pgsz, 
d280: 69 6e 74 2c 20 76 6f 69 64 20 76 6f 6c 61 74 69  int, void volati
d290: 6c 65 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  le**);.  int (*x
d2a0: 53 68 6d 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33  ShmLock)(sqlite3
d2b0: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 66 66 73  _file*, int offs
d2c0: 65 74 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20 66  et, int n, int f
d2d0: 6c 61 67 73 29 3b 0a 20 20 76 6f 69 64 20 28 2a  lags);.  void (*
d2e0: 78 53 68 6d 42 61 72 72 69 65 72 29 28 73 71 6c  xShmBarrier)(sql
d2f0: 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69  ite3_file*);.  i
d300: 6e 74 20 28 2a 78 53 68 6d 55 6e 6d 61 70 29 28  nt (*xShmUnmap)(
d310: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
d320: 6e 74 20 64 65 6c 65 74 65 46 6c 61 67 29 3b 0a  nt deleteFlag);.
d330: 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f    /* Methods abo
d340: 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72  ve are valid for
d350: 20 76 65 72 73 69 6f 6e 20 32 20 2a 2f 0a 20 20   version 2 */.  
d360: 69 6e 74 20 28 2a 78 46 65 74 63 68 29 28 73 71  int (*xFetch)(sq
d370: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c  lite3_file*, sql
d380: 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74  ite3_int64 iOfst
d390: 2c 20 69 6e 74 20 69 41 6d 74 2c 20 76 6f 69 64  , int iAmt, void
d3a0: 20 2a 2a 70 70 29 3b 0a 20 20 69 6e 74 20 28 2a   **pp);.  int (*
d3b0: 78 55 6e 66 65 74 63 68 29 28 73 71 6c 69 74 65  xUnfetch)(sqlite
d3c0: 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33  3_file*, sqlite3
d3d0: 5f 69 6e 74 36 34 20 69 4f 66 73 74 2c 20 76 6f  _int64 iOfst, vo
d3e0: 69 64 20 2a 70 29 3b 0a 20 20 2f 2a 20 4d 65 74  id *p);.  /* Met
d3f0: 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 76  hods above are v
d400: 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e  alid for version
d410: 20 33 20 2a 2f 0a 20 20 2f 2a 20 41 64 64 69 74   3 */.  /* Addit
d420: 69 6f 6e 61 6c 20 6d 65 74 68 6f 64 73 20 6d 61  ional methods ma
d430: 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75  y be added in fu
d440: 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 2a 2f  ture releases */
d450: 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .};../*.** CAPI3
d460: 52 45 46 3a 20 53 74 61 6e 64 61 72 64 20 46 69  REF: Standard Fi
d470: 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64  le Control Opcod
d480: 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69  es.**.** These i
d490: 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73  nteger constants
d4a0: 20 61 72 65 20 6f 70 63 6f 64 65 73 20 66 6f 72   are opcodes for
d4b0: 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f   the xFileContro
d4c0: 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74  l method.** of t
d4d0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  he [sqlite3_io_m
d4e0: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 61  ethods] object a
d4f0: 6e 64 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69  nd for the [sqli
d500: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
d510: 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  ()].** interface
d520: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ..**.** The [SQL
d530: 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54  ITE_FCNTL_LOCKST
d540: 41 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75  ATE] opcode is u
d550: 73 65 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e  sed for debuggin
d560: 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f  g.  This.** opco
d570: 64 65 20 63 61 75 73 65 73 20 74 68 65 20 78 46  de causes the xF
d580: 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f  ileControl metho
d590: 64 20 74 6f 20 77 72 69 74 65 20 74 68 65 20 63  d to write the c
d5a0: 75 72 72 65 6e 74 20 73 74 61 74 65 20 6f 66 0a  urrent state of.
d5b0: 2a 2a 20 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65  ** the lock (one
d5c0: 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b   of [SQLITE_LOCK
d5d0: 5f 4e 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f  _NONE], [SQLITE_
d5e0: 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a  LOCK_SHARED],.**
d5f0: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45   [SQLITE_LOCK_RE
d600: 53 45 52 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45  SERVED], [SQLITE
d610: 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20  _LOCK_PENDING], 
d620: 6f 72 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  or [SQLITE_LOCK_
d630: 45 58 43 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69  EXCLUSIVE]).** i
d640: 6e 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 74  nto an integer t
d650: 68 61 74 20 74 68 65 20 70 41 72 67 20 61 72 67  hat the pArg arg
d660: 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e  ument points to.
d670: 20 54 68 69 73 20 63 61 70 61 62 69 6c 69 74 79   This capability
d680: 0a 2a 2a 20 69 73 20 75 73 65 64 20 64 75 72 69  .** is used duri
d690: 6e 67 20 74 65 73 74 69 6e 67 20 61 6e 64 20 6f  ng testing and o
d6a0: 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 62 65 20  nly needs to be 
d6b0: 73 75 70 70 6f 72 74 65 64 20 77 68 65 6e 20 53  supported when S
d6c0: 51 4c 49 54 45 5f 54 45 53 54 0a 2a 2a 20 69 73  QLITE_TEST.** is
d6d0: 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 3c 75 6c   defined..** <ul
d6e0: 3e 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  >.** <li>[[SQLIT
d6f0: 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e  E_FCNTL_SIZE_HIN
d700: 54 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  T]].** The [SQLI
d710: 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49  TE_FCNTL_SIZE_HI
d720: 4e 54 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  NT] opcode is us
d730: 65 64 20 62 79 20 53 51 4c 69 74 65 20 74 6f 20  ed by SQLite to 
d740: 67 69 76 65 20 74 68 65 20 56 46 53 0a 2a 2a 20  give the VFS.** 
d750: 6c 61 79 65 72 20 61 20 68 69 6e 74 20 6f 66 20  layer a hint of 
d760: 68 6f 77 20 6c 61 72 67 65 20 74 68 65 20 64 61  how large the da
d770: 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c  tabase file will
d780: 20 67 72 6f 77 20 74 6f 20 62 65 20 64 75 72 69   grow to be duri
d790: 6e 67 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e  ng the.** curren
d7a0: 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 20  t transaction.  
d7b0: 54 68 69 73 20 68 69 6e 74 20 69 73 20 6e 6f 74  This hint is not
d7c0: 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62   guaranteed to b
d7d0: 65 20 61 63 63 75 72 61 74 65 20 62 75 74 20 69  e accurate but i
d7e0: 74 0a 2a 2a 20 69 73 20 6f 66 74 65 6e 20 63 6c  t.** is often cl
d7f0: 6f 73 65 2e 20 20 54 68 65 20 75 6e 64 65 72 6c  ose.  The underl
d800: 79 69 6e 67 20 56 46 53 20 6d 69 67 68 74 20 63  ying VFS might c
d810: 68 6f 6f 73 65 20 74 6f 20 70 72 65 61 6c 6c 6f  hoose to preallo
d820: 63 61 74 65 20 64 61 74 61 62 61 73 65 0a 2a 2a  cate database.**
d830: 20 66 69 6c 65 20 73 70 61 63 65 20 62 61 73 65   file space base
d840: 64 20 6f 6e 20 74 68 69 73 20 68 69 6e 74 20 69  d on this hint i
d850: 6e 20 6f 72 64 65 72 20 74 6f 20 68 65 6c 70 20  n order to help 
d860: 77 72 69 74 65 73 20 74 6f 20 74 68 65 20 64 61  writes to the da
d870: 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 72  tabase.** file r
d880: 75 6e 20 66 61 73 74 65 72 2e 0a 2a 2a 0a 2a 2a  un faster..**.**
d890: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
d8a0: 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 5d  NTL_CHUNK_SIZE]]
d8b0: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
d8c0: 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45  FCNTL_CHUNK_SIZE
d8d0: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
d8e0: 20 74 6f 20 72 65 71 75 65 73 74 20 74 68 61 74   to request that
d8f0: 20 74 68 65 20 56 46 53 0a 2a 2a 20 65 78 74 65   the VFS.** exte
d900: 6e 64 73 20 61 6e 64 20 74 72 75 6e 63 61 74 65  nds and truncate
d910: 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  s the database f
d920: 69 6c 65 20 69 6e 20 63 68 75 6e 6b 73 20 6f 66  ile in chunks of
d930: 20 61 20 73 69 7a 65 20 73 70 65 63 69 66 69 65   a size specifie
d940: 64 0a 2a 2a 20 62 79 20 74 68 65 20 75 73 65 72  d.** by the user
d950: 2e 20 54 68 65 20 66 6f 75 72 74 68 20 61 72 67  . The fourth arg
d960: 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65  ument to [sqlite
d970: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
d980: 5d 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 70 6f 69  ] should .** poi
d990: 6e 74 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  nt to an integer
d9a0: 20 28 74 79 70 65 20 69 6e 74 29 20 63 6f 6e 74   (type int) cont
d9b0: 61 69 6e 69 6e 67 20 74 68 65 20 6e 65 77 20 63  aining the new c
d9c0: 68 75 6e 6b 2d 73 69 7a 65 20 74 6f 20 75 73 65  hunk-size to use
d9d0: 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6e 6f 6d 69  .** for the nomi
d9e0: 6e 61 74 65 64 20 64 61 74 61 62 61 73 65 2e 20  nated database. 
d9f0: 41 6c 6c 6f 63 61 74 69 6e 67 20 64 61 74 61 62  Allocating datab
da00: 61 73 65 20 66 69 6c 65 20 73 70 61 63 65 20 69  ase file space i
da10: 6e 20 6c 61 72 67 65 0a 2a 2a 20 63 68 75 6e 6b  n large.** chunk
da20: 73 20 28 73 61 79 20 31 4d 42 20 61 74 20 61 20  s (say 1MB at a 
da30: 74 69 6d 65 29 2c 20 6d 61 79 20 72 65 64 75 63  time), may reduc
da40: 65 20 66 69 6c 65 2d 73 79 73 74 65 6d 20 66 72  e file-system fr
da50: 61 67 6d 65 6e 74 61 74 69 6f 6e 20 61 6e 64 0a  agmentation and.
da60: 2a 2a 20 69 6d 70 72 6f 76 65 20 70 65 72 66 6f  ** improve perfo
da70: 72 6d 61 6e 63 65 20 6f 6e 20 73 6f 6d 65 20 73  rmance on some s
da80: 79 73 74 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  ystems..**.** <l
da90: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
daa0: 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 5d 0a  _FILE_POINTER]].
dab0: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
dac0: 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45  CNTL_FILE_POINTE
dad0: 52 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  R] opcode is use
dae0: 64 20 74 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f  d to obtain a po
daf0: 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  inter.** to the 
db00: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f  [sqlite3_file] o
db10: 62 6a 65 63 74 20 61 73 73 6f 63 69 61 74 65 64  bject associated
db20: 20 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c   with a particul
db30: 61 72 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  ar database.** c
db40: 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 53 65 65 20  onnection.  See 
db50: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  the [sqlite3_fil
db60: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 64 6f 63  e_control()] doc
db70: 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a  umentation for.*
db80: 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66  * additional inf
db90: 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  ormation..**.** 
dba0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
dbb0: 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 5d  TL_SYNC_OMITTED]
dbc0: 5d 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c 49  ].** ^(The [SQLI
dbd0: 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d  TE_FCNTL_SYNC_OM
dbe0: 49 54 54 45 44 5d 20 6f 70 63 6f 64 65 20 69 73  ITTED] opcode is
dbf0: 20 67 65 6e 65 72 61 74 65 64 20 69 6e 74 65 72   generated inter
dc00: 6e 61 6c 6c 79 20 62 79 0a 2a 2a 20 53 51 4c 69  nally by.** SQLi
dc10: 74 65 20 61 6e 64 20 73 65 6e 74 20 74 6f 20 61  te and sent to a
dc20: 6c 6c 20 56 46 53 65 73 20 69 6e 20 70 6c 61 63  ll VFSes in plac
dc30: 65 20 6f 66 20 61 20 63 61 6c 6c 20 74 6f 20 74  e of a call to t
dc40: 68 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 0a  he xSync method.
dc50: 2a 2a 20 77 68 65 6e 20 74 68 65 20 64 61 74 61  ** when the data
dc60: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
dc70: 68 61 73 20 5b 50 52 41 47 4d 41 20 73 79 6e 63  has [PRAGMA sync
dc80: 68 72 6f 6e 6f 75 73 5d 20 73 65 74 20 74 6f 20  hronous] set to 
dc90: 4f 46 46 2e 29 5e 0a 2a 2a 20 53 6f 6d 65 20 73  OFF.)^.** Some s
dca0: 70 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65 73  pecialized VFSes
dcb0: 20 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e 61   need this signa
dcc0: 6c 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 6f 70  l in order to op
dcd0: 65 72 61 74 65 20 63 6f 72 72 65 63 74 6c 79 0a  erate correctly.
dce0: 2a 2a 20 77 68 65 6e 20 5b 50 52 41 47 4d 41 20  ** when [PRAGMA 
dcf0: 73 79 6e 63 68 72 6f 6e 6f 75 73 20 7c 20 50 52  synchronous | PR
dd00: 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73  AGMA synchronous
dd10: 3d 4f 46 46 5d 20 69 73 20 73 65 74 2c 20 62 75  =OFF] is set, bu
dd20: 74 20 6d 6f 73 74 20 0a 2a 2a 20 56 46 53 65 73  t most .** VFSes
dd30: 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 68 69   do not need thi
dd40: 73 20 73 69 67 6e 61 6c 20 61 6e 64 20 73 68 6f  s signal and sho
dd50: 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e  uld silently ign
dd60: 6f 72 65 20 74 68 69 73 20 6f 70 63 6f 64 65 2e  ore this opcode.
dd70: 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  .** Applications
dd80: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c   should not call
dd90: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
dda0: 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 20 74  ontrol()] with t
ddb0: 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 61 73  his.** opcode as
ddc0: 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20 64 69   doing so may di
ddd0: 73 72 75 70 74 20 74 68 65 20 6f 70 65 72 61 74  srupt the operat
dde0: 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 65 63 69  ion of the speci
ddf0: 61 6c 69 7a 65 64 20 56 46 53 65 73 0a 2a 2a 20  alized VFSes.** 
de00: 74 68 61 74 20 64 6f 20 72 65 71 75 69 72 65 20  that do require 
de10: 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  it.  .**.** <li>
de20: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57  [[SQLITE_FCNTL_W
de30: 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d 5d 0a  IN32_AV_RETRY]].
de40: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
de50: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52  FCNTL_WIN32_AV_R
de60: 45 54 52 59 5d 20 6f 70 63 6f 64 65 20 69 73 20  ETRY] opcode is 
de70: 75 73 65 64 20 74 6f 20 63 6f 6e 66 69 67 75 72  used to configur
de80: 65 20 61 75 74 6f 6d 61 74 69 63 0a 2a 2a 20 72  e automatic.** r
de90: 65 74 72 79 20 63 6f 75 6e 74 73 20 61 6e 64 20  etry counts and 
dea0: 69 6e 74 65 72 76 61 6c 73 20 66 6f 72 20 63 65  intervals for ce
deb0: 72 74 61 69 6e 20 64 69 73 6b 20 49 2f 4f 20 6f  rtain disk I/O o
dec0: 70 65 72 61 74 69 6f 6e 73 20 66 6f 72 20 74 68  perations for th
ded0: 65 0a 2a 2a 20 77 69 6e 64 6f 77 73 20 5b 56 46  e.** windows [VF
dee0: 53 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 70  S] in order to p
def0: 72 6f 76 69 64 65 20 72 6f 62 75 73 74 6e 65 73  rovide robustnes
df00: 73 20 69 6e 20 74 68 65 20 70 72 65 73 65 6e 63  s in the presenc
df10: 65 20 6f 66 0a 2a 2a 20 61 6e 74 69 2d 76 69 72  e of.** anti-vir
df20: 75 73 20 70 72 6f 67 72 61 6d 73 2e 20 20 42 79  us programs.  By
df30: 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20 77 69   default, the wi
df40: 6e 64 6f 77 73 20 56 46 53 20 77 69 6c 6c 20 72  ndows VFS will r
df50: 65 74 72 79 20 66 69 6c 65 20 72 65 61 64 2c 0a  etry file read,.
df60: 2a 2a 20 66 69 6c 65 20 77 72 69 74 65 2c 20 61  ** file write, a
df70: 6e 64 20 66 69 6c 65 20 64 65 6c 65 74 65 20 6f  nd file delete o
df80: 70 65 72 61 74 69 6f 6e 73 20 75 70 20 74 6f 20  perations up to 
df90: 31 30 20 74 69 6d 65 73 2c 20 77 69 74 68 20 61  10 times, with a
dfa0: 20 64 65 6c 61 79 0a 2a 2a 20 6f 66 20 32 35 20   delay.** of 25 
dfb0: 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 62 65 66  milliseconds bef
dfc0: 6f 72 65 20 74 68 65 20 66 69 72 73 74 20 72 65  ore the first re
dfd0: 74 72 79 20 61 6e 64 20 77 69 74 68 20 74 68 65  try and with the
dfe0: 20 64 65 6c 61 79 20 69 6e 63 72 65 61 73 69 6e   delay increasin
dff0: 67 0a 2a 2a 20 62 79 20 61 6e 20 61 64 64 69 74  g.** by an addit
e000: 69 6f 6e 61 6c 20 32 35 20 6d 69 6c 6c 69 73 65  ional 25 millise
e010: 63 6f 6e 64 73 20 77 69 74 68 20 65 61 63 68 20  conds with each 
e020: 73 75 62 73 65 71 75 65 6e 74 20 72 65 74 72 79  subsequent retry
e030: 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64  .  This.** opcod
e040: 65 20 61 6c 6c 6f 77 73 20 74 68 65 73 65 20 74  e allows these t
e050: 77 6f 20 76 61 6c 75 65 73 20 28 31 30 20 72 65  wo values (10 re
e060: 74 72 69 65 73 20 61 6e 64 20 32 35 20 6d 69 6c  tries and 25 mil
e070: 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 64 65 6c  liseconds of del
e080: 61 79 29 0a 2a 2a 20 74 6f 20 62 65 20 61 64 6a  ay).** to be adj
e090: 75 73 74 65 64 2e 20 20 54 68 65 20 76 61 6c 75  usted.  The valu
e0a0: 65 73 20 61 72 65 20 63 68 61 6e 67 65 64 20 66  es are changed f
e0b0: 6f 72 20 61 6c 6c 20 64 61 74 61 62 61 73 65 20  or all database 
e0c0: 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 77  connections.** w
e0d0: 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 70  ithin the same p
e0e0: 72 6f 63 65 73 73 2e 20 20 54 68 65 20 61 72 67  rocess.  The arg
e0f0: 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74  ument is a point
e100: 65 72 20 74 6f 20 61 6e 20 61 72 72 61 79 20 6f  er to an array o
e110: 66 20 74 77 6f 0a 2a 2a 20 69 6e 74 65 67 65 72  f two.** integer
e120: 73 20 77 68 65 72 65 20 74 68 65 20 66 69 72 73  s where the firs
e130: 74 20 69 6e 74 65 67 65 72 20 69 20 74 68 65 20  t integer i the 
e140: 6e 65 77 20 72 65 74 72 79 20 63 6f 75 6e 74 20  new retry count 
e150: 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a  and the second.*
e160: 2a 20 69 6e 74 65 67 65 72 20 69 73 20 74 68 65  * integer is the
e170: 20 64 65 6c 61 79 2e 20 20 49 66 20 65 69 74 68   delay.  If eith
e180: 65 72 20 69 6e 74 65 67 65 72 20 69 73 20 6e 65  er integer is ne
e190: 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65  gative, then the
e1a0: 20 73 65 74 74 69 6e 67 0a 2a 2a 20 69 73 20 6e   setting.** is n
e1b0: 6f 74 20 63 68 61 6e 67 65 64 20 62 75 74 20 69  ot changed but i
e1c0: 6e 73 74 65 61 64 20 74 68 65 20 70 72 69 6f 72  nstead the prior
e1d0: 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20 73   value of that s
e1e0: 65 74 74 69 6e 67 20 69 73 20 77 72 69 74 74 65  etting is writte
e1f0: 6e 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 61 72  n.** into the ar
e200: 72 61 79 20 65 6e 74 72 79 2c 20 61 6c 6c 6f 77  ray entry, allow
e210: 69 6e 67 20 74 68 65 20 63 75 72 72 65 6e 74 20  ing the current 
e220: 72 65 74 72 79 20 73 65 74 74 69 6e 67 73 20 74  retry settings t
e230: 6f 20 62 65 0a 2a 2a 20 69 6e 74 65 72 72 6f 67  o be.** interrog
e240: 61 74 65 64 2e 20 20 54 68 65 20 7a 44 62 4e 61  ated.  The zDbNa
e250: 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  me parameter is 
e260: 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c  ignored..**.** <
e270: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
e280: 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d 5d 0a  L_PERSIST_WAL]].
e290: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
e2a0: 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41  FCNTL_PERSIST_WA
e2b0: 4c 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  L] opcode is use
e2c0: 64 20 74 6f 20 73 65 74 20 6f 72 20 71 75 65 72  d to set or quer
e2d0: 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 73 74  y the.** persist
e2e0: 65 6e 74 20 5b 57 41 4c 20 7c 20 57 72 69 74 65  ent [WAL | Write
e2f0: 20 41 68 65 61 64 20 4c 6f 67 5d 20 73 65 74 74   Ahead Log] sett
e300: 69 6e 67 2e 20 20 42 79 20 64 65 66 61 75 6c 74  ing.  By default
e310: 2c 20 74 68 65 20 61 75 78 69 6c 69 61 72 79 0a  , the auxiliary.
e320: 2a 2a 20 77 72 69 74 65 20 61 68 65 61 64 20 6c  ** write ahead l
e330: 6f 67 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65  og and shared me
e340: 6d 6f 72 79 20 66 69 6c 65 73 20 75 73 65 64 20  mory files used 
e350: 66 6f 72 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  for transaction 
e360: 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 61 72 65 20 61  control.** are a
e370: 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c  utomatically del
e380: 65 74 65 64 20 77 68 65 6e 20 74 68 65 20 6c 61  eted when the la
e390: 74 65 73 74 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  test connection 
e3a0: 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  to the database.
e3b0: 2a 2a 20 63 6c 6f 73 65 73 2e 20 20 53 65 74 74  ** closes.  Sett
e3c0: 69 6e 67 20 70 65 72 73 69 73 74 65 6e 74 20 57  ing persistent W
e3d0: 41 4c 20 6d 6f 64 65 20 63 61 75 73 65 73 20 74  AL mode causes t
e3e0: 68 6f 73 65 20 66 69 6c 65 73 20 74 6f 20 70 65  hose files to pe
e3f0: 72 73 69 73 74 20 61 66 74 65 72 0a 2a 2a 20 63  rsist after.** c
e400: 6c 6f 73 65 2e 20 20 50 65 72 73 69 73 74 69 6e  lose.  Persistin
e410: 67 20 74 68 65 20 66 69 6c 65 73 20 69 73 20 75  g the files is u
e420: 73 65 66 75 6c 20 77 68 65 6e 20 6f 74 68 65 72  seful when other
e430: 20 70 72 6f 63 65 73 73 65 73 20 74 68 61 74 20   processes that 
e440: 64 6f 20 6e 6f 74 0a 2a 2a 20 68 61 76 65 20 77  do not.** have w
e450: 72 69 74 65 20 70 65 72 6d 69 73 73 69 6f 6e 20  rite permission 
e460: 6f 6e 20 74 68 65 20 64 69 72 65 63 74 6f 72 79  on the directory
e470: 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20   containing the 
e480: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 61  database file wa
e490: 6e 74 0a 2a 2a 20 74 6f 20 72 65 61 64 20 74 68  nt.** to read th
e4a0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c  e database file,
e4b0: 20 61 73 20 74 68 65 20 57 41 4c 20 61 6e 64 20   as the WAL and 
e4c0: 73 68 61 72 65 64 20 6d 65 6d 6f 72 79 20 66 69  shared memory fi
e4d0: 6c 65 73 20 6d 75 73 74 20 65 78 69 73 74 0a 2a  les must exist.*
e4e0: 2a 20 69 6e 20 6f 72 64 65 72 20 66 6f 72 20 74  * in order for t
e4f0: 68 65 20 64 61 74 61 62 61 73 65 20 74 6f 20 62  he database to b
e500: 65 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65  e readable.  The
e510: 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
e520: 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  r to.** [sqlite3
e530: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _file_control()]
e540: 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65   for this opcode
e550: 20 73 68 6f 75 6c 64 20 62 65 20 61 20 70 6f 69   should be a poi
e560: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67  nter to an integ
e570: 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65  er..** That inte
e580: 67 65 72 20 69 73 20 30 20 74 6f 20 64 69 73 61  ger is 0 to disa
e590: 62 6c 65 20 70 65 72 73 69 73 74 65 6e 74 20 57  ble persistent W
e5a0: 41 4c 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20  AL mode or 1 to 
e5b0: 65 6e 61 62 6c 65 20 70 65 72 73 69 73 74 65 6e  enable persisten
e5c0: 74 0a 2a 2a 20 57 41 4c 20 6d 6f 64 65 2e 20 20  t.** WAL mode.  
e5d0: 49 66 20 74 68 65 20 69 6e 74 65 67 65 72 20 69  If the integer i
e5e0: 73 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69 73  s -1, then it is
e5f0: 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 74   overwritten wit
e600: 68 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a  h the current.**
e610: 20 57 41 4c 20 70 65 72 73 69 73 74 65 6e 63 65   WAL persistence
e620: 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20   setting..**.** 
e630: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
e640: 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45  TL_POWERSAFE_OVE
e650: 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65  RWRITE]].** ^The
e660: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50   [SQLITE_FCNTL_P
e670: 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49  OWERSAFE_OVERWRI
e680: 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  TE] opcode is us
e690: 65 64 20 74 6f 20 73 65 74 20 6f 72 20 71 75 65  ed to set or que
e6a0: 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 73  ry the.** persis
e6b0: 74 65 6e 74 20 22 70 6f 77 65 72 73 61 66 65 2d  tent "powersafe-
e6c0: 6f 76 65 72 77 72 69 74 65 22 20 6f 72 20 22 50  overwrite" or "P
e6d0: 53 4f 57 22 20 73 65 74 74 69 6e 67 2e 20 20 54  SOW" setting.  T
e6e0: 68 65 20 50 53 4f 57 20 73 65 74 74 69 6e 67 0a  he PSOW setting.
e6f0: 2a 2a 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68  ** determines th
e700: 65 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  e [SQLITE_IOCAP_
e710: 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52  POWERSAFE_OVERWR
e720: 49 54 45 5d 20 62 69 74 20 6f 66 20 74 68 65 0a  ITE] bit of the.
e730: 2a 2a 20 78 44 65 76 69 63 65 43 68 61 72 61 63  ** xDeviceCharac
e740: 74 65 72 69 73 74 69 63 73 20 6d 65 74 68 6f 64  teristics method
e750: 73 2e 20 54 68 65 20 66 6f 75 72 74 68 20 70 61  s. The fourth pa
e760: 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73  rameter to.** [s
e770: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
e780: 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 20  rol()] for this 
e790: 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 65  opcode should be
e7a0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
e7b0: 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61   integer..** Tha
e7c0: 74 20 69 6e 74 65 67 65 72 20 69 73 20 30 20 74  t integer is 0 t
e7d0: 6f 20 64 69 73 61 62 6c 65 20 7a 65 72 6f 2d 64  o disable zero-d
e7e0: 61 6d 61 67 65 20 6d 6f 64 65 20 6f 72 20 31 20  amage mode or 1 
e7f0: 74 6f 20 65 6e 61 62 6c 65 20 7a 65 72 6f 2d 64  to enable zero-d
e800: 61 6d 61 67 65 0a 2a 2a 20 6d 6f 64 65 2e 20 20  amage.** mode.  
e810: 49 66 20 74 68 65 20 69 6e 74 65 67 65 72 20 69  If the integer i
e820: 73 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69 73  s -1, then it is
e830: 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 74   overwritten wit
e840: 68 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a  h the current.**
e850: 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64   zero-damage mod
e860: 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a  e setting..**.**
e870: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
e880: 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a  NTL_OVERWRITE]].
e890: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
e8a0: 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d  FCNTL_OVERWRITE]
e8b0: 20 6f 70 63 6f 64 65 20 69 73 20 69 6e 76 6f 6b   opcode is invok
e8c0: 65 64 20 62 79 20 53 51 4c 69 74 65 20 61 66 74  ed by SQLite aft
e8d0: 65 72 20 6f 70 65 6e 69 6e 67 0a 2a 2a 20 61 20  er opening.** a 
e8e0: 77 72 69 74 65 20 74 72 61 6e 73 61 63 74 69 6f  write transactio
e8f0: 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68  n to indicate th
e900: 61 74 2c 20 75 6e 6c 65 73 73 20 69 74 20 69 73  at, unless it is
e910: 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 66 6f 72   rolled back for
e920: 20 73 6f 6d 65 0a 2a 2a 20 72 65 61 73 6f 6e 2c   some.** reason,
e930: 20 74 68 65 20 65 6e 74 69 72 65 20 64 61 74 61   the entire data
e940: 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 62  base file will b
e950: 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20 62 79  e overwritten by
e960: 20 74 68 65 20 63 75 72 72 65 6e 74 20 0a 2a 2a   the current .**
e970: 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 54 68   transaction. Th
e980: 69 73 20 69 73 20 75 73 65 64 20 62 79 20 56 41  is is used by VA
e990: 43 55 55 4d 20 6f 70 65 72 61 74 69 6f 6e 73 2e  CUUM operations.
e9a0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
e9b0: 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d  ITE_FCNTL_VFSNAM
e9c0: 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  E]].** ^The [SQL
e9d0: 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d  ITE_FCNTL_VFSNAM
e9e0: 45 5d 20 6f 70 63 6f 64 65 20 63 61 6e 20 62 65  E] opcode can be
e9f0: 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20   used to obtain 
ea00: 74 68 65 20 6e 61 6d 65 73 20 6f 66 0a 2a 2a 20  the names of.** 
ea10: 61 6c 6c 20 5b 56 46 53 65 73 5d 20 69 6e 20 74  all [VFSes] in t
ea20: 68 65 20 56 46 53 20 73 74 61 63 6b 2e 20 20 54  he VFS stack.  T
ea30: 68 65 20 6e 61 6d 65 73 20 61 72 65 20 6f 66 20  he names are of 
ea40: 61 6c 6c 20 56 46 53 20 73 68 69 6d 73 20 61 6e  all VFS shims an
ea50: 64 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 62  d the.** final b
ea60: 6f 74 74 6f 6d 2d 6c 65 76 65 6c 20 56 46 53 20  ottom-level VFS 
ea70: 61 72 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f  are written into
ea80: 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64   memory obtained
ea90: 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74   from .** [sqlit
eaa0: 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64  e3_malloc()] and
eab0: 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 73   the result is s
eac0: 74 6f 72 65 64 20 69 6e 20 74 68 65 20 63 68 61  tored in the cha
ead0: 72 2a 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 74  r* variable.** t
eae0: 68 61 74 20 74 68 65 20 66 6f 75 72 74 68 20 70  hat the fourth p
eaf0: 61 72 61 6d 65 74 65 72 20 6f 66 20 5b 73 71 6c  arameter of [sql
eb00: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
eb10: 6c 28 29 5d 20 70 6f 69 6e 74 73 20 74 6f 2e 0a  l()] points to..
eb20: 2a 2a 20 54 68 65 20 63 61 6c 6c 65 72 20 69 73  ** The caller is
eb30: 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72   responsible for
eb40: 20 66 72 65 65 69 6e 67 20 74 68 65 20 6d 65 6d   freeing the mem
eb50: 6f 72 79 20 77 68 65 6e 20 64 6f 6e 65 2e 20 20  ory when done.  
eb60: 41 73 20 77 69 74 68 0a 2a 2a 20 61 6c 6c 20 66  As with.** all f
eb70: 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 61 63 74 69  ile-control acti
eb80: 6f 6e 73 2c 20 74 68 65 72 65 20 69 73 20 6e 6f  ons, there is no
eb90: 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 20   guarantee that 
eba0: 74 68 69 73 20 77 69 6c 6c 20 61 63 74 75 61 6c  this will actual
ebb0: 6c 79 0a 2a 2a 20 64 6f 20 61 6e 79 74 68 69 6e  ly.** do anythin
ebc0: 67 2e 20 20 43 61 6c 6c 65 72 73 20 73 68 6f 75  g.  Callers shou
ebd0: 6c 64 20 69 6e 69 74 69 61 6c 69 7a 65 20 74 68  ld initialize th
ebe0: 65 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c 65  e char* variable
ebf0: 20 74 6f 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f   to a NULL.** po
ec00: 69 6e 74 65 72 20 69 6e 20 63 61 73 65 20 74 68  inter in case th
ec10: 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20  is file-control 
ec20: 69 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74  is not implement
ec30: 65 64 2e 20 20 54 68 69 73 20 66 69 6c 65 2d 63  ed.  This file-c
ec40: 6f 6e 74 72 6f 6c 0a 2a 2a 20 69 73 20 69 6e 74  ontrol.** is int
ec50: 65 6e 64 65 64 20 66 6f 72 20 64 69 61 67 6e 6f  ended for diagno
ec60: 73 74 69 63 20 75 73 65 20 6f 6e 6c 79 2e 0a 2a  stic use only..*
ec70: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
ec80: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 5d  E_FCNTL_PRAGMA]]
ec90: 0a 2a 2a 20 5e 57 68 65 6e 65 76 65 72 20 61 20  .** ^Whenever a 
eca0: 5b 50 52 41 47 4d 41 5d 20 73 74 61 74 65 6d 65  [PRAGMA] stateme
ecb0: 6e 74 20 69 73 20 70 61 72 73 65 64 2c 20 61 6e  nt is parsed, an
ecc0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50   [SQLITE_FCNTL_P
ecd0: 52 41 47 4d 41 5d 20 0a 2a 2a 20 66 69 6c 65 20  RAGMA] .** file 
ece0: 63 6f 6e 74 72 6f 6c 20 69 73 20 73 65 6e 74 20  control is sent 
ecf0: 74 6f 20 74 68 65 20 6f 70 65 6e 20 5b 73 71 6c  to the open [sql
ed00: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63  ite3_file] objec
ed10: 74 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a  t corresponding.
ed20: 2a 2a 20 74 6f 20 74 68 65 20 64 61 74 61 62 61  ** to the databa
ed30: 73 65 20 66 69 6c 65 20 74 6f 20 77 68 69 63 68  se file to which
ed40: 20 74 68 65 20 70 72 61 67 6d 61 20 73 74 61 74   the pragma stat
ed50: 65 6d 65 6e 74 20 72 65 66 65 72 73 2e 20 5e 54  ement refers. ^T
ed60: 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74  he argument.** t
ed70: 6f 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  o the [SQLITE_FC
ed80: 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65  NTL_PRAGMA] file
ed90: 20 63 6f 6e 74 72 6f 6c 20 69 73 20 61 6e 20 61   control is an a
eda0: 72 72 61 79 20 6f 66 0a 2a 2a 20 70 6f 69 6e 74  rray of.** point
edb0: 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 28  ers to strings (
edc0: 63 68 61 72 2a 2a 29 20 69 6e 20 77 68 69 63 68  char**) in which
edd0: 20 74 68 65 20 73 65 63 6f 6e 64 20 65 6c 65 6d   the second elem
ede0: 65 6e 74 20 6f 66 20 74 68 65 20 61 72 72 61 79  ent of the array
edf0: 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20  .** is the name 
ee00: 6f 66 20 74 68 65 20 70 72 61 67 6d 61 20 61 6e  of the pragma an
ee10: 64 20 74 68 65 20 74 68 69 72 64 20 65 6c 65 6d  d the third elem
ee20: 65 6e 74 20 69 73 20 74 68 65 20 61 72 67 75 6d  ent is the argum
ee30: 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20 70 72  ent to the.** pr
ee40: 61 67 6d 61 20 6f 72 20 4e 55 4c 4c 20 69 66 20  agma or NULL if 
ee50: 74 68 65 20 70 72 61 67 6d 61 20 68 61 73 20 6e  the pragma has n
ee60: 6f 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 54 68  o argument.  ^Th
ee70: 65 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 6e  e handler for an
ee80: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  .** [SQLITE_FCNT
ee90: 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63  L_PRAGMA] file c
eea0: 6f 6e 74 72 6f 6c 20 63 61 6e 20 6f 70 74 69 6f  ontrol can optio
eeb0: 6e 61 6c 6c 79 20 6d 61 6b 65 20 74 68 65 20 66  nally make the f
eec0: 69 72 73 74 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20  irst element.** 
eed0: 6f 66 20 74 68 65 20 63 68 61 72 2a 2a 20 61 72  of the char** ar
eee0: 67 75 6d 65 6e 74 20 70 6f 69 6e 74 20 74 6f 20  gument point to 
eef0: 61 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65  a string obtaine
ef00: 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
ef10: 6d 70 72 69 6e 74 66 28 29 5d 0a 2a 2a 20 6f 72  mprintf()].** or
ef20: 20 74 68 65 20 65 71 75 69 76 61 6c 65 6e 74 20   the equivalent 
ef30: 61 6e 64 20 74 68 61 74 20 73 74 72 69 6e 67 20  and that string 
ef40: 77 69 6c 6c 20 62 65 63 6f 6d 65 20 74 68 65 20  will become the 
ef50: 72 65 73 75 6c 74 20 6f 66 20 74 68 65 20 70 72  result of the pr
ef60: 61 67 6d 61 20 6f 72 0a 2a 2a 20 74 68 65 20 65  agma or.** the e
ef70: 72 72 6f 72 20 6d 65 73 73 61 67 65 20 69 66 20  rror message if 
ef80: 74 68 65 20 70 72 61 67 6d 61 20 66 61 69 6c 73  the pragma fails
ef90: 2e 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51  . ^If the.** [SQ
efa0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
efb0: 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  A] file control 
efc0: 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
efd0: 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 65 6e 20  NOTFOUND], then 
efe0: 6e 6f 72 6d 61 6c 20 0a 2a 2a 20 5b 50 52 41 47  normal .** [PRAG
eff0: 4d 41 5d 20 70 72 6f 63 65 73 73 69 6e 67 20 63  MA] processing c
f000: 6f 6e 74 69 6e 75 65 73 2e 20 20 5e 49 66 20 74  ontinues.  ^If t
f010: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
f020: 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65  _PRAGMA].** file
f030: 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73   control returns
f040: 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68   [SQLITE_OK], th
f050: 65 6e 20 74 68 65 20 70 61 72 73 65 72 20 61 73  en the parser as
f060: 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a  sumes that the.*
f070: 2a 20 56 46 53 20 68 61 73 20 68 61 6e 64 6c 65  * VFS has handle
f080: 64 20 74 68 65 20 50 52 41 47 4d 41 20 69 74 73  d the PRAGMA its
f090: 65 6c 66 20 61 6e 64 20 74 68 65 20 70 61 72 73  elf and the pars
f0a0: 65 72 20 67 65 6e 65 72 61 74 65 73 20 61 20 6e  er generates a n
f0b0: 6f 2d 6f 70 0a 2a 2a 20 70 72 65 70 61 72 65 64  o-op.** prepared
f0c0: 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 49 66   statement.  ^If
f0d0: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   the [SQLITE_FCN
f0e0: 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20  TL_PRAGMA] file 
f0f0: 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 0a  control returns.
f100: 2a 2a 20 61 6e 79 20 72 65 73 75 6c 74 20 63 6f  ** any result co
f110: 64 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  de other than [S
f120: 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 5b 53 51  QLITE_OK] or [SQ
f130: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20  LITE_NOTFOUND], 
f140: 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 68  that means.** th
f150: 61 74 20 74 68 65 20 56 46 53 20 65 6e 63 6f 75  at the VFS encou
f160: 6e 74 65 72 65 64 20 61 6e 20 65 72 72 6f 72 20  ntered an error 
f170: 77 68 69 6c 65 20 68 61 6e 64 6c 69 6e 67 20 74  while handling t
f180: 68 65 20 5b 50 52 41 47 4d 41 5d 20 61 6e 64 20  he [PRAGMA] and 
f190: 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 61 74 69  the.** compilati
f1a0: 6f 6e 20 6f 66 20 74 68 65 20 50 52 41 47 4d 41  on of the PRAGMA
f1b0: 20 66 61 69 6c 73 20 77 69 74 68 20 61 6e 20 65   fails with an e
f1c0: 72 72 6f 72 2e 20 20 5e 54 68 65 20 5b 53 51 4c  rror.  ^The [SQL
f1d0: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
f1e0: 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f  ].** file contro
f1f0: 6c 20 6f 63 63 75 72 73 20 61 74 20 74 68 65 20  l occurs at the 
f200: 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 70 72 61  beginning of pra
f210: 67 6d 61 20 73 74 61 74 65 6d 65 6e 74 20 61 6e  gma statement an
f220: 61 6c 79 73 69 73 20 61 6e 64 20 73 6f 0a 2a 2a  alysis and so.**
f230: 20 69 74 20 69 73 20 61 62 6c 65 20 74 6f 20 6f   it is able to o
f240: 76 65 72 72 69 64 65 20 62 75 69 6c 74 2d 69 6e  verride built-in
f250: 20 5b 50 52 41 47 4d 41 5d 20 73 74 61 74 65 6d   [PRAGMA] statem
f260: 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  ents..**.** <li>
f270: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42  [[SQLITE_FCNTL_B
f280: 55 53 59 48 41 4e 44 4c 45 52 5d 5d 0a 2a 2a 20  USYHANDLER]].** 
f290: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e  ^The [SQLITE_FCN
f2a0: 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d 0a  TL_BUSYHANDLER].
f2b0: 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20  ** file-control 
f2c0: 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 62  may be invoked b
f2d0: 79 20 53 51 4c 69 74 65 20 6f 6e 20 74 68 65 20  y SQLite on the 
f2e0: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 68 61  database file ha
f2f0: 6e 64 6c 65 0a 2a 2a 20 73 68 6f 72 74 6c 79 20  ndle.** shortly 
f300: 61 66 74 65 72 20 69 74 20 69 73 20 6f 70 65 6e  after it is open
f310: 65 64 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 70  ed in order to p
f320: 72 6f 76 69 64 65 20 61 20 63 75 73 74 6f 6d 20  rovide a custom 
f330: 56 46 53 20 77 69 74 68 20 61 63 63 65 73 73 0a  VFS with access.
f340: 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6e 6e 65 63  ** to the connec
f350: 74 69 6f 6e 73 20 62 75 73 79 2d 68 61 6e 64 6c  tions busy-handl
f360: 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20 54 68 65  er callback. The
f370: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 66 20   argument is of 
f380: 74 79 70 65 20 28 76 6f 69 64 20 2a 2a 29 0a 2a  type (void **).*
f390: 2a 20 2d 20 61 6e 20 61 72 72 61 79 20 6f 66 20  * - an array of 
f3a0: 74 77 6f 20 28 76 6f 69 64 20 2a 29 20 76 61 6c  two (void *) val
f3b0: 75 65 73 2e 20 54 68 65 20 66 69 72 73 74 20 28  ues. The first (
f3c0: 76 6f 69 64 20 2a 29 20 61 63 74 75 61 6c 6c 79  void *) actually
f3d0: 20 70 6f 69 6e 74 73 0a 2a 2a 20 74 6f 20 61 20   points.** to a 
f3e0: 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70 65  function of type
f3f0: 20 28 69 6e 74 20 28 2a 29 28 76 6f 69 64 20 2a   (int (*)(void *
f400: 29 29 2e 20 49 6e 20 6f 72 64 65 72 20 74 6f 20  )). In order to 
f410: 69 6e 76 6f 6b 65 20 74 68 65 20 63 6f 6e 6e 65  invoke the conne
f420: 63 74 69 6f 6e 73 0a 2a 2a 20 62 75 73 79 2d 68  ctions.** busy-h
f430: 61 6e 64 6c 65 72 2c 20 74 68 69 73 20 66 75 6e  andler, this fun
f440: 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65 20  ction should be 
f450: 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 68 65  invoked with the
f460: 20 73 65 63 6f 6e 64 20 28 76 6f 69 64 20 2a 29   second (void *)
f470: 20 69 6e 0a 2a 2a 20 74 68 65 20 61 72 72 61 79   in.** the array
f480: 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 61 72 67   as the only arg
f490: 75 6d 65 6e 74 2e 20 49 66 20 69 74 20 72 65 74  ument. If it ret
f4a0: 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  urns non-zero, t
f4b0: 68 65 6e 20 74 68 65 20 6f 70 65 72 61 74 69 6f  hen the operatio
f4c0: 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72  n.** should be r
f4d0: 65 74 72 69 65 64 2e 20 49 66 20 69 74 20 72 65  etried. If it re
f4e0: 74 75 72 6e 73 20 7a 65 72 6f 2c 20 74 68 65 20  turns zero, the 
f4f0: 63 75 73 74 6f 6d 20 56 46 53 20 73 68 6f 75 6c  custom VFS shoul
f500: 64 20 61 62 61 6e 64 6f 6e 20 74 68 65 0a 2a 2a  d abandon the.**
f510: 20 63 75 72 72 65 6e 74 20 6f 70 65 72 61 74 69   current operati
f520: 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  on..**.** <li>[[
f530: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d  SQLITE_FCNTL_TEM
f540: 50 46 49 4c 45 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e  PFILENAME]].** ^
f550: 41 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20  Application can 
f560: 69 6e 76 6f 6b 65 20 74 68 65 20 5b 53 51 4c 49  invoke the [SQLI
f570: 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c  TE_FCNTL_TEMPFIL
f580: 45 4e 41 4d 45 5d 20 66 69 6c 65 2d 63 6f 6e 74  ENAME] file-cont
f590: 72 6f 6c 0a 2a 2a 20 74 6f 20 68 61 76 65 20 53  rol.** to have S
f5a0: 51 4c 69 74 65 20 67 65 6e 65 72 61 74 65 20 61  QLite generate a
f5b0: 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69  .** temporary fi
f5c0: 6c 65 6e 61 6d 65 20 75 73 69 6e 67 20 74 68 65  lename using the
f5d0: 20 73 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d 20   same algorithm 
f5e0: 74 68 61 74 20 69 73 20 66 6f 6c 6c 6f 77 65 64  that is followed
f5f0: 20 74 6f 20 67 65 6e 65 72 61 74 65 0a 2a 2a 20   to generate.** 
f600: 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 6e 61  temporary filena
f610: 6d 65 73 20 66 6f 72 20 54 45 4d 50 20 74 61 62  mes for TEMP tab
f620: 6c 65 73 20 61 6e 64 20 6f 74 68 65 72 20 69 6e  les and other in
f630: 74 65 72 6e 61 6c 20 75 73 65 73 2e 20 20 54 68  ternal uses.  Th
f640: 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68  e.** argument sh
f650: 6f 75 6c 64 20 62 65 20 61 20 63 68 61 72 2a 2a  ould be a char**
f660: 20 77 68 69 63 68 20 77 69 6c 6c 20 62 65 20 66   which will be f
f670: 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 66  illed with the f
f680: 69 6c 65 6e 61 6d 65 0a 2a 2a 20 77 72 69 74 74  ilename.** writt
f690: 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f  en into memory o
f6a0: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
f6b0: 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e  lite3_malloc()].
f6c0: 20 20 54 68 65 20 63 61 6c 6c 65 72 20 73 68 6f    The caller sho
f6d0: 75 6c 64 0a 2a 2a 20 69 6e 76 6f 6b 65 20 5b 73  uld.** invoke [s
f6e0: 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f  qlite3_free()] o
f6f0: 6e 20 74 68 65 20 72 65 73 75 6c 74 20 74 6f 20  n the result to 
f700: 61 76 6f 69 64 20 61 20 6d 65 6d 6f 72 79 20 6c  avoid a memory l
f710: 65 61 6b 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  eak..**.** <li>[
f720: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d  [SQLITE_FCNTL_MM
f730: 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65  AP_SIZE]].** The
f740: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d   [SQLITE_FCNTL_M
f750: 4d 41 50 5f 53 49 5a 45 5d 20 66 69 6c 65 20 63  MAP_SIZE] file c
f760: 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65 64 20 74  ontrol is used t
f770: 6f 20 71 75 65 72 79 20 6f 72 20 73 65 74 20 74  o query or set t
f780: 68 65 0a 2a 2a 20 6d 61 78 69 6d 75 6d 20 6e 75  he.** maximum nu
f790: 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 74 68  mber of bytes th
f7a0: 61 74 20 77 69 6c 6c 20 62 65 20 75 73 65 64 20  at will be used 
f7b0: 66 6f 72 20 6d 65 6d 6f 72 79 2d 6d 61 70 70 65  for memory-mappe
f7c0: 64 20 49 2f 4f 2e 0a 2a 2a 20 54 68 65 20 61 72  d I/O..** The ar
f7d0: 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e  gument is a poin
f7e0: 74 65 72 20 74 6f 20 61 20 76 61 6c 75 65 20 6f  ter to a value o
f7f0: 66 20 74 79 70 65 20 73 71 6c 69 74 65 33 5f 69  f type sqlite3_i
f800: 6e 74 36 34 20 74 68 61 74 0a 2a 2a 20 69 73 20  nt64 that.** is 
f810: 61 6e 20 61 64 76 69 73 6f 72 79 20 6d 61 78 69  an advisory maxi
f820: 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  mum number of by
f830: 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65 20  tes in the file 
f840: 74 6f 20 6d 65 6d 6f 72 79 20 6d 61 70 2e 20 20  to memory map.  
f850: 54 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69  The.** pointer i
f860: 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69  s overwritten wi
f870: 74 68 20 74 68 65 20 6f 6c 64 20 76 61 6c 75 65  th the old value
f880: 2e 20 20 54 68 65 20 6c 69 6d 69 74 20 69 73 20  .  The limit is 
f890: 6e 6f 74 20 63 68 61 6e 67 65 64 20 69 66 0a 2a  not changed if.*
f8a0: 2a 20 74 68 65 20 76 61 6c 75 65 20 6f 72 69 67  * the value orig
f8b0: 69 6e 61 6c 6c 79 20 70 6f 69 6e 74 65 64 20 74  inally pointed t
f8c0: 6f 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 61  o is negative, a
f8d0: 6e 64 20 73 6f 20 74 68 65 20 63 75 72 72 65 6e  nd so the curren
f8e0: 74 20 6c 69 6d 69 74 20 0a 2a 2a 20 63 61 6e 20  t limit .** can 
f8f0: 62 65 20 71 75 65 72 69 65 64 20 62 79 20 70 61  be queried by pa
f900: 73 73 69 6e 67 20 69 6e 20 61 20 70 6f 69 6e 74  ssing in a point
f910: 65 72 20 74 6f 20 61 20 6e 65 67 61 74 69 76 65  er to a negative
f920: 20 6e 75 6d 62 65 72 2e 20 20 54 68 69 73 0a 2a   number.  This.*
f930: 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69  * file-control i
f940: 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c  s used internall
f950: 79 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b  y to implement [
f960: 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65  PRAGMA mmap_size
f970: 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  ]..**.** </ul>.*
f980: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
f990: 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45  _FCNTL_LOCKSTATE
f9a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
f9b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
f9c0: 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c  GET_LOCKPROXYFIL
f9d0: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 32 0a  E             2.
f9e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
f9f0: 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45  ET_LOCKPROXYFILE
fa00: 20 20 20 20 20 20 20 20 20 20 20 20 20 33 0a 23               3.#
fa10: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 41  define SQLITE_LA
fa20: 53 54 5f 45 52 52 4e 4f 20 20 20 20 20 20 20 20  ST_ERRNO        
fa30: 20 20 20 20 20 20 20 20 20 20 20 20 34 0a 23 64              4.#d
fa40: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
fa50: 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 20 20 20 20  TL_SIZE_HINT    
fa60: 20 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 65             5.#de
fa70: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
fa80: 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 20 20 20 20  L_CHUNK_SIZE    
fa90: 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 66            6.#def
faa0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
fab0: 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 20 20 20  _FILE_POINTER   
fac0: 20 20 20 20 20 20 20 20 20 37 0a 23 64 65 66 69           7.#defi
fad0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
fae0: 53 59 4e 43 5f 4f 4d 49 54 54 45 44 20 20 20 20  SYNC_OMITTED    
faf0: 20 20 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e          8.#defin
fb00: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57  e SQLITE_FCNTL_W
fb10: 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 20 20 20  IN32_AV_RETRY   
fb20: 20 20 20 20 20 20 20 39 0a 23 64 65 66 69 6e 65         9.#define
fb30: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45   SQLITE_FCNTL_PE
fb40: 52 53 49 53 54 5f 57 41 4c 20 20 20 20 20 20 20  RSIST_WAL       
fb50: 20 20 20 20 20 31 30 0a 23 64 65 66 69 6e 65 20       10.#define 
fb60: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45  SQLITE_FCNTL_OVE
fb70: 52 57 52 49 54 45 20 20 20 20 20 20 20 20 20 20  RWRITE          
fb80: 20 20 20 20 31 31 0a 23 64 65 66 69 6e 65 20 53      11.#define S
fb90: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e  QLITE_FCNTL_VFSN
fba0: 41 4d 45 20 20 20 20 20 20 20 20 20 20 20 20 20  AME             
fbb0: 20 20 20 31 32 0a 23 64 65 66 69 6e 65 20 53 51     12.#define SQ
fbc0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52  LITE_FCNTL_POWER
fbd0: 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20 20  SAFE_OVERWRITE  
fbe0: 20 20 31 33 0a 23 64 65 66 69 6e 65 20 53 51 4c    13.#define SQL
fbf0: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
fc00: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
fc10: 20 31 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   14.#define SQLI
fc20: 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e  TE_FCNTL_BUSYHAN
fc30: 44 4c 45 52 20 20 20 20 20 20 20 20 20 20 20 20  DLER            
fc40: 31 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  15.#define SQLIT
fc50: 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45  E_FCNTL_TEMPFILE
fc60: 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20 20 31  NAME           1
fc70: 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  6.#define SQLITE
fc80: 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45  _FCNTL_MMAP_SIZE
fc90: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 38                18
fca0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
fcb0: 3a 20 4d 75 74 65 78 20 48 61 6e 64 6c 65 0a 2a  : Mutex Handle.*
fcc0: 2a 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 6d  *.** The mutex m
fcd0: 6f 64 75 6c 65 20 77 69 74 68 69 6e 20 53 51 4c  odule within SQL
fce0: 69 74 65 20 64 65 66 69 6e 65 73 20 5b 73 71 6c  ite defines [sql
fcf0: 69 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62  ite3_mutex] to b
fd00: 65 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74  e an.** abstract
fd10: 20 74 79 70 65 20 66 6f 72 20 61 20 6d 75 74 65   type for a mute
fd20: 78 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 53  x object.  The S
fd30: 51 4c 69 74 65 20 63 6f 72 65 20 6e 65 76 65 72  QLite core never
fd40: 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65   looks.** at the
fd50: 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73   internal repres
fd60: 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b  entation of an [
fd70: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20  sqlite3_mutex]. 
fd80: 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c   It only.** deal
fd90: 73 20 77 69 74 68 20 70 6f 69 6e 74 65 72 73 20  s with pointers 
fda0: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
fdb0: 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a  mutex] object..*
fdc0: 2a 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61 72 65  *.** Mutexes are
fdd0: 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b   created using [
fde0: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c  sqlite3_mutex_al
fdf0: 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64  loc()]..*/.typed
fe00: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
fe10: 33 5f 6d 75 74 65 78 20 73 71 6c 69 74 65 33 5f  3_mutex sqlite3_
fe20: 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  mutex;../*.** CA
fe30: 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72  PI3REF: OS Inter
fe40: 66 61 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a  face Object.**.*
fe50: 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  * An instance of
fe60: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73   the sqlite3_vfs
fe70: 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20   object defines 
fe80: 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65  the interface be
fe90: 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c  tween.** the SQL
fea0: 69 74 65 20 63 6f 72 65 20 61 6e 64 20 74 68 65  ite core and the
feb0: 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72   underlying oper
fec0: 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 54  ating system.  T
fed0: 68 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74  he "vfs".** in t
fee0: 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f  he name of the o
fef0: 62 6a 65 63 74 20 73 74 61 6e 64 73 20 66 6f 72  bject stands for
ff00: 20 22 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73   "virtual file s
ff10: 79 73 74 65 6d 22 2e 20 20 53 65 65 0a 2a 2a 20  ystem".  See.** 
ff20: 74 68 65 20 5b 56 46 53 20 7c 20 56 46 53 20 64  the [VFS | VFS d
ff30: 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f  ocumentation] fo
ff40: 72 20 66 75 72 74 68 65 72 20 69 6e 66 6f 72 6d  r further inform
ff50: 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ation..**.** The
ff60: 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 69 56   value of the iV
ff70: 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 69 73 20  ersion field is 
ff80: 69 6e 69 74 69 61 6c 6c 79 20 31 20 62 75 74 20  initially 1 but 
ff90: 6d 61 79 20 62 65 20 6c 61 72 67 65 72 20 69 6e  may be larger in
ffa0: 0a 2a 2a 20 66 75 74 75 72 65 20 76 65 72 73 69  .** future versi
ffb0: 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20  ons of SQLite.  
ffc0: 41 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64  Additional field
ffd0: 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65  s may be appende
ffe0: 64 20 74 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a  d to this.** obj
fff0: 65 63 74 20 77 68 65 6e 20 74 68 65 20 69 56 65  ect when the iVe
10000 72 73 69 6f 6e 20 76 61 6c 75 65 20 69 73 20 69  rsion value is i
10010 6e 63 72 65 61 73 65 64 2e 20 20 4e 6f 74 65 20  ncreased.  Note 
10020 74 68 61 74 20 74 68 65 20 73 74 72 75 63 74 75  that the structu
10030 72 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c  re.** of the sql
10040 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20  ite3_vfs object 
10050 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 74  changes in the t
10060 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 74 77 65  ransaction betwe
10070 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72  en.** SQLite ver
10080 73 69 6f 6e 20 33 2e 35 2e 39 20 61 6e 64 20 33  sion 3.5.9 and 3
10090 2e 36 2e 30 20 61 6e 64 20 79 65 74 20 74 68 65  .6.0 and yet the
100a0 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20   iVersion field 
100b0 77 61 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66  was not.** modif
100c0 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ied..**.** The s
100d0 7a 4f 73 46 69 6c 65 20 66 69 65 6c 64 20 69 73  zOsFile field is
100e0 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
100f0 20 73 75 62 63 6c 61 73 73 65 64 20 5b 73 71 6c   subclassed [sql
10100 69 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74  ite3_file].** st
10110 72 75 63 74 75 72 65 20 75 73 65 64 20 62 79 20  ructure used by 
10120 74 68 69 73 20 56 46 53 2e 20 20 6d 78 50 61 74  this VFS.  mxPat
10130 68 6e 61 6d 65 20 69 73 20 74 68 65 20 6d 61 78  hname is the max
10140 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a  imum length of.*
10150 2a 20 61 20 70 61 74 68 6e 61 6d 65 20 69 6e 20  * a pathname in 
10160 74 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20  this VFS..**.** 
10170 52 65 67 69 73 74 65 72 65 64 20 73 71 6c 69 74  Registered sqlit
10180 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 73 20 61  e3_vfs objects a
10190 72 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e  re kept on a lin
101a0 6b 65 64 20 6c 69 73 74 20 66 6f 72 6d 65 64 20  ked list formed 
101b0 62 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74 20  by.** the pNext 
101c0 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 5b 73  pointer.  The [s
101d0 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73  qlite3_vfs_regis
101e0 74 65 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73  ter()].** and [s
101f0 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67  qlite3_vfs_unreg
10200 69 73 74 65 72 28 29 5d 20 69 6e 74 65 72 66 61  ister()] interfa
10210 63 65 73 20 6d 61 6e 61 67 65 20 74 68 69 73 20  ces manage this 
10220 6c 69 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72  list.** in a thr
10230 65 61 64 2d 73 61 66 65 20 77 61 79 2e 20 20 54  ead-safe way.  T
10240 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f  he [sqlite3_vfs_
10250 66 69 6e 64 28 29 5d 20 69 6e 74 65 72 66 61 63  find()] interfac
10260 65 0a 2a 2a 20 73 65 61 72 63 68 65 73 20 74 68  e.** searches th
10270 65 20 6c 69 73 74 2e 20 20 4e 65 69 74 68 65 72  e list.  Neither
10280 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
10290 20 63 6f 64 65 20 6e 6f 72 20 74 68 65 20 56 46   code nor the VF
102a0 53 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  S.** implementat
102b0 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 20 74  ion should use t
102c0 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72  he pNext pointer
102d0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78  ..**.** The pNex
102e0 74 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 6f  t field is the o
102f0 6e 6c 79 20 66 69 65 6c 64 20 69 6e 20 74 68 65  nly field in the
10300 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20   sqlite3_vfs.** 
10310 73 74 72 75 63 74 75 72 65 20 74 68 61 74 20 53  structure that S
10320 51 4c 69 74 65 20 77 69 6c 6c 20 65 76 65 72 20  QLite will ever 
10330 6d 6f 64 69 66 79 2e 20 20 53 51 4c 69 74 65 20  modify.  SQLite 
10340 77 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73  will only access
10350 0a 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74 68  .** or modify th
10360 69 73 20 66 69 65 6c 64 20 77 68 69 6c 65 20 68  is field while h
10370 6f 6c 64 69 6e 67 20 61 20 70 61 72 74 69 63 75  olding a particu
10380 6c 61 72 20 73 74 61 74 69 63 20 6d 75 74 65 78  lar static mutex
10390 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  ..** The applica
103a0 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65  tion should neve
103b0 72 20 6d 6f 64 69 66 79 20 61 6e 79 74 68 69 6e  r modify anythin
103c0 67 20 77 69 74 68 69 6e 20 74 68 65 20 73 71 6c  g within the sql
103d0 69 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65  ite3_vfs.** obje
103e0 63 74 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65  ct once the obje
103f0 63 74 20 68 61 73 20 62 65 65 6e 20 72 65 67 69  ct has been regi
10400 73 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  stered..**.** Th
10410 65 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f  e zName field ho
10420 6c 64 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  lds the name of 
10430 74 68 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20  the VFS module. 
10440 20 54 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a   The name must.*
10450 2a 20 62 65 20 75 6e 69 71 75 65 20 61 63 72 6f  * be unique acro
10460 73 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c  ss all VFS modul
10470 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69  es..**.** [[sqli
10480 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 5d 0a  te3_vfs.xOpen]].
10490 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61  ** ^SQLite guara
104a0 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20 7a  ntees that the z
104b0 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74  Filename paramet
104c0 65 72 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69  er to xOpen.** i
104d0 73 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20  s either a NULL 
104e0 70 6f 69 6e 74 65 72 20 6f 72 20 73 74 72 69 6e  pointer or strin
104f0 67 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72  g obtained.** fr
10500 6f 6d 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65  om xFullPathname
10510 28 29 20 77 69 74 68 20 61 6e 20 6f 70 74 69 6f  () with an optio
10520 6e 61 6c 20 73 75 66 66 69 78 20 61 64 64 65 64  nal suffix added
10530 2e 0a 2a 2a 20 5e 49 66 20 61 20 73 75 66 66 69  ..** ^If a suffi
10540 78 20 69 73 20 61 64 64 65 64 20 74 6f 20 74 68  x is added to th
10550 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61  e zFilename para
10560 6d 65 74 65 72 2c 20 69 74 20 77 69 6c 6c 0a 2a  meter, it will.*
10570 2a 20 63 6f 6e 73 69 73 74 20 6f 66 20 61 20 73  * consist of a s
10580 69 6e 67 6c 65 20 22 2d 22 20 63 68 61 72 61 63  ingle "-" charac
10590 74 65 72 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  ter followed by 
105a0 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 0a 2a 2a 20  no more than.** 
105b0 31 31 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20  11 alphanumeric 
105c0 61 6e 64 2f 6f 72 20 22 2d 22 20 63 68 61 72 61  and/or "-" chara
105d0 63 74 65 72 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74  cters..** ^SQLit
105e0 65 20 66 75 72 74 68 65 72 20 67 75 61 72 61 6e  e further guaran
105f0 74 65 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65  tees that.** the
10600 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 20   string will be 
10610 76 61 6c 69 64 20 61 6e 64 20 75 6e 63 68 61 6e  valid and unchan
10620 67 65 64 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65  ged until xClose
10630 28 29 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e  () is.** called.
10640 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20   Because of the 
10650 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63  previous sentenc
10660 65 2c 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74  e,.** the [sqlit
10670 65 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73 61 66  e3_file] can saf
10680 65 6c 79 20 73 74 6f 72 65 20 61 20 70 6f 69 6e  ely store a poin
10690 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69  ter to the.** fi
106a0 6c 65 6e 61 6d 65 20 69 66 20 69 74 20 6e 65 65  lename if it nee
106b0 64 73 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 74  ds to remember t
106c0 68 65 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20  he filename for 
106d0 73 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20  some reason..** 
106e0 49 66 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65  If the zFilename
106f0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f   parameter to xO
10700 70 65 6e 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  pen is a NULL po
10710 69 6e 74 65 72 20 74 68 65 6e 20 78 4f 70 65 6e  inter then xOpen
10720 0a 2a 2a 20 6d 75 73 74 20 69 6e 76 65 6e 74 20  .** must invent 
10730 69 74 73 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72  its own temporar
10740 79 20 6e 61 6d 65 20 66 6f 72 20 74 68 65 20 66  y name for the f
10750 69 6c 65 2e 20 20 5e 57 68 65 6e 65 76 65 72 20  ile.  ^Whenever 
10760 74 68 65 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d  the .** xFilenam
10770 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 4e  e parameter is N
10780 55 4c 4c 20 69 74 20 77 69 6c 6c 20 61 6c 73 6f  ULL it will also
10790 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61   be the case tha
107a0 74 20 74 68 65 0a 2a 2a 20 66 6c 61 67 73 20 70  t the.** flags p
107b0 61 72 61 6d 65 74 65 72 20 77 69 6c 6c 20 69 6e  arameter will in
107c0 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50  clude [SQLITE_OP
107d0 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45  EN_DELETEONCLOSE
107e0 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61  ]..**.** The fla
107f0 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78  gs argument to x
10800 4f 70 65 6e 28 29 20 69 6e 63 6c 75 64 65 73 20  Open() includes 
10810 61 6c 6c 20 62 69 74 73 20 73 65 74 20 69 6e 0a  all bits set in.
10820 2a 2a 20 74 68 65 20 66 6c 61 67 73 20 61 72 67  ** the flags arg
10830 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65  ument to [sqlite
10840 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20 4f  3_open_v2()].  O
10850 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70  r if [sqlite3_op
10860 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c  en()].** or [sql
10870 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69  ite3_open16()] i
10880 73 20 75 73 65 64 2c 20 74 68 65 6e 20 66 6c 61  s used, then fla
10890 67 73 20 69 6e 63 6c 75 64 65 73 20 61 74 20 6c  gs includes at l
108a0 65 61 73 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  east.** [SQLITE_
108b0 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20  OPEN_READWRITE] 
108c0 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  | [SQLITE_OPEN_C
108d0 52 45 41 54 45 5d 2e 20 0a 2a 2a 20 49 66 20 78  REATE]. .** If x
108e0 4f 70 65 6e 28 29 20 6f 70 65 6e 73 20 61 20 66  Open() opens a f
108f0 69 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68  ile read-only th
10900 65 6e 20 69 74 20 73 65 74 73 20 2a 70 4f 75 74  en it sets *pOut
10910 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c  Flags to.** incl
10920 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  ude [SQLITE_OPEN
10930 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68  _READONLY].  Oth
10940 65 72 20 62 69 74 73 20 69 6e 20 2a 70 4f 75 74  er bits in *pOut
10950 46 6c 61 67 73 20 6d 61 79 20 62 65 20 73 65 74  Flags may be set
10960 2e 0a 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74 65  ..**.** ^(SQLite
10970 20 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f   will also add o
10980 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77  ne of the follow
10990 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65  ing flags to the
109a0 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c   xOpen().** call
109b0 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  , depending on t
109c0 68 65 20 6f 62 6a 65 63 74 20 62 65 69 6e 67 20  he object being 
109d0 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75  opened:.**.** <u
109e0 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  l>.** <li>  [SQL
109f0 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42  ITE_OPEN_MAIN_DB
10a00 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
10a10 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55  TE_OPEN_MAIN_JOU
10a20 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  RNAL].** <li>  [
10a30 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50  SQLITE_OPEN_TEMP
10a40 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  _DB].** <li>  [S
10a50 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
10a60 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e  JOURNAL].** <li>
10a70 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54    [SQLITE_OPEN_T
10a80 52 41 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20  RANSIENT_DB].** 
10a90 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
10aa0 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a  EN_SUBJOURNAL].*
10ab0 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
10ac0 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52  OPEN_MASTER_JOUR
10ad0 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  NAL].** <li>  [S
10ae0 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 5d 0a  QLITE_OPEN_WAL].
10af0 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a  ** </ul>)^.**.**
10b00 20 54 68 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d   The file I/O im
10b10 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e  plementation can
10b20 20 75 73 65 20 74 68 65 20 6f 62 6a 65 63 74 20   use the object 
10b30 74 79 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a  type flags to.**
10b40 20 63 68 61 6e 67 65 20 74 68 65 20 77 61 79 20   change the way 
10b50 69 74 20 64 65 61 6c 73 20 77 69 74 68 20 66 69  it deals with fi
10b60 6c 65 73 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c  les.  For exampl
10b70 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  e, an applicatio
10b80 6e 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73 20 6e  n.** that does n
10b90 6f 74 20 63 61 72 65 20 61 62 6f 75 74 20 63 72  ot care about cr
10ba0 61 73 68 20 72 65 63 6f 76 65 72 79 20 6f 72 20  ash recovery or 
10bb0 72 6f 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d  rollback might m
10bc0 61 6b 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20  ake.** the open 
10bd0 6f 66 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c  of a journal fil
10be0 65 20 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74  e a no-op.  Writ
10bf0 65 73 20 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e  es to this journ
10c00 61 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f  al would.** also
10c10 20 62 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20   be no-ops, and 
10c20 61 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 72  any attempt to r
10c30 65 61 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20  ead the journal 
10c40 77 6f 75 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20  would return.** 
10c50 53 51 4c 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f  SQLITE_IOERR.  O
10c60 72 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  r the implementa
10c70 74 69 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f 67  tion might recog
10c80 6e 69 7a 65 20 74 68 61 74 20 61 20 64 61 74 61  nize that a data
10c90 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c  base.** file wil
10ca0 6c 20 62 65 20 64 6f 69 6e 67 20 70 61 67 65 2d  l be doing page-
10cb0 61 6c 69 67 6e 65 64 20 73 65 63 74 6f 72 20 72  aligned sector r
10cc0 65 61 64 73 20 61 6e 64 20 77 72 69 74 65 73 20  eads and writes 
10cd0 69 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f  in a random.** o
10ce0 72 64 65 72 20 61 6e 64 20 73 65 74 20 75 70 20  rder and set up 
10cf0 69 74 73 20 49 2f 4f 20 73 75 62 73 79 73 74 65  its I/O subsyste
10d00 6d 20 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a  m accordingly..*
10d10 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 69 67 68  *.** SQLite migh
10d20 74 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f  t also add one o
10d30 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  f the following 
10d40 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70  flags to the xOp
10d50 65 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a  en method:.**.**
10d60 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53   <ul>.** <li> [S
10d70 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
10d80 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69  EONCLOSE].** <li
10d90 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45  > [SQLITE_OPEN_E
10da0 58 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75  XCLUSIVE].** </u
10db0 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51  l>.**.** The [SQ
10dc0 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
10dd0 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65  ONCLOSE] flag me
10de0 61 6e 73 20 74 68 65 20 66 69 6c 65 20 73 68 6f  ans the file sho
10df0 75 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65  uld be.** delete
10e00 64 20 77 68 65 6e 20 69 74 20 69 73 20 63 6c 6f  d when it is clo
10e10 73 65 64 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49  sed.  ^The [SQLI
10e20 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
10e30 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62  CLOSE].** will b
10e40 65 20 73 65 74 20 66 6f 72 20 54 45 4d 50 20 64  e set for TEMP d
10e50 61 74 61 62 61 73 65 73 20 61 6e 64 20 74 68 65  atabases and the
10e60 69 72 20 6a 6f 75 72 6e 61 6c 73 2c 20 74 72 61  ir journals, tra
10e70 6e 73 69 65 6e 74 0a 2a 2a 20 64 61 74 61 62 61  nsient.** databa
10e80 73 65 73 2c 20 61 6e 64 20 73 75 62 6a 6f 75 72  ses, and subjour
10e90 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  nals..**.** ^The
10ea0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58   [SQLITE_OPEN_EX
10eb0 43 4c 55 53 49 56 45 5d 20 66 6c 61 67 20 69 73  CLUSIVE] flag is
10ec0 20 61 6c 77 61 79 73 20 75 73 65 64 20 69 6e 20   always used in 
10ed0 63 6f 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77  conjunction.** w
10ee0 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ith the [SQLITE_
10ef0 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20 66 6c 61  OPEN_CREATE] fla
10f00 67 2c 20 77 68 69 63 68 20 61 72 65 20 62 6f 74  g, which are bot
10f10 68 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 61 6e  h directly.** an
10f20 61 6c 6f 67 6f 75 73 20 74 6f 20 74 68 65 20 4f  alogous to the O
10f30 5f 45 58 43 4c 20 61 6e 64 20 4f 5f 43 52 45 41  _EXCL and O_CREA
10f40 54 20 66 6c 61 67 73 20 6f 66 20 74 68 65 20 50  T flags of the P
10f50 4f 53 49 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 41  OSIX open().** A
10f60 50 49 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  PI.  The SQLITE_
10f70 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 66  OPEN_EXCLUSIVE f
10f80 6c 61 67 2c 20 77 68 65 6e 20 70 61 69 72 65 64  lag, when paired
10f90 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 53 51   with the .** SQ
10fa0 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
10fb0 2c 20 69 73 20 75 73 65 64 20 74 6f 20 69 6e 64  , is used to ind
10fc0 69 63 61 74 65 20 74 68 61 74 20 66 69 6c 65 20  icate that file 
10fd0 73 68 6f 75 6c 64 20 61 6c 77 61 79 73 0a 2a 2a  should always.**
10fe0 20 62 65 20 63 72 65 61 74 65 64 2c 20 61 6e 64   be created, and
10ff0 20 74 68 61 74 20 69 74 20 69 73 20 61 6e 20 65   that it is an e
11000 72 72 6f 72 20 69 66 20 69 74 20 61 6c 72 65 61  rror if it alrea
11010 64 79 20 65 78 69 73 74 73 2e 0a 2a 2a 20 49 74  dy exists..** It
11020 20 69 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75   is <i>not</i> u
11030 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20  sed to indicate 
11040 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20  the file should 
11050 62 65 20 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 6f  be opened .** fo
11060 72 20 65 78 63 6c 75 73 69 76 65 20 61 63 63 65  r exclusive acce
11070 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74 20 6c 65  ss..**.** ^At le
11080 61 73 74 20 73 7a 4f 73 46 69 6c 65 20 62 79 74  ast szOsFile byt
11090 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65  es of memory are
110a0 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51   allocated by SQ
110b0 4c 69 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20  Lite.** to hold 
110c0 74 68 65 20 20 5b 73 71 6c 69 74 65 33 5f 66 69  the  [sqlite3_fi
110d0 6c 65 5d 20 73 74 72 75 63 74 75 72 65 20 70 61  le] structure pa
110e0 73 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72  ssed as the thir
110f0 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f  d.** argument to
11100 20 78 4f 70 65 6e 2e 20 20 54 68 65 20 78 4f 70   xOpen.  The xOp
11110 65 6e 20 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e  en method does n
11120 6f 74 20 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c  ot have to.** al
11130 6c 6f 63 61 74 65 20 74 68 65 20 73 74 72 75 63  locate the struc
11140 74 75 72 65 3b 20 69 74 20 73 68 6f 75 6c 64 20  ture; it should 
11150 6a 75 73 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e  just fill it in.
11160 20 20 4e 6f 74 65 20 74 68 61 74 0a 2a 2a 20 74    Note that.** t
11170 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20  he xOpen method 
11180 6d 75 73 74 20 73 65 74 20 74 68 65 20 73 71 6c  must set the sql
11190 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f  ite3_file.pMetho
111a0 64 73 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20  ds to either.** 
111b0 61 20 76 61 6c 69 64 20 5b 73 71 6c 69 74 65 33  a valid [sqlite3
111c0 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
111d0 65 63 74 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20  ect or to NULL. 
111e0 20 78 4f 70 65 6e 20 6d 75 73 74 20 64 6f 0a 2a   xOpen must do.*
111f0 2a 20 74 68 69 73 20 65 76 65 6e 20 69 66 20 74  * this even if t
11200 68 65 20 6f 70 65 6e 20 66 61 69 6c 73 2e 20 20  he open fails.  
11210 53 51 4c 69 74 65 20 65 78 70 65 63 74 73 20 74  SQLite expects t
11220 68 61 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f  hat the sqlite3_
11230 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a  file.pMethods.**
11240 20 65 6c 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65   element will be
11250 20 76 61 6c 69 64 20 61 66 74 65 72 20 78 4f 70   valid after xOp
11260 65 6e 20 72 65 74 75 72 6e 73 20 72 65 67 61 72  en returns regar
11270 64 6c 65 73 73 20 6f 66 20 74 68 65 20 73 75 63  dless of the suc
11280 63 65 73 73 0a 2a 2a 20 6f 72 20 66 61 69 6c 75  cess.** or failu
11290 72 65 20 6f 66 20 74 68 65 20 78 4f 70 65 6e 20  re of the xOpen 
112a0 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71  call..**.** [[sq
112b0 6c 69 74 65 33 5f 76 66 73 2e 78 41 63 63 65 73  lite3_vfs.xAcces
112c0 73 5d 5d 0a 2a 2a 20 5e 54 68 65 20 66 6c 61 67  s]].** ^The flag
112d0 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 41  s argument to xA
112e0 63 63 65 73 73 28 29 20 6d 61 79 20 62 65 20 5b  ccess() may be [
112f0 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58  SQLITE_ACCESS_EX
11300 49 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73 74  ISTS].** to test
11310 20 66 6f 72 20 74 68 65 20 65 78 69 73 74 65 6e   for the existen
11320 63 65 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f 72  ce of a file, or
11330 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f   [SQLITE_ACCESS_
11340 52 45 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a 2a  READWRITE] to.**
11350 20 74 65 73 74 20 77 68 65 74 68 65 72 20 61 20   test whether a 
11360 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65  file is readable
11370 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2c 20 6f   and writable, o
11380 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53  r [SQLITE_ACCESS
11390 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65 73  _READ].** to tes
113a0 74 20 77 68 65 74 68 65 72 20 61 20 66 69 6c 65  t whether a file
113b0 20 69 73 20 61 74 20 6c 65 61 73 74 20 72 65 61   is at least rea
113c0 64 61 62 6c 65 2e 20 20 20 54 68 65 20 66 69 6c  dable.   The fil
113d0 65 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64 69  e can be a.** di
113e0 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e  rectory..**.** ^
113f0 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77 61  SQLite will alwa
11400 79 73 20 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c  ys allocate at l
11410 65 61 73 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b  east mxPathname+
11420 31 20 62 79 74 65 73 20 66 6f 72 20 74 68 65 0a  1 bytes for the.
11430 2a 2a 20 6f 75 74 70 75 74 20 62 75 66 66 65 72  ** output buffer
11440 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20   xFullPathname. 
11450 20 54 68 65 20 65 78 61 63 74 20 73 69 7a 65 20   The exact size 
11460 6f 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75  of the output bu
11470 66 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20  ffer.** is also 
11480 70 61 73 73 65 64 20 61 73 20 61 20 70 61 72 61  passed as a para
11490 6d 65 74 65 72 20 74 6f 20 62 6f 74 68 20 20 6d  meter to both  m
114a0 65 74 68 6f 64 73 2e 20 49 66 20 74 68 65 20 6f  ethods. If the o
114b0 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20  utput buffer.** 
114c0 69 73 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f  is not large eno
114d0 75 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e  ugh, [SQLITE_CAN
114e0 54 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65  TOPEN] should be
114f0 20 72 65 74 75 72 6e 65 64 2e 20 53 69 6e 63 65   returned. Since
11500 20 74 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64   this is.** hand
11510 6c 65 64 20 61 73 20 61 20 66 61 74 61 6c 20 65  led as a fatal e
11520 72 72 6f 72 20 62 79 20 53 51 4c 69 74 65 2c 20  rror by SQLite, 
11530 76 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  vfs implementati
11540 6f 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64 65 61  ons should endea
11550 76 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e  vor.** to preven
11560 74 20 74 68 69 73 20 62 79 20 73 65 74 74 69 6e  t this by settin
11570 67 20 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f 20  g mxPathname to 
11580 61 20 73 75 66 66 69 63 69 65 6e 74 6c 79 20 6c  a sufficiently l
11590 61 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a  arge value..**.*
115a0 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73  * The xRandomnes
115b0 73 28 29 2c 20 78 53 6c 65 65 70 28 29 2c 20 78  s(), xSleep(), x
115c0 43 75 72 72 65 6e 74 54 69 6d 65 28 29 2c 20 61  CurrentTime(), a
115d0 6e 64 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49  nd xCurrentTimeI
115e0 6e 74 36 34 28 29 0a 2a 2a 20 69 6e 74 65 72 66  nt64().** interf
115f0 61 63 65 73 20 61 72 65 20 6e 6f 74 20 73 74 72  aces are not str
11600 69 63 74 6c 79 20 61 20 70 61 72 74 20 6f 66 20  ictly a part of 
11610 74 68 65 20 66 69 6c 65 73 79 73 74 65 6d 2c 20  the filesystem, 
11620 62 75 74 20 74 68 65 79 20 61 72 65 0a 2a 2a 20  but they are.** 
11630 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65 20  included in the 
11640 56 46 53 20 73 74 72 75 63 74 75 72 65 20 66 6f  VFS structure fo
11650 72 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a  r completeness..
11660 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65  ** The xRandomne
11670 73 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 74  ss() function at
11680 74 65 6d 70 74 73 20 74 6f 20 72 65 74 75 72 6e  tempts to return
11690 20 6e 42 79 74 65 73 20 62 79 74 65 73 0a 2a 2a   nBytes bytes.**
116a0 20 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79   of good-quality
116b0 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f   randomness into
116c0 20 7a 4f 75 74 2e 20 20 54 68 65 20 72 65 74 75   zOut.  The retu
116d0 72 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74  rn value is.** t
116e0 68 65 20 61 63 74 75 61 6c 20 6e 75 6d 62 65 72  he actual number
116f0 20 6f 66 20 62 79 74 65 73 20 6f 66 20 72 61 6e   of bytes of ran
11700 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64  domness obtained
11710 2e 0a 2a 2a 20 54 68 65 20 78 53 6c 65 65 70 28  ..** The xSleep(
11720 29 20 6d 65 74 68 6f 64 20 63 61 75 73 65 73 20  ) method causes 
11730 74 68 65 20 63 61 6c 6c 69 6e 67 20 74 68 72 65  the calling thre
11740 61 64 20 74 6f 20 73 6c 65 65 70 20 66 6f 72 20  ad to sleep for 
11750 61 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65 20  at.** least the 
11760 6e 75 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f 73  number of micros
11770 65 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20 5e  econds given.  ^
11780 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65  The xCurrentTime
11790 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74  ().** method ret
117a0 75 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44 61  urns a Julian Da
117b0 79 20 4e 75 6d 62 65 72 20 66 6f 72 20 74 68 65  y Number for the
117c0 20 63 75 72 72 65 6e 74 20 64 61 74 65 20 61 6e   current date an
117d0 64 20 74 69 6d 65 20 61 73 0a 2a 2a 20 61 20 66  d time as.** a f
117e0 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61  loating point va
117f0 6c 75 65 2e 0a 2a 2a 20 5e 54 68 65 20 78 43 75  lue..** ^The xCu
11800 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29  rrentTimeInt64()
11810 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 2c   method returns,
11820 20 61 73 20 61 6e 20 69 6e 74 65 67 65 72 2c 20   as an integer, 
11830 74 68 65 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44 61  the Julian.** Da
11840 79 20 4e 75 6d 62 65 72 20 6d 75 6c 74 69 70 6c  y Number multipl
11850 69 65 64 20 62 79 20 38 36 34 30 30 30 30 30 20  ied by 86400000 
11860 28 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d  (the number of m
11870 69 6c 6c 69 73 65 63 6f 6e 64 73 20 69 6e 20 0a  illiseconds in .
11880 2a 2a 20 61 20 32 34 2d 68 6f 75 72 20 64 61 79  ** a 24-hour day
11890 29 2e 20 20 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ).  .** ^SQLite 
118a0 77 69 6c 6c 20 75 73 65 20 74 68 65 20 78 43 75  will use the xCu
118b0 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29  rrentTimeInt64()
118c0 20 6d 65 74 68 6f 64 20 74 6f 20 67 65 74 20 74   method to get t
118d0 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 64 61  he current.** da
118e0 74 65 20 61 6e 64 20 74 69 6d 65 20 69 66 20 74  te and time if t
118f0 68 61 74 20 6d 65 74 68 6f 64 20 69 73 20 61 76  hat method is av
11900 61 69 6c 61 62 6c 65 20 28 69 66 20 69 56 65 72  ailable (if iVer
11910 73 69 6f 6e 20 69 73 20 32 20 6f 72 20 0a 2a 2a  sion is 2 or .**
11920 20 67 72 65 61 74 65 72 20 61 6e 64 20 74 68 65   greater and the
11930 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65   function pointe
11940 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 61  r is not NULL) a
11950 6e 64 20 77 69 6c 6c 20 66 61 6c 6c 20 62 61 63  nd will fall bac
11960 6b 0a 2a 2a 20 74 6f 20 78 43 75 72 72 65 6e 74  k.** to xCurrent
11970 54 69 6d 65 28 29 20 69 66 20 78 43 75 72 72 65  Time() if xCurre
11980 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 69 73  ntTimeInt64() is
11990 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a   unavailable..**
119a0 0a 2a 2a 20 5e 54 68 65 20 78 53 65 74 53 79 73  .** ^The xSetSys
119b0 74 65 6d 43 61 6c 6c 28 29 2c 20 78 47 65 74 53  temCall(), xGetS
119c0 79 73 74 65 6d 43 61 6c 6c 28 29 2c 20 61 6e 64  ystemCall(), and
119d0 20 78 4e 65 73 74 53 79 73 74 65 6d 43 61 6c 6c   xNestSystemCall
119e0 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  () interfaces.**
119f0 20 61 72 65 20 6e 6f 74 20 75 73 65 64 20 62 79   are not used by
11a00 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   the SQLite core
11a10 2e 20 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 61  .  These optiona
11a20 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  l interfaces are
11a30 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 62 79 20   provided.** by 
11a40 73 6f 6d 65 20 56 46 53 65 73 20 74 6f 20 66 61  some VFSes to fa
11a50 63 69 6c 69 74 61 74 65 20 74 65 73 74 69 6e 67  cilitate testing
11a60 20 6f 66 20 74 68 65 20 56 46 53 20 63 6f 64 65   of the VFS code
11a70 2e 20 42 79 20 6f 76 65 72 72 69 64 69 6e 67 20  . By overriding 
11a80 0a 2a 2a 20 73 79 73 74 65 6d 20 63 61 6c 6c 73  .** system calls
11a90 20 77 69 74 68 20 66 75 6e 63 74 69 6f 6e 73 20   with functions 
11aa0 75 6e 64 65 72 20 69 74 73 20 63 6f 6e 74 72 6f  under its contro
11ab0 6c 2c 20 61 20 74 65 73 74 20 70 72 6f 67 72 61  l, a test progra
11ac0 6d 20 63 61 6e 0a 2a 2a 20 73 69 6d 75 6c 61 74  m can.** simulat
11ad0 65 20 66 61 75 6c 74 73 20 61 6e 64 20 65 72 72  e faults and err
11ae0 6f 72 20 63 6f 6e 64 69 74 69 6f 6e 73 20 74 68  or conditions th
11af0 61 74 20 77 6f 75 6c 64 20 6f 74 68 65 72 77 69  at would otherwi
11b00 73 65 20 62 65 20 64 69 66 66 69 63 75 6c 74 0a  se be difficult.
11b10 2a 2a 20 6f 72 20 69 6d 70 6f 73 73 69 62 6c 65  ** or impossible
11b20 20 74 6f 20 69 6e 64 75 63 65 2e 20 20 54 68 65   to induce.  The
11b30 20 73 65 74 20 6f 66 20 73 79 73 74 65 6d 20 63   set of system c
11b40 61 6c 6c 73 20 74 68 61 74 20 63 61 6e 20 62 65  alls that can be
11b50 20 6f 76 65 72 72 69 64 64 65 6e 0a 2a 2a 20 76   overridden.** v
11b60 61 72 69 65 73 20 66 72 6f 6d 20 6f 6e 65 20 56  aries from one V
11b70 46 53 20 74 6f 20 61 6e 6f 74 68 65 72 2c 20 61  FS to another, a
11b80 6e 64 20 66 72 6f 6d 20 6f 6e 65 20 76 65 72 73  nd from one vers
11b90 69 6f 6e 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ion of the same 
11ba0 56 46 53 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 65  VFS to the.** ne
11bb0 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e  xt.  Application
11bc0 73 20 74 68 61 74 20 75 73 65 20 74 68 65 73 65  s that use these
11bd0 20 69 6e 74 65 72 66 61 63 65 73 20 6d 75 73 74   interfaces must
11be0 20 62 65 20 70 72 65 70 61 72 65 64 20 66 6f 72   be prepared for
11bf0 20 61 6e 79 0a 2a 2a 20 6f 72 20 61 6c 6c 20 6f   any.** or all o
11c00 66 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63  f these interfac
11c10 65 73 20 74 6f 20 62 65 20 4e 55 4c 4c 20 6f 72  es to be NULL or
11c20 20 66 6f 72 20 74 68 65 69 72 20 62 65 68 61 76   for their behav
11c30 69 6f 72 20 74 6f 20 63 68 61 6e 67 65 0a 2a 2a  ior to change.**
11c40 20 66 72 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 73   from one releas
11c50 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 20 20  e to the next.  
11c60 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73  Applications mus
11c70 74 20 6e 6f 74 20 61 74 74 65 6d 70 74 20 74 6f  t not attempt to
11c80 20 61 63 63 65 73 73 0a 2a 2a 20 61 6e 79 20 6f   access.** any o
11c90 66 20 74 68 65 73 65 20 6d 65 74 68 6f 64 73 20  f these methods 
11ca0 69 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20  if the iVersion 
11cb0 6f 66 20 74 68 65 20 56 46 53 20 69 73 20 6c 65  of the VFS is le
11cc0 73 73 20 74 68 61 6e 20 33 2e 0a 2a 2f 0a 74 79  ss than 3..*/.ty
11cd0 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
11ce0 69 74 65 33 5f 76 66 73 20 73 71 6c 69 74 65 33  ite3_vfs sqlite3
11cf0 5f 76 66 73 3b 0a 74 79 70 65 64 65 66 20 76 6f  _vfs;.typedef vo
11d00 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 73 79 73  id (*sqlite3_sys
11d10 63 61 6c 6c 5f 70 74 72 29 28 76 6f 69 64 29 3b  call_ptr)(void);
11d20 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
11d30 76 66 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72  vfs {.  int iVer
11d40 73 69 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 20  sion;           
11d50 20 2f 2a 20 53 74 72 75 63 74 75 72 65 20 76 65   /* Structure ve
11d60 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 63 75  rsion number (cu
11d70 72 72 65 6e 74 6c 79 20 33 29 20 2a 2f 0a 20 20  rrently 3) */.  
11d80 69 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20  int szOsFile;   
11d90 20 20 20 20 20 20 20 20 20 2f 2a 20 53 69 7a 65           /* Size
11da0 20 6f 66 20 73 75 62 63 6c 61 73 73 65 64 20 73   of subclassed s
11db0 71 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20  qlite3_file */. 
11dc0 20 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b   int mxPathname;
11dd0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
11de0 69 6d 75 6d 20 66 69 6c 65 20 70 61 74 68 6e 61  imum file pathna
11df0 6d 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73  me length */.  s
11e00 71 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e 65 78  qlite3_vfs *pNex
11e10 74 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78 74 20  t;      /* Next 
11e20 72 65 67 69 73 74 65 72 65 64 20 56 46 53 20 2a  registered VFS *
11e30 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
11e40 7a 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20  zName;       /* 
11e50 4e 61 6d 65 20 6f 66 20 74 68 69 73 20 76 69 72  Name of this vir
11e60 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d  tual file system
11e70 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70   */.  void *pApp
11e80 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 2f  Data;          /
11e90 2a 20 50 6f 69 6e 74 65 72 20 74 6f 20 61 70 70  * Pointer to app
11ea0 6c 69 63 61 74 69 6f 6e 2d 73 70 65 63 69 66 69  lication-specifi
11eb0 63 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20  c data */.  int 
11ec0 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33  (*xOpen)(sqlite3
11ed0 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
11ee0 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65  r *zName, sqlite
11ef0 33 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20  3_file*,.       
11f00 20 20 20 20 20 20 20 20 69 6e 74 20 66 6c 61 67          int flag
11f10 73 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67  s, int *pOutFlag
11f20 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c  s);.  int (*xDel
11f30 65 74 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ete)(sqlite3_vfs
11f40 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
11f50 4e 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44 69  Name, int syncDi
11f60 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63 63  r);.  int (*xAcc
11f70 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ess)(sqlite3_vfs
11f80 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
11f90 4e 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c  Name, int flags,
11fa0 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a   int *pResOut);.
11fb0 20 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74    int (*xFullPat
11fc0 68 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76  hname)(sqlite3_v
11fd0 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
11fe0 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74  *zName, int nOut
11ff0 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20  , char *zOut);. 
12000 20 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e   void *(*xDlOpen
12010 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
12020 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c  const char *zFil
12030 65 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28  ename);.  void (
12040 2a 78 44 6c 45 72 72 6f 72 29 28 73 71 6c 69 74  *xDlError)(sqlit
12050 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79  e3_vfs*, int nBy
12060 74 65 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d 73  te, char *zErrMs
12070 67 29 3b 0a 20 20 76 6f 69 64 20 28 2a 28 2a 78  g);.  void (*(*x
12080 44 6c 53 79 6d 29 28 73 71 6c 69 74 65 33 5f 76  DlSym)(sqlite3_v
12090 66 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74  fs*,void*, const
120a0 20 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 29   char *zSymbol))
120b0 28 76 6f 69 64 29 3b 0a 20 20 76 6f 69 64 20 28  (void);.  void (
120c0 2a 78 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74  *xDlClose)(sqlit
120d0 65 33 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b  e3_vfs*, void*);
120e0 0a 20 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d  .  int (*xRandom
120f0 6e 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66  ness)(sqlite3_vf
12100 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63  s*, int nByte, c
12110 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e  har *zOut);.  in
12120 74 20 28 2a 78 53 6c 65 65 70 29 28 73 71 6c 69  t (*xSleep)(sqli
12130 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69  te3_vfs*, int mi
12140 63 72 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69  croseconds);.  i
12150 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d  nt (*xCurrentTim
12160 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  e)(sqlite3_vfs*,
12170 20 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74   double*);.  int
12180 20 28 2a 78 47 65 74 4c 61 73 74 45 72 72 6f 72   (*xGetLastError
12190 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
121a0 69 6e 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20  int, char *);.  
121b0 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68  /*.  ** The meth
121c0 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e  ods above are in
121d0 20 76 65 72 73 69 6f 6e 20 31 20 6f 66 20 74 68   version 1 of th
121e0 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a  e sqlite_vfs obj
121f0 65 63 74 0a 20 20 2a 2a 20 64 65 66 69 6e 69 74  ect.  ** definit
12200 69 6f 6e 2e 20 20 54 68 6f 73 65 20 74 68 61 74  ion.  Those that
12210 20 66 6f 6c 6c 6f 77 20 61 72 65 20 61 64 64 65   follow are adde
12220 64 20 69 6e 20 76 65 72 73 69 6f 6e 20 32 20 6f  d in version 2 o
12230 72 20 6c 61 74 65 72 0a 20 20 2a 2f 0a 20 20 69  r later.  */.  i
12240 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d  nt (*xCurrentTim
12250 65 49 6e 74 36 34 29 28 73 71 6c 69 74 65 33 5f  eInt64)(sqlite3_
12260 76 66 73 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  vfs*, sqlite3_in
12270 74 36 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a  t64*);.  /*.  **
12280 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f   The methods abo
12290 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f  ve are in versio
122a0 6e 73 20 31 20 61 6e 64 20 32 20 6f 66 20 74 68  ns 1 and 2 of th
122b0 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a  e sqlite_vfs obj
122c0 65 63 74 2e 0a 20 20 2a 2a 20 54 68 6f 73 65 20  ect..  ** Those 
122d0 62 65 6c 6f 77 20 61 72 65 20 66 6f 72 20 76 65  below are for ve
122e0 72 73 69 6f 6e 20 33 20 61 6e 64 20 67 72 65 61  rsion 3 and grea
122f0 74 65 72 2e 0a 20 20 2a 2f 0a 20 20 69 6e 74 20  ter..  */.  int 
12300 28 2a 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c  (*xSetSystemCall
12310 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
12320 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
12330 65 2c 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61  e, sqlite3_sysca
12340 6c 6c 5f 70 74 72 29 3b 0a 20 20 73 71 6c 69 74  ll_ptr);.  sqlit
12350 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 20 28  e3_syscall_ptr (
12360 2a 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 29  *xGetSystemCall)
12370 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
12380 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
12390 29 3b 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  );.  const char 
123a0 2a 28 2a 78 4e 65 78 74 53 79 73 74 65 6d 43 61  *(*xNextSystemCa
123b0 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ll)(sqlite3_vfs*
123c0 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
123d0 61 6d 65 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20  ame);.  /*.  ** 
123e0 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76  The methods abov
123f0 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e  e are in version
12400 73 20 31 20 74 68 72 6f 75 67 68 20 33 20 6f 66  s 1 through 3 of
12410 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20   the sqlite_vfs 
12420 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 4e 65 77  object..  ** New
12430 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61   fields may be a
12440 70 70 65 6e 64 65 64 20 69 6e 20 66 69 67 75 72  ppended in figur
12450 65 20 76 65 72 73 69 6f 6e 73 2e 20 20 54 68 65  e versions.  The
12460 20 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76   iVersion.  ** v
12470 61 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d  alue will increm
12480 65 6e 74 20 77 68 65 6e 65 76 65 72 20 74 68 69  ent whenever thi
12490 73 20 68 61 70 70 65 6e 73 2e 20 0a 20 20 2a 2f  s happens. .  */
124a0 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .};../*.** CAPI3
124b0 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74  REF: Flags for t
124c0 68 65 20 78 41 63 63 65 73 73 20 56 46 53 20 6d  he xAccess VFS m
124d0 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ethod.**.** Thes
124e0 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61  e integer consta
124f0 6e 74 73 20 63 61 6e 20 62 65 20 75 73 65 64 20  nts can be used 
12500 61 73 20 74 68 65 20 74 68 69 72 64 20 70 61 72  as the third par
12510 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65  ameter to.** the
12520 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20   xAccess method 
12530 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76  of an [sqlite3_v
12540 66 73 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 65  fs] object.  The
12550 79 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77  y determine.** w
12560 68 61 74 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d  hat kind of perm
12570 69 73 73 69 6f 6e 73 20 74 68 65 20 78 41 63 63  issions the xAcc
12580 65 73 73 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f  ess method is lo
12590 6f 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 69  oking for..** Wi
125a0 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  th SQLITE_ACCESS
125b0 5f 45 58 49 53 54 53 2c 20 74 68 65 20 78 41 63  _EXISTS, the xAc
125c0 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73  cess method.** s
125d0 69 6d 70 6c 79 20 63 68 65 63 6b 73 20 77 68 65  imply checks whe
125e0 74 68 65 72 20 74 68 65 20 66 69 6c 65 20 65 78  ther the file ex
125f0 69 73 74 73 2e 0a 2a 2a 20 57 69 74 68 20 53 51  ists..** With SQ
12600 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
12610 57 52 49 54 45 2c 20 74 68 65 20 78 41 63 63 65  WRITE, the xAcce
12620 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65  ss method.** che
12630 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20  cks whether the 
12640 6e 61 6d 65 64 20 64 69 72 65 63 74 6f 72 79 20  named directory 
12650 69 73 20 62 6f 74 68 20 72 65 61 64 61 62 6c 65  is both readable
12660 20 61 6e 64 20 77 72 69 74 61 62 6c 65 0a 2a 2a   and writable.**
12670 20 28 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73   (in other words
12680 2c 20 69 66 20 66 69 6c 65 73 20 63 61 6e 20 62  , if files can b
12690 65 20 61 64 64 65 64 2c 20 72 65 6d 6f 76 65 64  e added, removed
126a0 2c 20 61 6e 64 20 72 65 6e 61 6d 65 64 20 77 69  , and renamed wi
126b0 74 68 69 6e 0a 2a 2a 20 74 68 65 20 64 69 72 65  thin.** the dire
126c0 63 74 6f 72 79 29 2e 0a 2a 2a 20 54 68 65 20 53  ctory)..** The S
126d0 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
126e0 44 57 52 49 54 45 20 63 6f 6e 73 74 61 6e 74 20  DWRITE constant 
126f0 69 73 20 63 75 72 72 65 6e 74 6c 79 20 75 73 65  is currently use
12700 64 20 6f 6e 6c 79 20 62 79 20 74 68 65 0a 2a 2a  d only by the.**
12710 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72   [temp_store_dir
12720 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 2c 20  ectory pragma], 
12730 74 68 6f 75 67 68 20 74 68 69 73 20 63 6f 75 6c  though this coul
12740 64 20 63 68 61 6e 67 65 20 69 6e 20 61 20 66 75  d change in a fu
12750 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20  ture.** release 
12760 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 57 69  of SQLite..** Wi
12770 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  th SQLITE_ACCESS
12780 5f 52 45 41 44 2c 20 74 68 65 20 78 41 63 63 65  _READ, the xAcce
12790 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65  ss method.** che
127a0 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20  cks whether the 
127b0 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65  file is readable
127c0 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43  .  The SQLITE_AC
127d0 43 45 53 53 5f 52 45 41 44 20 63 6f 6e 73 74 61  CESS_READ consta
127e0 6e 74 20 69 73 0a 2a 2a 20 63 75 72 72 65 6e 74  nt is.** current
127f0 6c 79 20 75 6e 75 73 65 64 2c 20 74 68 6f 75 67  ly unused, thoug
12800 68 20 69 74 20 6d 69 67 68 74 20 62 65 20 75 73  h it might be us
12810 65 64 20 69 6e 20 61 20 66 75 74 75 72 65 20 72  ed in a future r
12820 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c  elease of.** SQL
12830 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ite..*/.#define 
12840 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58  SQLITE_ACCESS_EX
12850 49 53 54 53 20 20 20 20 30 0a 23 64 65 66 69 6e  ISTS    0.#defin
12860 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  e SQLITE_ACCESS_
12870 52 45 41 44 57 52 49 54 45 20 31 20 20 20 2f 2a  READWRITE 1   /*
12880 20 55 73 65 64 20 62 79 20 50 52 41 47 4d 41 20   Used by PRAGMA 
12890 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63  temp_store_direc
128a0 74 6f 72 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  tory */.#define 
128b0 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
128c0 41 44 20 20 20 20 20 20 32 20 20 20 2f 2a 20 55  AD      2   /* U
128d0 6e 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  nused */../*.** 
128e0 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20  CAPI3REF: Flags 
128f0 66 6f 72 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b  for the xShmLock
12900 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a   VFS method.**.*
12910 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20  * These integer 
12920 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65  constants define
12930 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c 6f 63   the various loc
12940 6b 69 6e 67 20 6f 70 65 72 61 74 69 6f 6e 73 0a  king operations.
12950 2a 2a 20 61 6c 6c 6f 77 65 64 20 62 79 20 74 68  ** allowed by th
12960 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f  e xShmLock metho
12970 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 69 6f  d of [sqlite3_io
12980 5f 6d 65 74 68 6f 64 73 5d 2e 20 20 54 68 65 0a  _methods].  The.
12990 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 72 65  ** following are
129a0 20 74 68 65 20 6f 6e 6c 79 20 6c 65 67 61 6c 20   the only legal 
129b0 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 6f 66 20  combinations of 
129c0 66 6c 61 67 73 20 74 6f 20 74 68 65 0a 2a 2a 20  flags to the.** 
129d0 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 3a  xShmLock method:
129e0 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
129f0 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f  li>  SQLITE_SHM_
12a00 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48  LOCK | SQLITE_SH
12a10 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e  M_SHARED.** <li>
12a20 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43    SQLITE_SHM_LOC
12a30 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45  K | SQLITE_SHM_E
12a40 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e  XCLUSIVE.** <li>
12a50 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c    SQLITE_SHM_UNL
12a60 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d  OCK | SQLITE_SHM
12a70 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20  _SHARED.** <li> 
12a80 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f   SQLITE_SHM_UNLO
12a90 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f  CK | SQLITE_SHM_
12aa0 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 2f 75  EXCLUSIVE.** </u
12ab0 6c 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 75 6e  l>.**.** When un
12ac0 6c 6f 63 6b 69 6e 67 2c 20 74 68 65 20 73 61 6d  locking, the sam
12ad0 65 20 53 48 41 52 45 44 20 6f 72 20 45 58 43 4c  e SHARED or EXCL
12ae0 55 53 49 56 45 20 66 6c 61 67 20 6d 75 73 74 20  USIVE flag must 
12af0 62 65 20 73 75 70 70 6c 69 65 64 20 61 73 0a 2a  be supplied as.*
12b00 2a 20 77 61 73 20 67 69 76 65 6e 20 6e 6f 20 74  * was given no t
12b10 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
12b20 20 6c 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20 54   lock.  .**.** T
12b30 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68  he xShmLock meth
12b40 6f 64 20 63 61 6e 20 74 72 61 6e 73 69 74 69 6f  od can transitio
12b50 6e 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b  n between unlock
12b60 65 64 20 61 6e 64 20 53 48 41 52 45 44 20 6f 72  ed and SHARED or
12b70 0a 2a 2a 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f  .** between unlo
12b80 63 6b 65 64 20 61 6e 64 20 45 58 43 4c 55 53 49  cked and EXCLUSI
12b90 56 45 2e 20 20 49 74 20 63 61 6e 6e 6f 74 20 74  VE.  It cannot t
12ba0 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65  ransition betwee
12bb0 6e 20 53 48 41 52 45 44 0a 2a 2a 20 61 6e 64 20  n SHARED.** and 
12bc0 45 58 43 4c 55 53 49 56 45 2e 0a 2a 2f 0a 23 64  EXCLUSIVE..*/.#d
12bd0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d  efine SQLITE_SHM
12be0 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 31 0a  _UNLOCK       1.
12bf0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
12c00 48 4d 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20  HM_LOCK         
12c10 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
12c20 5f 53 48 4d 5f 53 48 41 52 45 44 20 20 20 20 20  _SHM_SHARED     
12c30 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    4.#define SQLI
12c40 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45  TE_SHM_EXCLUSIVE
12c50 20 20 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50      8../*.** CAP
12c60 49 33 52 45 46 3a 20 4d 61 78 69 6d 75 6d 20 78  I3REF: Maximum x
12c70 53 68 6d 4c 6f 63 6b 20 69 6e 64 65 78 0a 2a 2a  ShmLock index.**
12c80 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b  .** The xShmLock
12c90 20 6d 65 74 68 6f 64 20 6f 6e 20 5b 73 71 6c 69   method on [sqli
12ca0 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
12cb0 6d 61 79 20 75 73 65 20 76 61 6c 75 65 73 0a 2a  may use values.*
12cc0 2a 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20  * between 0 and 
12cd0 74 68 69 73 20 75 70 70 65 72 20 62 6f 75 6e 64  this upper bound
12ce0 20 61 73 20 69 74 73 20 22 6f 66 66 73 65 74 22   as its "offset"
12cf0 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68   argument..** Th
12d00 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 77 69  e SQLite core wi
12d10 6c 6c 20 6e 65 76 65 72 20 61 74 74 65 6d 70 74  ll never attempt
12d20 20 74 6f 20 61 63 71 75 69 72 65 20 6f 72 20 72   to acquire or r
12d30 65 6c 65 61 73 65 20 61 0a 2a 2a 20 6c 6f 63 6b  elease a.** lock
12d40 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 69 73   outside of this
12d50 20 72 61 6e 67 65 0a 2a 2f 0a 23 64 65 66 69 6e   range.*/.#defin
12d60 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4e 4c 4f  e SQLITE_SHM_NLO
12d70 43 4b 20 20 20 20 20 20 20 20 38 0a 0a 0a 2f 2a  CK        8.../*
12d80 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e  .** CAPI3REF: In
12d90 69 74 69 61 6c 69 7a 65 20 54 68 65 20 53 51 4c  itialize The SQL
12da0 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a  ite Library.**.*
12db0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69  * ^The sqlite3_i
12dc0 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74  nitialize() rout
12dd0 69 6e 65 20 69 6e 69 74 69 61 6c 69 7a 65 73 20  ine initializes 
12de0 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69  the.** SQLite li
12df0 62 72 61 72 79 2e 20 20 5e 54 68 65 20 73 71 6c  brary.  ^The sql
12e00 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
12e10 72 6f 75 74 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c  routine.** deall
12e20 6f 63 61 74 65 73 20 61 6e 79 20 72 65 73 6f 75  ocates any resou
12e30 72 63 65 73 20 74 68 61 74 20 77 65 72 65 20 61  rces that were a
12e40 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69  llocated by sqli
12e50 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
12e60 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  ..** These routi
12e70 6e 65 73 20 61 72 65 20 64 65 73 69 67 6e 65 64  nes are designed
12e80 20 74 6f 20 61 69 64 20 69 6e 20 70 72 6f 63 65   to aid in proce
12e90 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  ss initializatio
12ea0 6e 20 61 6e 64 0a 2a 2a 20 73 68 75 74 64 6f 77  n and.** shutdow
12eb0 6e 20 6f 6e 20 65 6d 62 65 64 64 65 64 20 73 79  n on embedded sy
12ec0 73 74 65 6d 73 2e 20 20 57 6f 72 6b 73 74 61 74  stems.  Workstat
12ed0 69 6f 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  ion applications
12ee0 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 69 74 65   using.** SQLite
12ef0 20 6e 6f 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f 74   normally do not
12f00 20 6e 65 65 64 20 74 6f 20 69 6e 76 6f 6b 65 20   need to invoke 
12f10 65 69 74 68 65 72 20 6f 66 20 74 68 65 73 65 20  either of these 
12f20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20  routines..**.** 
12f30 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  A call to sqlite
12f40 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
12f50 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65 22  s an "effective"
12f60 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 0a 2a   call if it is.*
12f70 2a 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65  * the first time
12f80 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
12f90 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ize() is invoked
12fa0 20 64 75 72 69 6e 67 20 74 68 65 20 6c 69 66 65   during the life
12fb0 74 69 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20 70  time of.** the p
12fc0 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 69 74  rocess, or if it
12fd0 20 69 73 20 74 68 65 20 66 69 72 73 74 20 74 69   is the first ti
12fe0 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  me sqlite3_initi
12ff0 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b  alize() is invok
13000 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  ed.** following 
13010 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  a call to sqlite
13020 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 5e  3_shutdown().  ^
13030 28 4f 6e 6c 79 20 61 6e 20 65 66 66 65 63 74 69  (Only an effecti
13040 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71  ve call.** of sq
13050 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
13060 28 29 20 64 6f 65 73 20 61 6e 79 20 69 6e 69 74  () does any init
13070 69 61 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c  ialization.  All
13080 20 6f 74 68 65 72 20 63 61 6c 6c 73 0a 2a 2a 20   other calls.** 
13090 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d  are harmless no-
130a0 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 63  ops.)^.**.** A c
130b0 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
130c0 68 75 74 64 6f 77 6e 28 29 20 69 73 20 61 6e 20  hutdown() is an 
130d0 22 65 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c  "effective" call
130e0 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69   if it is the fi
130f0 72 73 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73  rst.** call to s
13100 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
13110 29 20 73 69 6e 63 65 20 74 68 65 20 6c 61 73 74  ) since the last
13120 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
13130 69 7a 65 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a 2a  ize().  ^(Only.*
13140 2a 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 63  * an effective c
13150 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
13160 68 75 74 64 6f 77 6e 28 29 20 64 6f 65 73 20 61  hutdown() does a
13170 6e 79 20 64 65 69 6e 69 74 69 61 6c 69 7a 61 74  ny deinitializat
13180 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68 65  ion..** All othe
13190 72 20 76 61 6c 69 64 20 63 61 6c 6c 73 20 74 6f  r valid calls to
131a0 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
131b0 6e 28 29 20 61 72 65 20 68 61 72 6d 6c 65 73 73  n() are harmless
131c0 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a   no-ops.)^.**.**
131d0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69   The sqlite3_ini
131e0 74 69 61 6c 69 7a 65 28 29 20 69 6e 74 65 72 66  tialize() interf
131f0 61 63 65 20 69 73 20 74 68 72 65 61 64 73 61 66  ace is threadsaf
13200 65 2c 20 62 75 74 20 73 71 6c 69 74 65 33 5f 73  e, but sqlite3_s
13210 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 69 73 20  hutdown().** is 
13220 6e 6f 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65  not.  The sqlite
13230 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 6e 74  3_shutdown() int
13240 65 72 66 61 63 65 20 6d 75 73 74 20 6f 6e 6c 79  erface must only
13250 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20   be called from 
13260 61 0a 2a 2a 20 73 69 6e 67 6c 65 20 74 68 72 65  a.** single thre
13270 61 64 2e 20 20 41 6c 6c 20 6f 70 65 6e 20 5b 64  ad.  All open [d
13280 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
13290 6f 6e 73 5d 20 6d 75 73 74 20 62 65 20 63 6c 6f  ons] must be clo
132a0 73 65 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20 6f  sed and all.** o
132b0 74 68 65 72 20 53 51 4c 69 74 65 20 72 65 73 6f  ther SQLite reso
132c0 75 72 63 65 73 20 6d 75 73 74 20 62 65 20 64 65  urces must be de
132d0 61 6c 6c 6f 63 61 74 65 64 20 70 72 69 6f 72 20  allocated prior 
132e0 74 6f 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73  to invoking.** s
132f0 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
13300 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f  )..**.** Among o
13310 74 68 65 72 20 74 68 69 6e 67 73 2c 20 5e 73 71  ther things, ^sq
13320 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
13330 28 29 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a  () will invoke.*
13340 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  * sqlite3_os_ini
13350 74 28 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c  t().  Similarly,
13360 20 5e 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f   ^sqlite3_shutdo
13370 77 6e 28 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e 76  wn().** will inv
13380 6f 6b 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  oke sqlite3_os_e
13390 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  nd()..**.** ^The
133a0 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
133b0 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65  ize() routine re
133c0 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
133d0 5d 20 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a  ] on success..**
133e0 20 5e 49 66 20 66 6f 72 20 73 6f 6d 65 20 72 65   ^If for some re
133f0 61 73 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ason, sqlite3_in
13400 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 75 6e  itialize() is un
13410 61 62 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c 69  able to initiali
13420 7a 65 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61 72  ze.** the librar
13430 79 20 28 70 65 72 68 61 70 73 20 69 74 20 69 73  y (perhaps it is
13440 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63   unable to alloc
13450 61 74 65 20 61 20 6e 65 65 64 65 64 20 72 65 73  ate a needed res
13460 6f 75 72 63 65 20 73 75 63 68 0a 2a 2a 20 61 73  ource such.** as
13470 20 61 20 6d 75 74 65 78 29 20 69 74 20 72 65 74   a mutex) it ret
13480 75 72 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20 63  urns an [error c
13490 6f 64 65 5d 20 6f 74 68 65 72 20 74 68 61 6e 20  ode] other than 
134a0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a  [SQLITE_OK]..**.
134b0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
134c0 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75  initialize() rou
134d0 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 69  tine is called i
134e0 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61 6e  nternally by man
134f0 79 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74  y other.** SQLit
13500 65 20 69 6e 74 65 72 66 61 63 65 73 20 73 6f 20  e interfaces so 
13510 74 68 61 74 20 61 6e 20 61 70 70 6c 69 63 61 74  that an applicat
13520 69 6f 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65 73  ion usually does
13530 20 6e 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a 20   not need to.** 
13540 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69  invoke sqlite3_i
13550 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65  nitialize() dire
13560 63 74 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d 70  ctly.  For examp
13570 6c 65 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  le, [sqlite3_ope
13580 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 71  n()].** calls sq
13590 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
135a0 28 29 20 73 6f 20 74 68 65 20 53 51 4c 69 74 65  () so the SQLite
135b0 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 62 65   library will be
135c0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a   automatically.*
135d0 2a 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 77 68  * initialized wh
135e0 65 6e 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  en [sqlite3_open
135f0 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 69 66  ()] is called if
13600 20 69 74 20 68 61 73 20 6e 6f 74 20 62 65 20 69   it has not be i
13610 6e 69 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c  nitialized.** al
13620 72 65 61 64 79 2e 20 20 5e 48 6f 77 65 76 65 72  ready.  ^However
13630 2c 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63  , if SQLite is c
13640 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65  ompiled with the
13650 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55   [SQLITE_OMIT_AU
13660 54 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69  TOINIT].** compi
13670 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20  le-time option, 
13680 74 68 65 6e 20 74 68 65 20 61 75 74 6f 6d 61 74  then the automat
13690 69 63 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  ic calls to sqli
136a0 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
136b0 0a 2a 2a 20 61 72 65 20 6f 6d 69 74 74 65 64 20  .** are omitted 
136c0 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 74  and the applicat
136d0 69 6f 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73 71  ion must call sq
136e0 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
136f0 28 29 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 70  () directly.** p
13700 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e  rior to using an
13710 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69  y other SQLite i
13720 6e 74 65 72 66 61 63 65 2e 20 20 46 6f 72 20 6d  nterface.  For m
13730 61 78 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c 69  aximum portabili
13740 74 79 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65 63  ty,.** it is rec
13750 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70  ommended that ap
13760 70 6c 69 63 61 74 69 6f 6e 73 20 61 6c 77 61 79  plications alway
13770 73 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33  s invoke sqlite3
13780 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a  _initialize().**
13790 20 64 69 72 65 63 74 6c 79 20 70 72 69 6f 72 20   directly prior 
137a0 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68  to using any oth
137b0 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
137c0 61 63 65 2e 20 20 46 75 74 75 72 65 20 72 65 6c  ace.  Future rel
137d0 65 61 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c 69  eases.** of SQLi
137e0 74 65 20 6d 61 79 20 72 65 71 75 69 72 65 20 74  te may require t
137f0 68 69 73 2e 20 20 49 6e 20 6f 74 68 65 72 20 77  his.  In other w
13800 6f 72 64 73 2c 20 74 68 65 20 62 65 68 61 76 69  ords, the behavi
13810 6f 72 20 65 78 68 69 62 69 74 65 64 0a 2a 2a 20  or exhibited.** 
13820 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63  when SQLite is c
13830 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51  ompiled with [SQ
13840 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e  LITE_OMIT_AUTOIN
13850 49 54 5d 20 6d 69 67 68 74 20 62 65 63 6f 6d 65  IT] might become
13860 20 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 20   the.** default 
13870 62 65 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d 65  behavior in some
13880 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20   future release 
13890 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a  of SQLite..**.**
138a0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f   The sqlite3_os_
138b0 69 6e 69 74 28 29 20 72 6f 75 74 69 6e 65 20 64  init() routine d
138c0 6f 65 73 20 6f 70 65 72 61 74 69 6e 67 2d 73 79  oes operating-sy
138d0 73 74 65 6d 20 73 70 65 63 69 66 69 63 0a 2a 2a  stem specific.**
138e0 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
138f0 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69  of the SQLite li
13900 62 72 61 72 79 2e 20 20 54 68 65 20 73 71 6c 69  brary.  The sqli
13910 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20  te3_os_end().** 
13920 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73 20 74  routine undoes t
13930 68 65 20 65 66 66 65 63 74 20 6f 66 20 73 71 6c  he effect of sql
13940 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20  ite3_os_init(). 
13950 20 54 79 70 69 63 61 6c 20 74 61 73 6b 73 0a 2a   Typical tasks.*
13960 2a 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20 74  * performed by t
13970 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 69 6e  hese routines in
13980 63 6c 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f 6e  clude allocation
13990 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e   or deallocation
139a0 0a 2a 2a 20 6f 66 20 73 74 61 74 69 63 20 72 65  .** of static re
139b0 73 6f 75 72 63 65 73 2c 20 69 6e 69 74 69 61 6c  sources, initial
139c0 69 7a 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 61  ization of globa
139d0 6c 20 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a 20  l variables,.** 
139e0 73 65 74 74 69 6e 67 20 75 70 20 61 20 64 65 66  setting up a def
139f0 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66  ault [sqlite3_vf
13a00 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 65  s] module, or se
13a10 74 74 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64 65  tting up.** a de
13a20 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74  fault configurat
13a30 69 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ion using [sqlit
13a40 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a  e3_config()]..**
13a50 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
13a60 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72  ion should never
13a70 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 73   invoke either s
13a80 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
13a90 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f  .** or sqlite3_o
13aa0 73 5f 65 6e 64 28 29 20 64 69 72 65 63 74 6c 79  s_end() directly
13ab0 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  .  The applicati
13ac0 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 69  on should only i
13ad0 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33  nvoke.** sqlite3
13ae0 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e  _initialize() an
13af0 64 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  d sqlite3_shutdo
13b00 77 6e 28 29 2e 20 20 54 68 65 20 73 71 6c 69 74  wn().  The sqlit
13b10 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20  e3_os_init().** 
13b20 69 6e 74 65 72 66 61 63 65 20 69 73 20 63 61 6c  interface is cal
13b30 6c 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  led automaticall
13b40 79 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69  y by sqlite3_ini
13b50 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a 2a  tialize() and.**
13b60 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
13b70 29 20 69 73 20 63 61 6c 6c 65 64 20 62 79 20 73  ) is called by s
13b80 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
13b90 29 2e 20 20 41 70 70 72 6f 70 72 69 61 74 65 0a  ).  Appropriate.
13ba0 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
13bb0 6e 73 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  ns for sqlite3_o
13bc0 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c  s_init() and sql
13bd0 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a  ite3_os_end().**
13be0 20 61 72 65 20 62 75 69 6c 74 20 69 6e 74 6f 20   are built into 
13bf0 53 51 4c 69 74 65 20 77 68 65 6e 20 69 74 20 69  SQLite when it i
13c00 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 55  s compiled for U
13c10 6e 69 78 2c 20 57 69 6e 64 6f 77 73 2c 20 6f 72  nix, Windows, or
13c20 20 4f 53 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 5b   OS/2..** When [
13c30 63 75 73 74 6f 6d 20 62 75 69 6c 64 73 20 7c 20  custom builds | 
13c40 62 75 69 6c 74 20 66 6f 72 20 6f 74 68 65 72 20  built for other 
13c50 70 6c 61 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28 75  platforms].** (u
13c60 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45  sing the [SQLITE
13c70 5f 4f 53 5f 4f 54 48 45 52 3d 31 5d 20 63 6f 6d  _OS_OTHER=1] com
13c80 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74  pile-time.** opt
13c90 69 6f 6e 29 20 74 68 65 20 61 70 70 6c 69 63 61  ion) the applica
13ca0 74 69 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c 79  tion must supply
13cb0 20 61 20 73 75 69 74 61 62 6c 65 20 69 6d 70 6c   a suitable impl
13cc0 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a  ementation for.*
13cd0 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  * sqlite3_os_ini
13ce0 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  t() and sqlite3_
13cf0 6f 73 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61 70  os_end().  An ap
13d00 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69  plication-suppli
13d10 65 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  ed.** implementa
13d20 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f  tion of sqlite3_
13d30 6f 73 5f 69 6e 69 74 28 29 20 6f 72 20 73 71 6c  os_init() or sql
13d40 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a  ite3_os_end().**
13d50 20 6d 75 73 74 20 72 65 74 75 72 6e 20 5b 53 51   must return [SQ
13d60 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63  LITE_OK] on succ
13d70 65 73 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74 68  ess and some oth
13d80 65 72 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  er [error code] 
13d90 75 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 2e  upon.** failure.
13da0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
13db0 6e 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  nt sqlite3_initi
13dc0 61 6c 69 7a 65 28 76 6f 69 64 29 3b 0a 53 51 4c  alize(void);.SQL
13dd0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
13de0 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 76 6f 69  te3_shutdown(voi
13df0 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  d);.SQLITE_API i
13e00 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  nt sqlite3_os_in
13e10 69 74 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45  it(void);.SQLITE
13e20 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
13e30 5f 6f 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a  _os_end(void);..
13e40 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
13e50 43 6f 6e 66 69 67 75 72 69 6e 67 20 54 68 65 20  Configuring The 
13e60 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a  SQLite Library.*
13e70 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
13e80 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66  _config() interf
13e90 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d  ace is used to m
13ea0 61 6b 65 20 67 6c 6f 62 61 6c 20 63 6f 6e 66 69  ake global confi
13eb0 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e  guration.** chan
13ec0 67 65 73 20 74 6f 20 53 51 4c 69 74 65 20 69 6e  ges to SQLite in
13ed0 20 6f 72 64 65 72 20 74 6f 20 74 75 6e 65 20 53   order to tune S
13ee0 51 4c 69 74 65 20 74 6f 20 74 68 65 20 73 70 65  QLite to the spe
13ef0 63 69 66 69 63 20 6e 65 65 64 73 20 6f 66 0a 2a  cific needs of.*
13f00 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * the applicatio
13f10 6e 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20  n.  The default 
13f20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 69 73  configuration is
13f30 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72   recommended for
13f40 20 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61   most.** applica
13f50 74 69 6f 6e 73 20 61 6e 64 20 73 6f 20 74 68 69  tions and so thi
13f60 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75 73 75  s routine is usu
13f70 61 6c 6c 79 20 6e 6f 74 20 6e 65 63 65 73 73 61  ally not necessa
13f80 72 79 2e 20 20 49 74 20 69 73 0a 2a 2a 20 70 72  ry.  It is.** pr
13f90 6f 76 69 64 65 64 20 74 6f 20 73 75 70 70 6f 72  ovided to suppor
13fa0 74 20 72 61 72 65 20 61 70 70 6c 69 63 61 74 69  t rare applicati
13fb0 6f 6e 73 20 77 69 74 68 20 75 6e 75 73 75 61 6c  ons with unusual
13fc0 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68   needs..**.** Th
13fd0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  e sqlite3_config
13fe0 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
13ff0 6e 6f 74 20 74 68 72 65 61 64 73 61 66 65 2e 20  not threadsafe. 
14000 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
14010 0a 2a 2a 20 6d 75 73 74 20 69 6e 73 75 72 65 20  .** must insure 
14020 74 68 61 74 20 6e 6f 20 6f 74 68 65 72 20 53 51  that no other SQ
14030 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20  Lite interfaces 
14040 61 72 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 6f  are invoked by o
14050 74 68 65 72 0a 2a 2a 20 74 68 72 65 61 64 73 20  ther.** threads 
14060 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f  while sqlite3_co
14070 6e 66 69 67 28 29 20 69 73 20 72 75 6e 6e 69 6e  nfig() is runnin
14080 67 2e 20 20 46 75 72 74 68 65 72 6d 6f 72 65 2c  g.  Furthermore,
14090 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
140a0 29 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65  ).** may only be
140b0 20 69 6e 76 6f 6b 65 64 20 70 72 69 6f 72 20 74   invoked prior t
140c0 6f 20 6c 69 62 72 61 72 79 20 69 6e 69 74 69 61  o library initia
140d0 6c 69 7a 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a  lization using.*
140e0 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  * [sqlite3_initi
140f0 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65  alize()] or afte
14100 72 20 73 68 75 74 64 6f 77 6e 20 62 79 20 5b 73  r shutdown by [s
14110 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
14120 29 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74  )]..** ^If sqlit
14130 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 63  e3_config() is c
14140 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c  alled after [sql
14150 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
14160 29 5d 20 61 6e 64 20 62 65 66 6f 72 65 0a 2a 2a  )] and before.**
14170 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f   [sqlite3_shutdo
14180 77 6e 28 29 5d 20 74 68 65 6e 20 69 74 20 77 69  wn()] then it wi
14190 6c 6c 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45  ll return SQLITE
141a0 5f 4d 49 53 55 53 45 2e 0a 2a 2a 20 4e 6f 74 65  _MISUSE..** Note
141b0 2c 20 68 6f 77 65 76 65 72 2c 20 74 68 61 74 20  , however, that 
141c0 5e 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  ^sqlite3_config(
141d0 29 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20  ) can be called 
141e0 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 0a 2a  as part of the.*
141f0 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
14200 20 6f 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69   of an applicati
14210 6f 6e 2d 64 65 66 69 6e 65 64 20 5b 73 71 6c 69  on-defined [sqli
14220 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a  te3_os_init()]..
14230 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
14240 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
14250 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20  te3_config() is 
14260 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 63  an integer.** [c
14270 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
14280 69 6f 6e 5d 20 74 68 61 74 20 64 65 74 65 72 6d  ion] that determ
14290 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20 70 72 6f  ines.** what pro
142a0 70 65 72 74 79 20 6f 66 20 53 51 4c 69 74 65 20  perty of SQLite 
142b0 69 73 20 74 6f 20 62 65 20 63 6f 6e 66 69 67 75  is to be configu
142c0 72 65 64 2e 20 20 53 75 62 73 65 71 75 65 6e 74  red.  Subsequent
142d0 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 76 61   arguments.** va
142e0 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  ry depending on 
142f0 74 68 65 20 5b 63 6f 6e 66 69 67 75 72 61 74 69  the [configurati
14300 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e  on option].** in
14310 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
14320 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e  ent..**.** ^When
14330 20 61 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e   a configuration
14340 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 2c 20   option is set, 
14350 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
14360 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
14370 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  _OK]..** ^If the
14380 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f   option is unkno
14390 77 6e 20 6f 72 20 53 51 4c 69 74 65 20 69 73 20  wn or SQLite is 
143a0 75 6e 61 62 6c 65 20 74 6f 20 73 65 74 20 74 68  unable to set th
143b0 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e  e option.** then
143c0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65   this routine re
143d0 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f  turns a non-zero
143e0 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a   [error code]..*
143f0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
14400 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
14410 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a  int, ...);../*.*
14420 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66  * CAPI3REF: Conf
14430 69 67 75 72 65 20 64 61 74 61 62 61 73 65 20 63  igure database c
14440 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a  onnections.**.**
14450 20 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f   The sqlite3_db_
14460 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61  config() interfa
14470 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61  ce is used to ma
14480 6b 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ke configuration
14490 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 61  .** changes to a
144a0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
144b0 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 69 6e 74  ction].  The int
144c0 65 72 66 61 63 65 20 69 73 20 73 69 6d 69 6c 61  erface is simila
144d0 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  r to.** [sqlite3
144e0 5f 63 6f 6e 66 69 67 28 29 5d 20 65 78 63 65 70  _config()] excep
144f0 74 20 74 68 61 74 20 74 68 65 20 63 68 61 6e 67  t that the chang
14500 65 73 20 61 70 70 6c 79 20 74 6f 20 61 20 73 69  es apply to a si
14510 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73  ngle.** [databas
14520 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 73  e connection] (s
14530 70 65 63 69 66 69 65 64 20 69 6e 20 74 68 65 20  pecified in the 
14540 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 29 2e  first argument).
14550 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  .**.** The secon
14560 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  d argument to sq
14570 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
14580 44 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 74 68 65  D,V,...)  is the
14590 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f  .** [SQLITE_DBCO
145a0 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 7c  NFIG_LOOKASIDE |
145b0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76   configuration v
145c0 65 72 62 5d 20 2d 20 61 6e 20 69 6e 74 65 67 65  erb] - an intege
145d0 72 20 63 6f 64 65 20 0a 2a 2a 20 74 68 61 74 20  r code .** that 
145e0 69 6e 64 69 63 61 74 65 73 20 77 68 61 74 20 61  indicates what a
145f0 73 70 65 63 74 20 6f 66 20 74 68 65 20 5b 64 61  spect of the [da
14600 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
14610 6e 5d 20 69 73 20 62 65 69 6e 67 20 63 6f 6e 66  n] is being conf
14620 69 67 75 72 65 64 2e 0a 2a 2a 20 53 75 62 73 65  igured..** Subse
14630 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 20  quent arguments 
14640 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f  vary depending o
14650 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74  n the configurat
14660 69 6f 6e 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20  ion verb..**.** 
14670 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65  ^Calls to sqlite
14680 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 72 65  3_db_config() re
14690 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69  turn SQLITE_OK i
146a0 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a  f and only if.**
146b0 20 74 68 65 20 63 61 6c 6c 20 69 73 20 63 6f 6e   the call is con
146c0 73 69 64 65 72 65 64 20 73 75 63 63 65 73 73 66  sidered successf
146d0 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  ul..*/.SQLITE_AP
146e0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 62  I int sqlite3_db
146f0 5f 63 6f 6e 66 69 67 28 73 71 6c 69 74 65 33 2a  _config(sqlite3*
14700 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a  , int op, ...);.
14710 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
14720 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69   Memory Allocati
14730 6f 6e 20 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a  on Routines.**.*
14740 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  * An instance of
14750 20 74 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66   this object def
14760 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66 61  ines the interfa
14770 63 65 20 62 65 74 77 65 65 6e 20 53 51 4c 69 74  ce between SQLit
14780 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76  e.** and low-lev
14790 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  el memory alloca
147a0 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  tion routines..*
147b0 2a 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74  *.** This object
147c0 20 69 73 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79   is used in only
147d0 20 6f 6e 65 20 70 6c 61 63 65 20 69 6e 20 74 68   one place in th
147e0 65 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  e SQLite interfa
147f0 63 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72  ce..** A pointer
14800 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20   to an instance 
14810 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69  of this object i
14820 73 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74  s the argument t
14830 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  o.** [sqlite3_co
14840 6e 66 69 67 28 29 5d 20 77 68 65 6e 20 74 68 65  nfig()] when the
14850 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
14860 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c  ption is.** [SQL
14870 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
14880 43 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f  C] or [SQLITE_CO
14890 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e  NFIG_GETMALLOC].
148a0 20 20 0a 2a 2a 20 42 79 20 63 72 65 61 74 69 6e    .** By creatin
148b0 67 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  g an instance of
148c0 20 74 68 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20   this object.** 
148d0 61 6e 64 20 70 61 73 73 69 6e 67 20 69 74 20 74  and passing it t
148e0 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  o [sqlite3_confi
148f0 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  g]([SQLITE_CONFI
14900 47 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75  G_MALLOC]).** du
14910 72 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69  ring configurati
14920 6f 6e 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69  on, an applicati
14930 6f 6e 20 63 61 6e 20 73 70 65 63 69 66 79 20 61  on can specify a
14940 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a  n alternative.**
14950 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
14960 6f 6e 20 73 75 62 73 79 73 74 65 6d 20 66 6f 72  on subsystem for
14970 20 53 51 4c 69 74 65 20 74 6f 20 75 73 65 20 66   SQLite to use f
14980 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a  or all of its.**
14990 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20   dynamic memory 
149a0 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74  needs..**.** Not
149b0 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 6f  e that SQLite co
149c0 6d 65 73 20 77 69 74 68 20 73 65 76 65 72 61 6c  mes with several
149d0 20 5b 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72   [built-in memor
149e0 79 20 61 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a  y allocators].**
149f0 20 74 68 61 74 20 61 72 65 20 70 65 72 66 65 63   that are perfec
14a00 74 6c 79 20 61 64 65 71 75 61 74 65 20 66 6f 72  tly adequate for
14a10 20 74 68 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e   the overwhelmin
14a20 67 20 6d 61 6a 6f 72 69 74 79 20 6f 66 20 61 70  g majority of ap
14a30 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e  plications.** an
14a40 64 20 74 68 61 74 20 74 68 69 73 20 6f 62 6a 65  d that this obje
14a50 63 74 20 69 73 20 6f 6e 6c 79 20 75 73 65 66 75  ct is only usefu
14a60 6c 20 74 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f  l to a tiny mino
14a70 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74  rity of applicat
14a80 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 20 73 70 65  ions.** with spe
14a90 63 69 61 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20  cialized memory 
14aa0 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 69  allocation requi
14ab0 72 65 6d 65 6e 74 73 2e 20 20 54 68 69 73 20 6f  rements.  This o
14ac0 62 6a 65 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f  bject is.** also
14ad0 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73   used during tes
14ae0 74 69 6e 67 20 6f 66 20 53 51 4c 69 74 65 20 69  ting of SQLite i
14af0 6e 20 6f 72 64 65 72 20 74 6f 20 73 70 65 63 69  n order to speci
14b00 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76  fy an alternativ
14b10 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  e.** memory allo
14b20 63 61 74 6f 72 20 74 68 61 74 20 73 69 6d 75 6c  cator that simul
14b30 61 74 65 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d  ates memory out-
14b40 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74  of-memory condit
14b50 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72  ions in.** order
14b60 20 74 6f 20 76 65 72 69 66 79 20 74 68 61 74 20   to verify that 
14b70 53 51 4c 69 74 65 20 72 65 63 6f 76 65 72 73 20  SQLite recovers 
14b80 67 72 61 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20  gracefully from 
14b90 73 75 63 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f  such.** conditio
14ba0 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d  ns..**.** The xM
14bb0 61 6c 6c 6f 63 2c 20 78 52 65 61 6c 6c 6f 63 2c  alloc, xRealloc,
14bc0 20 61 6e 64 20 78 46 72 65 65 20 6d 65 74 68 6f   and xFree metho
14bd0 64 73 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b  ds must work lik
14be0 65 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28  e the.** malloc(
14bf0 29 2c 20 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64  ), realloc() and
14c00 20 66 72 65 65 28 29 20 66 75 6e 63 74 69 6f 6e   free() function
14c10 73 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64  s from the stand
14c20 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a  ard C library..*
14c30 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e  * ^SQLite guaran
14c40 74 65 65 73 20 74 68 61 74 20 74 68 65 20 73 65  tees that the se
14c50 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
14c60 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 69 73 20  .** xRealloc is 
14c70 61 6c 77 61 79 73 20 61 20 76 61 6c 75 65 20 72  always a value r
14c80 65 74 75 72 6e 65 64 20 62 79 20 61 20 70 72 69  eturned by a pri
14c90 6f 72 20 63 61 6c 6c 20 74 6f 20 78 52 6f 75 6e  or call to xRoun
14ca0 64 75 70 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65  dup..**.** xSize
14cb0 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 74   should return t
14cc0 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a  he allocated siz
14cd0 65 20 6f 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c  e of a memory al
14ce0 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70 72 65 76  location.** prev
14cf0 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20  iously obtained 
14d00 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72 20  from xMalloc or 
14d10 78 52 65 61 6c 6c 6f 63 2e 20 20 54 68 65 20 61  xRealloc.  The a
14d20 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 0a 2a 2a  llocated size.**
14d30 20 69 73 20 61 6c 77 61 79 73 20 61 74 20 6c 65   is always at le
14d40 61 73 74 20 61 73 20 62 69 67 20 61 73 20 74 68  ast as big as th
14d50 65 20 72 65 71 75 65 73 74 65 64 20 73 69 7a 65  e requested size
14d60 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67   but may be larg
14d70 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52  er..**.** The xR
14d80 6f 75 6e 64 75 70 20 6d 65 74 68 6f 64 20 72 65  oundup method re
14d90 74 75 72 6e 73 20 77 68 61 74 20 77 6f 75 6c 64  turns what would
14da0 20 62 65 20 74 68 65 20 61 6c 6c 6f 63 61 74 65   be the allocate
14db0 64 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d  d size of.** a m
14dc0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
14dd0 20 67 69 76 65 6e 20 61 20 70 61 72 74 69 63 75   given a particu
14de0 6c 61 72 20 72 65 71 75 65 73 74 65 64 20 73 69  lar requested si
14df0 7a 65 2e 20 20 4d 6f 73 74 20 6d 65 6d 6f 72 79  ze.  Most memory
14e00 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72  .** allocators r
14e10 6f 75 6e 64 20 75 70 20 6d 65 6d 6f 72 79 20 61  ound up memory a
14e20 6c 6c 6f 63 61 74 69 6f 6e 73 20 61 74 20 6c 65  llocations at le
14e30 61 73 74 20 74 6f 20 74 68 65 20 6e 65 78 74 20  ast to the next 
14e40 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f 66 20 38  multiple.** of 8
14e50 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f  .  Some allocato
14e60 72 73 20 72 6f 75 6e 64 20 75 70 20 74 6f 20 61  rs round up to a
14e70 20 6c 61 72 67 65 72 20 6d 75 6c 74 69 70 6c 65   larger multiple
14e80 20 6f 72 20 74 6f 20 61 20 70 6f 77 65 72 20 6f   or to a power o
14e90 66 20 32 2e 0a 2a 2a 20 45 76 65 72 79 20 6d 65  f 2..** Every me
14ea0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
14eb0 72 65 71 75 65 73 74 20 63 6f 6d 69 6e 67 20 69  request coming i
14ec0 6e 20 74 68 72 6f 75 67 68 20 5b 73 71 6c 69 74  n through [sqlit
14ed0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20  e3_malloc()].** 
14ee0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  or [sqlite3_real
14ef0 6c 6f 63 28 29 5d 20 66 69 72 73 74 20 63 61 6c  loc()] first cal
14f00 6c 73 20 78 52 6f 75 6e 64 75 70 2e 20 20 49 66  ls xRoundup.  If
14f10 20 78 52 6f 75 6e 64 75 70 20 72 65 74 75 72 6e   xRoundup return
14f20 73 20 30 2c 20 0a 2a 2a 20 74 68 61 74 20 63 61  s 0, .** that ca
14f30 75 73 65 73 20 74 68 65 20 63 6f 72 72 65 73 70  uses the corresp
14f40 6f 6e 64 69 6e 67 20 6d 65 6d 6f 72 79 20 61 6c  onding memory al
14f50 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 66 61 69 6c  location to fail
14f60 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69  ..**.** The xIni
14f70 74 20 6d 65 74 68 6f 64 20 69 6e 69 74 69 61 6c  t method initial
14f80 69 7a 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20  izes the memory 
14f90 61 6c 6c 6f 63 61 74 6f 72 2e 20 20 28 46 6f 72  allocator.  (For
14fa0 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20   example,.** it 
14fb0 6d 69 67 68 74 20 61 6c 6c 6f 63 61 74 65 20 61  might allocate a
14fc0 6e 79 20 72 65 71 75 69 72 65 20 6d 75 74 65 78  ny require mutex
14fd0 65 73 20 6f 72 20 69 6e 69 74 69 61 6c 69 7a 65  es or initialize
14fe0 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 0a 2a   internal data.*
14ff0 2a 20 73 74 72 75 63 74 75 72 65 73 2e 20 20 54  * structures.  T
15000 68 65 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74  he xShutdown met
15010 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 28  hod is invoked (
15020 69 6e 64 69 72 65 63 74 6c 79 29 20 62 79 0a 2a  indirectly) by.*
15030 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64  * [sqlite3_shutd
15040 6f 77 6e 28 29 5d 20 61 6e 64 20 73 68 6f 75 6c  own()] and shoul
15050 64 20 64 65 61 6c 6c 6f 63 61 74 65 20 61 6e 79  d deallocate any
15060 20 72 65 73 6f 75 72 63 65 73 20 61 63 71 75 69   resources acqui
15070 72 65 64 0a 2a 2a 20 62 79 20 78 49 6e 69 74 2e  red.** by xInit.
15080 20 20 54 68 65 20 70 41 70 70 44 61 74 61 20 70    The pAppData p
15090 6f 69 6e 74 65 72 20 69 73 20 75 73 65 64 20 61  ointer is used a
150a0 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d  s the only param
150b0 65 74 65 72 20 74 6f 0a 2a 2a 20 78 49 6e 69 74  eter to.** xInit
150c0 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 2e 0a   and xShutdown..
150d0 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 68 6f 6c  **.** SQLite hol
150e0 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d  ds the [SQLITE_M
150f0 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 41 53 54  UTEX_STATIC_MAST
15100 45 52 5d 20 6d 75 74 65 78 20 77 68 65 6e 20 69  ER] mutex when i
15110 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 74 68 65  t invokes.** the
15120 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 2c 20 73   xInit method, s
15130 6f 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68  o the xInit meth
15140 6f 64 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 74  od need not be t
15150 68 72 65 61 64 73 61 66 65 2e 20 20 54 68 65 0a  hreadsafe.  The.
15160 2a 2a 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74  ** xShutdown met
15170 68 6f 64 20 69 73 20 6f 6e 6c 79 20 63 61 6c 6c  hod is only call
15180 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
15190 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 73 6f 20  _shutdown()] so 
151a0 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 6e  it does.** not n
151b0 65 65 64 20 74 6f 20 62 65 20 74 68 72 65 61 64  eed to be thread
151c0 73 61 66 65 20 65 69 74 68 65 72 2e 20 20 46 6f  safe either.  Fo
151d0 72 20 61 6c 6c 20 6f 74 68 65 72 20 6d 65 74 68  r all other meth
151e0 6f 64 73 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 68  ods, SQLite.** h
151f0 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45  olds the [SQLITE
15200 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 45  _MUTEX_STATIC_ME
15210 4d 5d 20 6d 75 74 65 78 20 61 73 20 6c 6f 6e 67  M] mutex as long
15220 20 61 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49   as the.** [SQLI
15230 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41  TE_CONFIG_MEMSTA
15240 54 55 53 5d 20 63 6f 6e 66 69 67 75 72 61 74 69  TUS] configurati
15250 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 74 75 72  on option is tur
15260 6e 65 64 20 6f 6e 20 28 77 68 69 63 68 0a 2a 2a  ned on (which.**
15270 20 69 74 20 69 73 20 62 79 20 64 65 66 61 75 6c   it is by defaul
15280 74 29 20 61 6e 64 20 73 6f 20 74 68 65 20 6d 65  t) and so the me
15290 74 68 6f 64 73 20 61 72 65 20 61 75 74 6f 6d 61  thods are automa
152a0 74 69 63 61 6c 6c 79 20 73 65 72 69 61 6c 69 7a  tically serializ
152b0 65 64 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20  ed..** However, 
152c0 69 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  if [SQLITE_CONFI
152d0 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 69 73 20  G_MEMSTATUS] is 
152e0 64 69 73 61 62 6c 65 64 2c 20 74 68 65 6e 20 74  disabled, then t
152f0 68 65 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 74 68  he other.** meth
15300 6f 64 73 20 6d 75 73 74 20 62 65 20 74 68 72 65  ods must be thre
15310 61 64 73 61 66 65 20 6f 72 20 65 6c 73 65 20 6d  adsafe or else m
15320 61 6b 65 20 74 68 65 69 72 20 6f 77 6e 20 61 72  ake their own ar
15330 72 61 6e 67 65 6d 65 6e 74 73 20 66 6f 72 0a 2a  rangements for.*
15340 2a 20 73 65 72 69 61 6c 69 7a 61 74 69 6f 6e 2e  * serialization.
15350 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69  .**.** SQLite wi
15360 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20  ll never invoke 
15370 78 49 6e 69 74 28 29 20 6d 6f 72 65 20 74 68 61  xInit() more tha
15380 6e 20 6f 6e 63 65 20 77 69 74 68 6f 75 74 20 61  n once without a
15390 6e 20 69 6e 74 65 72 76 65 6e 69 6e 67 0a 2a 2a  n intervening.**
153a0 20 63 61 6c 6c 20 74 6f 20 78 53 68 75 74 64 6f   call to xShutdo
153b0 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  wn()..*/.typedef
153c0 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
153d0 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69  mem_methods sqli
153e0 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b  te3_mem_methods;
153f0 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
15400 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20  mem_methods {.  
15410 76 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29  void *(*xMalloc)
15420 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 2f  (int);         /
15430 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  * Memory allocat
15440 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a  ion function */.
15450 20 20 76 6f 69 64 20 28 2a 78 46 72 65 65 29 28    void (*xFree)(
15460 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20  void*);         
15470 20 2f 2a 20 46 72 65 65 20 61 20 70 72 69 6f 72   /* Free a prior
15480 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20   allocation */. 
15490 20 76 6f 69 64 20 2a 28 2a 78 52 65 61 6c 6c 6f   void *(*xReallo
154a0 63 29 28 76 6f 69 64 2a 2c 69 6e 74 29 3b 20 20  c)(void*,int);  
154b0 2f 2a 20 52 65 73 69 7a 65 20 61 6e 20 61 6c 6c  /* Resize an all
154c0 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74  ocation */.  int
154d0 20 28 2a 78 53 69 7a 65 29 28 76 6f 69 64 2a 29   (*xSize)(void*)
154e0 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52  ;           /* R
154f0 65 74 75 72 6e 20 74 68 65 20 73 69 7a 65 20 6f  eturn the size o
15500 66 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  f an allocation 
15510 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 52 6f 75 6e  */.  int (*xRoun
15520 64 75 70 29 28 69 6e 74 29 3b 20 20 20 20 20 20  dup)(int);      
15530 20 20 20 20 2f 2a 20 52 6f 75 6e 64 20 75 70 20      /* Round up 
15540 72 65 71 75 65 73 74 20 73 69 7a 65 20 74 6f 20  request size to 
15550 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20  allocation size 
15560 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 49 6e 69 74  */.  int (*xInit
15570 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20  )(void*);       
15580 20 20 20 20 2f 2a 20 49 6e 69 74 69 61 6c 69 7a      /* Initializ
15590 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  e the memory all
155a0 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64  ocator */.  void
155b0 20 28 2a 78 53 68 75 74 64 6f 77 6e 29 28 76 6f   (*xShutdown)(vo
155c0 69 64 2a 29 3b 20 20 20 20 20 20 2f 2a 20 44 65  id*);      /* De
155d0 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d  initialize the m
155e0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20  emory allocator 
155f0 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44  */.  void *pAppD
15600 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 20 20  ata;            
15610 20 20 20 20 2f 2a 20 41 72 67 75 6d 65 6e 74 20      /* Argument 
15620 74 6f 20 78 49 6e 69 74 28 29 20 61 6e 64 20 78  to xInit() and x
15630 53 68 75 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b  Shutdown() */.};
15640 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
15650 3a 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  : Configuration 
15660 4f 70 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f  Options.** KEYWO
15670 52 44 53 3a 20 7b 63 6f 6e 66 69 67 75 72 61 74  RDS: {configurat
15680 69 6f 6e 20 6f 70 74 69 6f 6e 7d 0a 2a 2a 0a 2a  ion option}.**.*
15690 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
156a0 73 20 61 72 65 20 74 68 65 20 61 76 61 69 6c 61  s are the availa
156b0 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66  ble integer conf
156c0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
156d0 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65  s that.** can be
156e0 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66   passed as the f
156f0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
15700 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   the [sqlite3_co
15710 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63  nfig()] interfac
15720 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e  e..**.** New con
15730 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
15740 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20  ns may be added 
15750 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
15760 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  es of SQLite..**
15770 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67   Existing config
15780 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
15790 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74  might be discont
157a0 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74  inued.  Applicat
157b0 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63  ions.** should c
157c0 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20  heck the return 
157d0 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74  code from [sqlit
157e0 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20  e3_config()] to 
157f0 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a  make sure that.*
15800 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65  * the call worke
15810 64 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  d.  The [sqlite3
15820 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72  _config()] inter
15830 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e  face will return
15840 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b   a.** non-zero [
15850 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61  error code] if a
15860 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72   discontinued or
15870 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e   unsupported con
15880 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
15890 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e  n.** is invoked.
158a0 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b  .**.** <dl>.** [
158b0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
158c0 49 4e 47 4c 45 54 48 52 45 41 44 5d 5d 20 3c 64  INGLETHREAD]] <d
158d0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
158e0 53 49 4e 47 4c 45 54 48 52 45 41 44 3c 2f 64 74  SINGLETHREAD</dt
158f0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61  >.** <dd>There a
15900 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20  re no arguments 
15910 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20  to this option. 
15920 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65   ^This option se
15930 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61  ts the.** [threa
15940 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 69  ding mode] to Si
15950 6e 67 6c 65 2d 74 68 72 65 61 64 2e 20 20 49 6e  ngle-thread.  In
15960 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74   other words, it
15970 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c   disables.** all
15980 20 6d 75 74 65 78 69 6e 67 20 61 6e 64 20 70 75   mutexing and pu
15990 74 73 20 53 51 4c 69 74 65 20 69 6e 74 6f 20 61  ts SQLite into a
159a0 20 6d 6f 64 65 20 77 68 65 72 65 20 69 74 20 63   mode where it c
159b0 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 0a  an only be used.
159c0 2a 2a 20 62 79 20 61 20 73 69 6e 67 6c 65 20 74  ** by a single t
159d0 68 72 65 61 64 2e 20 20 20 5e 49 66 20 53 51 4c  hread.   ^If SQL
159e0 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
159f0 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c  with.** the [SQL
15a00 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c  ITE_THREADSAFE |
15a10 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41   SQLITE_THREADSA
15a20 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  FE=0] compile-ti
15a30 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a  me option then.*
15a40 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73  * it is not poss
15a50 69 62 6c 65 20 74 6f 20 63 68 61 6e 67 65 20 74  ible to change t
15a60 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  he [threading mo
15a70 64 65 5d 20 66 72 6f 6d 20 69 74 73 20 64 65 66  de] from its def
15a80 61 75 6c 74 0a 2a 2a 20 76 61 6c 75 65 20 6f 66  ault.** value of
15a90 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 61   Single-thread a
15aa0 6e 64 20 73 6f 20 5b 73 71 6c 69 74 65 33 5f 63  nd so [sqlite3_c
15ab0 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65  onfig()] will re
15ac0 74 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 45  turn .** [SQLITE
15ad0 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65  _ERROR] if calle
15ae0 64 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54  d with the SQLIT
15af0 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
15b00 48 52 45 41 44 0a 2a 2a 20 63 6f 6e 66 69 67 75  HREAD.** configu
15b10 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f  ration option.</
15b20 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
15b30 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54  TE_CONFIG_MULTIT
15b40 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49  HREAD]] <dt>SQLI
15b50 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54  TE_CONFIG_MULTIT
15b60 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  HREAD</dt>.** <d
15b70 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61  d>There are no a
15b80 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73  rguments to this
15b90 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20   option.  ^This 
15ba0 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a  option sets the.
15bb0 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ** [threading mo
15bc0 64 65 5d 20 74 6f 20 4d 75 6c 74 69 2d 74 68 72  de] to Multi-thr
15bd0 65 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77  ead.  In other w
15be0 6f 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65  ords, it disable
15bf0 73 0a 2a 2a 20 6d 75 74 65 78 69 6e 67 20 6f 6e  s.** mutexing on
15c00 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
15c10 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70  ction] and [prep
15c20 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
15c30 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 54 68 65 20  objects..** The 
15c40 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 72  application is r
15c50 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 73  esponsible for s
15c60 65 72 69 61 6c 69 7a 69 6e 67 20 61 63 63 65 73  erializing acces
15c70 73 20 74 6f 0a 2a 2a 20 5b 64 61 74 61 62 61 73  s to.** [databas
15c80 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61  e connections] a
15c90 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  nd [prepared sta
15ca0 74 65 6d 65 6e 74 73 5d 2e 20 20 42 75 74 20 6f  tements].  But o
15cb0 74 68 65 72 20 6d 75 74 65 78 65 73 0a 2a 2a 20  ther mutexes.** 
15cc0 61 72 65 20 65 6e 61 62 6c 65 64 20 73 6f 20 74  are enabled so t
15cd0 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  hat SQLite will 
15ce0 62 65 20 73 61 66 65 20 74 6f 20 75 73 65 20 69  be safe to use i
15cf0 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64  n a multi-thread
15d00 65 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e  ed.** environmen
15d10 74 20 61 73 20 6c 6f 6e 67 20 61 73 20 6e 6f 20  t as long as no 
15d20 74 77 6f 20 74 68 72 65 61 64 73 20 61 74 74 65  two threads atte
15d30 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65 20 73  mpt to use the s
15d40 61 6d 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  ame.** [database
15d50 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20   connection] at 
15d60 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 20 20  the same time.  
15d70 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f  ^If SQLite is co
15d80 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74  mpiled with.** t
15d90 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
15da0 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54  DSAFE | SQLITE_T
15db0 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d  HREADSAFE=0] com
15dc0 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
15dd0 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e   then.** it is n
15de0 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73  ot possible to s
15df0 65 74 20 74 68 65 20 4d 75 6c 74 69 2d 74 68 72  et the Multi-thr
15e00 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  ead [threading m
15e10 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ode] and.** [sql
15e20 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
15e30 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  ill return [SQLI
15e40 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c  TE_ERROR] if cal
15e50 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  led with the.** 
15e60 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
15e70 4c 54 49 54 48 52 45 41 44 20 63 6f 6e 66 69 67  LTITHREAD config
15e80 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c  uration option.<
15e90 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
15ea0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41  ITE_CONFIG_SERIA
15eb0 4c 49 5a 45 44 5d 5d 20 3c 64 74 3e 53 51 4c 49  LIZED]] <dt>SQLI
15ec0 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c  TE_CONFIG_SERIAL
15ed0 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  IZED</dt>.** <dd
15ee0 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72  >There are no ar
15ef0 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20  guments to this 
15f00 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f  option.  ^This o
15f10 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a  ption sets the.*
15f20 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  * [threading mod
15f30 65 5d 20 74 6f 20 53 65 72 69 61 6c 69 7a 65 64  e] to Serialized
15f40 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  . In other words
15f50 2c 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 65 6e  , this option en
15f60 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74  ables.** all mut
15f70 65 78 65 73 20 69 6e 63 6c 75 64 69 6e 67 20 74  exes including t
15f80 68 65 20 72 65 63 75 72 73 69 76 65 0a 2a 2a 20  he recursive.** 
15f90 6d 75 74 65 78 65 73 20 6f 6e 20 5b 64 61 74 61  mutexes on [data
15fa0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
15fb0 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73   and [prepared s
15fc0 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74  tatement] object
15fd0 73 2e 0a 2a 2a 20 49 6e 20 74 68 69 73 20 6d 6f  s..** In this mo
15fe0 64 65 20 28 77 68 69 63 68 20 69 73 20 74 68 65  de (which is the
15ff0 20 64 65 66 61 75 6c 74 20 77 68 65 6e 20 53 51   default when SQ
16000 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
16010 20 77 69 74 68 0a 2a 2a 20 5b 53 51 4c 49 54 45   with.** [SQLITE
16020 5f 54 48 52 45 41 44 53 41 46 45 3d 31 5d 29 20  _THREADSAFE=1]) 
16030 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61  the SQLite libra
16040 72 79 20 77 69 6c 6c 20 69 74 73 65 6c 66 20 73  ry will itself s
16050 65 72 69 61 6c 69 7a 65 20 61 63 63 65 73 73 0a  erialize access.
16060 2a 2a 20 74 6f 20 5b 64 61 74 61 62 61 73 65 20  ** to [database 
16070 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64  connections] and
16080 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
16090 6d 65 6e 74 73 5d 20 73 6f 20 74 68 61 74 20 74  ments] so that t
160a0 68 65 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f  he.** applicatio
160b0 6e 20 69 73 20 66 72 65 65 20 74 6f 20 75 73 65  n is free to use
160c0 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62   the same [datab
160d0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
160e0 6f 72 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20 5b  or the.** same [
160f0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
16100 6e 74 5d 20 69 6e 20 64 69 66 66 65 72 65 6e 74  nt] in different
16110 20 74 68 72 65 61 64 73 20 61 74 20 74 68 65 20   threads at the 
16120 73 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49  same time..** ^I
16130 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
16140 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65  iled with.** the
16150 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
16160 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52  AFE | SQLITE_THR
16170 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69  EADSAFE=0] compi
16180 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74  le-time option t
16190 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74  hen.** it is not
161a0 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74   possible to set
161b0 20 74 68 65 20 53 65 72 69 61 6c 69 7a 65 64 20   the Serialized 
161c0 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
161d0 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
161e0 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20  _config()] will 
161f0 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45  return [SQLITE_E
16200 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20  RROR] if called 
16210 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49  with the.** SQLI
16220 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c  TE_CONFIG_SERIAL
16230 49 5a 45 44 20 63 6f 6e 66 69 67 75 72 61 74 69  IZED configurati
16240 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a  on option.</dd>.
16250 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
16260 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c  ONFIG_MALLOC]] <
16270 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
16280 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20  _MALLOC</dt>.** 
16290 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69  <dd> ^(This opti
162a0 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
162b0 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
162c0 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
162d0 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20   an.** instance 
162e0 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
162f0 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  mem_methods] str
16300 75 63 74 75 72 65 2e 20 20 54 68 65 20 61 72 67  ucture.  The arg
16310 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a  ument specifies.
16320 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c  ** alternative l
16330 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20  ow-level memory 
16340 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69  allocation routi
16350 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 20 69  nes to be used i
16360 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 74 68  n place of.** th
16370 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
16380 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 62 75 69  ion routines bui
16390 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29  lt into SQLite.)
163a0 5e 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 0a  ^ ^SQLite makes.
163b0 2a 2a 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61  ** its own priva
163c0 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 63  te copy of the c
163d0 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73  ontent of the [s
163e0 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
163f0 64 73 5d 20 73 74 72 75 63 74 75 72 65 0a 2a 2a  ds] structure.**
16400 20 62 65 66 6f 72 65 20 74 68 65 20 5b 73 71 6c   before the [sql
16410 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 63  ite3_config()] c
16420 61 6c 6c 20 72 65 74 75 72 6e 73 2e 3c 2f 64 64  all returns.</dd
16430 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
16440 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f  _CONFIG_GETMALLO
16450 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  C]] <dt>SQLITE_C
16460 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c  ONFIG_GETMALLOC<
16470 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
16480 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
16490 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
164a0 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f  nt which is a po
164b0 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69  inter to an.** i
164c0 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b  nstance of the [
164d0 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
164e0 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20  ods] structure. 
164f0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65   The [sqlite3_me
16500 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74  m_methods].** st
16510 72 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65  ructure is fille
16520 64 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65  d with the curre
16530 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 65 6d  ntly defined mem
16540 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
16550 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68  outines.)^.** Th
16560 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65  is option can be
16570 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61   used to overloa
16580 64 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 65  d the default me
16590 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a  mory allocation.
165a0 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68  ** routines with
165b0 20 61 20 77 72 61 70 70 65 72 20 74 68 61 74 20   a wrapper that 
165c0 73 69 6d 75 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f  simulations memo
165d0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61  ry allocation fa
165e0 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 74 72 61 63  ilure or.** trac
165f0 6b 73 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 2c  ks memory usage,
16600 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 3c 2f   for example. </
16610 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
16620 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41  TE_CONFIG_MEMSTA
16630 54 55 53 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  TUS]] <dt>SQLITE
16640 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55  _CONFIG_MEMSTATU
16650 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  S</dt>.** <dd> ^
16660 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
16670 73 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  s single argumen
16680 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2c 20 69  t of type int, i
16690 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20  nterpreted as a 
166a0 0a 2a 2a 20 62 6f 6f 6c 65 61 6e 2c 20 77 68 69  .** boolean, whi
166b0 63 68 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69  ch enables or di
166c0 73 61 62 6c 65 73 20 74 68 65 20 63 6f 6c 6c 65  sables the colle
166d0 63 74 69 6f 6e 20 6f 66 20 6d 65 6d 6f 72 79 20  ction of memory 
166e0 61 6c 6c 6f 63 61 74 69 6f 6e 20 0a 2a 2a 20 73  allocation .** s
166f0 74 61 74 69 73 74 69 63 73 2e 20 5e 28 57 68 65  tatistics. ^(Whe
16700 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  n memory allocat
16710 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61  ion statistics a
16720 72 65 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65  re disabled, the
16730 20 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 53   .** following S
16740 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73  QLite interfaces
16750 20 62 65 63 6f 6d 65 20 6e 6f 6e 2d 6f 70 65 72   become non-oper
16760 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75  ational:.**   <u
16770 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71  l>.**   <li> [sq
16780 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
16790 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b  d()].**   <li> [
167a0 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
167b0 69 67 68 77 61 74 65 72 28 29 5d 0a 2a 2a 20 20  ighwater()].**  
167c0 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73   <li> [sqlite3_s
167d0 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34  oft_heap_limit64
167e0 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73  ()].**   <li> [s
167f0 71 6c 69 74 65 33 5f 73 74 61 74 75 73 28 29 5d  qlite3_status()]
16800 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a  .**   </ul>)^.**
16810 20 5e 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74   ^Memory allocat
16820 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61  ion statistics a
16830 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64 65  re enabled by de
16840 66 61 75 6c 74 20 75 6e 6c 65 73 73 20 53 51 4c  fault unless SQL
16850 69 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c  ite is.** compil
16860 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f  ed with [SQLITE_
16870 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55  DEFAULT_MEMSTATU
16880 53 5d 3d 30 20 69 6e 20 77 68 69 63 68 20 63 61  S]=0 in which ca
16890 73 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c  se memory.** all
168a0 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69  ocation statisti
168b0 63 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20  cs are disabled 
168c0 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c  by default..** <
168d0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
168e0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54  ITE_CONFIG_SCRAT
168f0 43 48 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  CH]] <dt>SQLITE_
16900 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 3c 2f  CONFIG_SCRATCH</
16910 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69  dt>.** <dd> ^Thi
16920 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69  s option specifi
16930 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f  es a static memo
16940 72 79 20 62 75 66 66 65 72 20 74 68 61 74 20 53  ry buffer that S
16950 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f  QLite can use fo
16960 72 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d 65 6d  r.** scratch mem
16970 6f 72 79 2e 20 20 54 68 65 72 65 20 61 72 65 20  ory.  There are 
16980 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 3a  three arguments:
16990 20 20 41 20 70 6f 69 6e 74 65 72 20 61 6e 20 38    A pointer an 8
169a0 2d 62 79 74 65 0a 2a 2a 20 61 6c 69 67 6e 65 64  -byte.** aligned
169b0 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 66   memory buffer f
169c0 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20 73 63  rom which the sc
169d0 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e  ratch allocation
169e0 73 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 64 72 61  s will be.** dra
169f0 77 6e 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20  wn, the size of 
16a00 65 61 63 68 20 73 63 72 61 74 63 68 20 61 6c 6c  each scratch all
16a10 6f 63 61 74 69 6f 6e 20 28 73 7a 29 2c 0a 2a 2a  ocation (sz),.**
16a20 20 61 6e 64 20 74 68 65 20 6d 61 78 69 6d 75 6d   and the maximum
16a30 20 6e 75 6d 62 65 72 20 6f 66 20 73 63 72 61 74   number of scrat
16a40 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 28  ch allocations (
16a50 4e 29 2e 20 20 54 68 65 20 73 7a 0a 2a 2a 20 61  N).  The sz.** a
16a60 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20  rgument must be 
16a70 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 31 36  a multiple of 16
16a80 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  ..** The first a
16a90 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20  rgument must be 
16aa0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
16ab0 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 62  8-byte aligned b
16ac0 75 66 66 65 72 0a 2a 2a 20 6f 66 20 61 74 20 6c  uffer.** of at l
16ad0 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20  east sz*N bytes 
16ae0 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53  of memory..** ^S
16af0 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 6e  QLite will use n
16b00 6f 20 6d 6f 72 65 20 74 68 61 6e 20 74 77 6f 20  o more than two 
16b10 73 63 72 61 74 63 68 20 62 75 66 66 65 72 73 20  scratch buffers 
16b20 70 65 72 20 74 68 72 65 61 64 2e 20 20 53 6f 0a  per thread.  So.
16b30 2a 2a 20 4e 20 73 68 6f 75 6c 64 20 62 65 20 73  ** N should be s
16b40 65 74 20 74 6f 20 74 77 69 63 65 20 74 68 65 20  et to twice the 
16b50 65 78 70 65 63 74 65 64 20 6d 61 78 69 6d 75 6d  expected maximum
16b60 20 6e 75 6d 62 65 72 20 6f 66 20 74 68 72 65 61   number of threa
16b70 64 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77  ds..** ^SQLite w
16b80 69 6c 6c 20 6e 65 76 65 72 20 72 65 71 75 69 72  ill never requir
16b90 65 20 61 20 73 63 72 61 74 63 68 20 62 75 66 66  e a scratch buff
16ba0 65 72 20 74 68 61 74 20 69 73 20 6d 6f 72 65 20  er that is more 
16bb0 74 68 61 6e 20 36 0a 2a 2a 20 74 69 6d 65 73 20  than 6.** times 
16bc0 74 68 65 20 64 61 74 61 62 61 73 65 20 70 61 67  the database pag
16bd0 65 20 73 69 7a 65 2e 20 5e 49 66 20 53 51 4c 69  e size. ^If SQLi
16be0 74 65 20 6e 65 65 64 73 20 6e 65 65 64 73 20 61  te needs needs a
16bf0 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 73 63 72  dditional.** scr
16c00 61 74 63 68 20 6d 65 6d 6f 72 79 20 62 65 79 6f  atch memory beyo
16c10 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f 76 69  nd what is provi
16c20 64 65 64 20 62 79 20 74 68 69 73 20 63 6f 6e 66  ded by this conf
16c30 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
16c40 2c 20 74 68 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69  , then .** [sqli
16c50 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 77 69  te3_malloc()] wi
16c60 6c 6c 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62  ll be used to ob
16c70 74 61 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20  tain the memory 
16c80 6e 65 65 64 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a  needed.</dd>.**.
16c90 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
16ca0 49 47 5f 50 41 47 45 43 41 43 48 45 5d 5d 20 3c  IG_PAGECACHE]] <
16cb0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
16cc0 5f 50 41 47 45 43 41 43 48 45 3c 2f 64 74 3e 0a  _PAGECACHE</dt>.
16cd0 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70  ** <dd> ^This op
16ce0 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61  tion specifies a
16cf0 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62   static memory b
16d00 75 66 66 65 72 20 74 68 61 74 20 53 51 4c 69 74  uffer that SQLit
16d10 65 20 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a  e can use for.**
16d20 20 74 68 65 20 64 61 74 61 62 61 73 65 20 70 61   the database pa
16d30 67 65 20 63 61 63 68 65 20 77 69 74 68 20 74 68  ge cache with th
16d40 65 20 64 65 66 61 75 6c 74 20 70 61 67 65 20 63  e default page c
16d50 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ache implementat
16d60 69 6f 6e 2e 20 20 0a 2a 2a 20 54 68 69 73 20 63  ion.  .** This c
16d70 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 73 68 6f  onfiguration sho
16d80 75 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20  uld not be used 
16d90 69 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  if an applicatio
16da0 6e 2d 64 65 66 69 6e 65 20 70 61 67 65 0a 2a 2a  n-define page.**
16db0 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74   cache implement
16dc0 61 74 69 6f 6e 20 69 73 20 6c 6f 61 64 65 64 20  ation is loaded 
16dd0 75 73 69 6e 67 20 74 68 65 20 53 51 4c 49 54 45  using the SQLITE
16de0 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 20  _CONFIG_PCACHE2 
16df0 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 72 65  option..** There
16e00 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d   are three argum
16e10 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74  ents to this opt
16e20 69 6f 6e 3a 20 41 20 70 6f 69 6e 74 65 72 20 74  ion: A pointer t
16e30 6f 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64  o 8-byte aligned
16e40 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 74 68 65 20  .** memory, the 
16e50 73 69 7a 65 20 6f 66 20 65 61 63 68 20 70 61 67  size of each pag
16e60 65 20 62 75 66 66 65 72 20 28 73 7a 29 2c 20 61  e buffer (sz), a
16e70 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  nd the number of
16e80 20 70 61 67 65 73 20 28 4e 29 2e 0a 2a 2a 20 54   pages (N)..** T
16e90 68 65 20 73 7a 20 61 72 67 75 6d 65 6e 74 20 73  he sz argument s
16ea0 68 6f 75 6c 64 20 62 65 20 74 68 65 20 73 69 7a  hould be the siz
16eb0 65 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74  e of the largest
16ec0 20 64 61 74 61 62 61 73 65 20 70 61 67 65 0a 2a   database page.*
16ed0 2a 20 28 61 20 70 6f 77 65 72 20 6f 66 20 74 77  * (a power of tw
16ee0 6f 20 62 65 74 77 65 65 6e 20 35 31 32 20 61 6e  o between 512 an
16ef0 64 20 33 32 37 36 38 29 20 70 6c 75 73 20 61 20  d 32768) plus a 
16f00 6c 69 74 74 6c 65 20 65 78 74 72 61 20 66 6f 72  little extra for
16f10 20 65 61 63 68 0a 2a 2a 20 70 61 67 65 20 68 65   each.** page he
16f20 61 64 65 72 2e 20 20 5e 54 68 65 20 70 61 67 65  ader.  ^The page
16f30 20 68 65 61 64 65 72 20 73 69 7a 65 20 69 73 20   header size is 
16f40 32 30 20 74 6f 20 34 30 20 62 79 74 65 73 20 64  20 to 40 bytes d
16f50 65 70 65 6e 64 69 6e 67 20 6f 6e 0a 2a 2a 20 74  epending on.** t
16f60 68 65 20 68 6f 73 74 20 61 72 63 68 69 74 65 63  he host architec
16f70 74 75 72 65 2e 20 20 5e 49 74 20 69 73 20 68 61  ture.  ^It is ha
16f80 72 6d 6c 65 73 73 2c 20 61 70 61 72 74 20 66 72  rmless, apart fr
16f90 6f 6d 20 74 68 65 20 77 61 73 74 65 64 20 6d 65  om the wasted me
16fa0 6d 6f 72 79 2c 0a 2a 2a 20 74 6f 20 6d 61 6b 65  mory,.** to make
16fb0 20 73 7a 20 61 20 6c 69 74 74 6c 65 20 74 6f 6f   sz a little too
16fc0 20 6c 61 72 67 65 2e 20 20 54 68 65 20 66 69 72   large.  The fir
16fd0 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73  st.** argument s
16fe0 68 6f 75 6c 64 20 70 6f 69 6e 74 20 74 6f 20 61  hould point to a
16ff0 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 66 20  n allocation of 
17000 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79  at least sz*N by
17010 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a  tes of memory..*
17020 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75  * ^SQLite will u
17030 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72  se the memory pr
17040 6f 76 69 64 65 64 20 62 79 20 74 68 65 20 66 69  ovided by the fi
17050 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
17060 73 61 74 69 73 66 79 20 69 74 73 0a 2a 2a 20 6d  satisfy its.** m
17070 65 6d 6f 72 79 20 6e 65 65 64 73 20 66 6f 72 20  emory needs for 
17080 74 68 65 20 66 69 72 73 74 20 4e 20 70 61 67 65  the first N page
17090 73 20 74 68 61 74 20 69 74 20 61 64 64 73 20 74  s that it adds t
170a0 6f 20 63 61 63 68 65 2e 20 20 5e 49 66 20 61 64  o cache.  ^If ad
170b0 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65  ditional.** page
170c0 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 69 73   cache memory is
170d0 20 6e 65 65 64 65 64 20 62 65 79 6f 6e 64 20 77   needed beyond w
170e0 68 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 20  hat is provided 
170f0 62 79 20 74 68 69 73 20 6f 70 74 69 6f 6e 2c 20  by this option, 
17100 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 67  then.** SQLite g
17110 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  oes to [sqlite3_
17120 6d 61 6c 6c 6f 63 28 29 5d 20 66 6f 72 20 74 68  malloc()] for th
17130 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 74 6f  e additional sto
17140 72 61 67 65 20 73 70 61 63 65 2e 0a 2a 2a 20 54  rage space..** T
17150 68 65 20 70 6f 69 6e 74 65 72 20 69 6e 20 74 68  he pointer in th
17160 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
17170 20 6d 75 73 74 0a 2a 2a 20 62 65 20 61 6c 69 67   must.** be alig
17180 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65  ned to an 8-byte
17190 20 62 6f 75 6e 64 61 72 79 20 6f 72 20 73 75 62   boundary or sub
171a0 73 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72  sequent behavior
171b0 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69   of SQLite.** wi
171c0 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 64 2e  ll be undefined.
171d0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
171e0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50  LITE_CONFIG_HEAP
171f0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
17200 4e 46 49 47 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a  NFIG_HEAP</dt>.*
17210 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74  * <dd> ^This opt
17220 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20  ion specifies a 
17230 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75  static memory bu
17240 66 66 65 72 20 74 68 61 74 20 53 51 4c 69 74 65  ffer that SQLite
17250 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 66 6f 72   will use.** for
17260 20 61 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e 61   all of its dyna
17270 6d 69 63 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  mic memory alloc
17280 61 74 69 6f 6e 20 6e 65 65 64 73 20 62 65 79 6f  ation needs beyo
17290 6e 64 20 74 68 6f 73 65 20 70 72 6f 76 69 64 65  nd those provide
172a0 64 0a 2a 2a 20 66 6f 72 20 62 79 20 5b 53 51 4c  d.** for by [SQL
172b0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54  ITE_CONFIG_SCRAT
172c0 43 48 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f  CH] and [SQLITE_
172d0 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
172e0 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20  ]..** There are 
172f0 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 3a  three arguments:
17300 20 41 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e   An 8-byte align
17310 65 64 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68  ed pointer to th
17320 65 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 68 65  e memory,.** the
17330 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
17340 20 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 62   in the memory b
17350 75 66 66 65 72 2c 20 61 6e 64 20 74 68 65 20 6d  uffer, and the m
17360 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f  inimum allocatio
17370 6e 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20 74  n size..** ^If t
17380 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72  he first pointer
17390 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69   (the memory poi
173a0 6e 74 65 72 29 20 69 73 20 4e 55 4c 4c 2c 20 74  nter) is NULL, t
173b0 68 65 6e 20 53 51 4c 69 74 65 20 72 65 76 65 72  hen SQLite rever
173c0 74 73 0a 2a 2a 20 74 6f 20 75 73 69 6e 67 20 69  ts.** to using i
173d0 74 73 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72  ts default memor
173e0 79 20 61 6c 6c 6f 63 61 74 6f 72 20 28 74 68 65  y allocator (the
173f0 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29   system malloc()
17400 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 29   implementation)
17410 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20 61 6e 79  ,.** undoing any
17420 20 70 72 69 6f 72 20 69 6e 76 6f 63 61 74 69 6f   prior invocatio
17430 6e 20 6f 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  n of [SQLITE_CON
17440 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 5e 49  FIG_MALLOC].  ^I
17450 66 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20  f the.** memory 
17460 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e  pointer is not N
17470 55 4c 4c 20 61 6e 64 20 65 69 74 68 65 72 20 5b  ULL and either [
17480 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45  SQLITE_ENABLE_ME
17490 4d 53 59 53 33 5d 20 6f 72 0a 2a 2a 20 5b 53 51  MSYS3] or.** [SQ
174a0 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53  LITE_ENABLE_MEMS
174b0 59 53 35 5d 20 61 72 65 20 64 65 66 69 6e 65 64  YS5] are defined
174c0 2c 20 74 68 65 6e 20 74 68 65 20 61 6c 74 65 72  , then the alter
174d0 6e 61 74 69 76 65 20 6d 65 6d 6f 72 79 0a 2a 2a  native memory.**
174e0 20 61 6c 6c 6f 63 61 74 6f 72 20 69 73 20 65 6e   allocator is en
174f0 67 61 67 65 64 20 74 6f 20 68 61 6e 64 6c 65 20  gaged to handle 
17500 61 6c 6c 20 6f 66 20 53 51 4c 69 74 65 73 20 6d  all of SQLites m
17510 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
17520 20 6e 65 65 64 73 2e 0a 2a 2a 20 54 68 65 20 66   needs..** The f
17530 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68  irst pointer (th
17540 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72  e memory pointer
17550 29 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65  ) must be aligne
17560 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 0a 2a  d to an 8-byte.*
17570 2a 20 62 6f 75 6e 64 61 72 79 20 6f 72 20 73 75  * boundary or su
17580 62 73 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f  bsequent behavio
17590 72 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c  r of SQLite will
175a0 20 62 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   be undefined..*
175b0 2a 20 54 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c  * The minimum al
175c0 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 69 73  location size is
175d0 20 63 61 70 70 65 64 20 61 74 20 32 2a 2a 31 32   capped at 2**12
175e0 2e 20 52 65 61 73 6f 6e 61 62 6c 65 20 76 61 6c  . Reasonable val
175f0 75 65 73 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6d  ues.** for the m
17600 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f  inimum allocatio
17610 6e 20 73 69 7a 65 20 61 72 65 20 32 2a 2a 35 20  n size are 2**5 
17620 74 68 72 6f 75 67 68 20 32 2a 2a 38 2e 3c 2f 64  through 2**8.</d
17630 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
17640 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 5d  E_CONFIG_MUTEX]]
17650 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
17660 49 47 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a  IG_MUTEX</dt>.**
17670 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74   <dd> ^(This opt
17680 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
17690 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
176a0 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  h is a pointer t
176b0 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65  o an.** instance
176c0 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
176d0 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20  _mutex_methods] 
176e0 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 20  structure.  The 
176f0 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69  argument specifi
17700 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76  es.** alternativ
17710 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75 74 65  e low-level mute
17720 78 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65  x routines to be
17730 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65 0a 2a   used in place.*
17740 2a 20 74 68 65 20 6d 75 74 65 78 20 72 6f 75 74  * the mutex rout
17750 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20  ines built into 
17760 53 51 4c 69 74 65 2e 29 5e 20 20 5e 53 51 4c 69  SQLite.)^  ^SQLi
17770 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20  te makes a copy 
17780 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6e 74 65 6e  of the.** conten
17790 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  t of the [sqlite
177a0 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d  3_mutex_methods]
177b0 20 73 74 72 75 63 74 75 72 65 20 62 65 66 6f 72   structure befor
177c0 65 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a  e the call to.**
177d0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
177e0 28 29 5d 20 72 65 74 75 72 6e 73 2e 20 5e 49 66  ()] returns. ^If
177f0 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
17800 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
17810 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
17820 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45  FE | SQLITE_THRE
17830 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c  ADSAFE=0] compil
17840 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68  e-time option th
17850 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65  en.** the entire
17860 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79 73   mutexing subsys
17870 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66  tem is omitted f
17880 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e  rom the build an
17890 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f  d hence calls to
178a0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
178b0 66 69 67 28 29 5d 20 77 69 74 68 20 74 68 65 20  fig()] with the 
178c0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
178d0 54 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  TEX configuratio
178e0 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a  n option will.**
178f0 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
17900 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a  ERROR].</dd>.**.
17910 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
17920 49 47 5f 47 45 54 4d 55 54 45 58 5d 5d 20 3c 64  IG_GETMUTEX]] <d
17930 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
17940 47 45 54 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a  GETMUTEX</dt>.**
17950 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74   <dd> ^(This opt
17960 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
17970 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
17980 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  h is a pointer t
17990 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65  o an.** instance
179a0 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
179b0 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20  _mutex_methods] 
179c0 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 0a  structure.  The.
179d0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  ** [sqlite3_mute
179e0 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74  x_methods].** st
179f0 72 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65  ructure is fille
17a00 64 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65  d with the curre
17a10 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 75 74  ntly defined mut
17a20 65 78 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a  ex routines.)^.*
17a30 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61  * This option ca
17a40 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65  n be used to ove
17a50 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c  rload the defaul
17a60 74 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74 69  t mutex allocati
17a70 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77  on.** routines w
17a80 69 74 68 20 61 20 77 72 61 70 70 65 72 20 75 73  ith a wrapper us
17a90 65 64 20 74 6f 20 74 72 61 63 6b 20 6d 75 74 65  ed to track mute
17aa0 78 20 75 73 61 67 65 20 66 6f 72 20 70 65 72 66  x usage for perf
17ab0 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69  ormance.** profi
17ac0 6c 69 6e 67 20 6f 72 20 74 65 73 74 69 6e 67 2c  ling or testing,
17ad0 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 20 20   for example.   
17ae0 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f  ^If SQLite is co
17af0 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74  mpiled with.** t
17b00 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
17b10 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54  DSAFE | SQLITE_T
17b20 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d  HREADSAFE=0] com
17b30 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
17b40 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74   then.** the ent
17b50 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62  ire mutexing sub
17b60 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65  system is omitte
17b70 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64  d from the build
17b80 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73   and hence calls
17b90 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
17ba0 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74  config()] with t
17bb0 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
17bc0 5f 47 45 54 4d 55 54 45 58 20 63 6f 6e 66 69 67  _GETMUTEX config
17bd0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77  uration option w
17be0 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53  ill.** return [S
17bf0 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64  QLITE_ERROR].</d
17c00 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
17c10 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  E_CONFIG_LOOKASI
17c20 44 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  DE]] <dt>SQLITE_
17c30 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
17c40 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
17c50 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
17c60 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 20  s two arguments 
17c70 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74  that determine t
17c80 68 65 20 64 65 66 61 75 6c 74 0a 2a 2a 20 6d 65  he default.** me
17c90 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
17ca0 66 6f 72 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64  for the lookasid
17cb0 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
17cc0 6f 72 20 6f 6e 20 65 61 63 68 0a 2a 2a 20 5b 64  or on each.** [d
17cd0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
17ce0 6f 6e 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20  on].  The first 
17cf0 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a  argument is the.
17d00 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20  ** size of each 
17d10 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72  lookaside buffer
17d20 20 73 6c 6f 74 20 61 6e 64 20 74 68 65 20 73 65   slot and the se
17d30 63 6f 6e 64 20 69 73 20 74 68 65 20 6e 75 6d 62  cond is the numb
17d40 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20 61  er of.** slots a
17d50 6c 6c 6f 63 61 74 65 64 20 74 6f 20 65 61 63 68  llocated to each
17d60 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
17d70 74 69 6f 6e 2e 29 5e 20 20 5e 28 54 68 69 73 20  tion.)^  ^(This 
17d80 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a  option sets the.
17d90 2a 2a 20 3c 69 3e 64 65 66 61 75 6c 74 3c 2f 69  ** <i>default</i
17da0 3e 20 6c 6f 6f 6b 61 73 69 64 65 20 73 69 7a 65  > lookaside size
17db0 2e 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 44 42  . The [SQLITE_DB
17dc0 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
17dd0 5d 0a 2a 2a 20 76 65 72 62 20 74 6f 20 5b 73 71  ].** verb to [sq
17de0 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
17df0 29 5d 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  )] can be used t
17e00 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f  o change the loo
17e10 6b 61 73 69 64 65 0a 2a 2a 20 63 6f 6e 66 69 67  kaside.** config
17e20 75 72 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76  uration on indiv
17e30 69 64 75 61 6c 20 63 6f 6e 6e 65 63 74 69 6f 6e  idual connection
17e40 73 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  s.)^ </dd>.**.**
17e50 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
17e60 5f 50 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53  _PCACHE2]] <dt>S
17e70 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
17e80 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  CHE2</dt>.** <dd
17e90 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20  > ^(This option 
17ea0 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
17eb0 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
17ec0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a   a pointer to.**
17ed0 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61   an [sqlite3_pca
17ee0 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62  che_methods2] ob
17ef0 6a 65 63 74 2e 20 20 54 68 69 73 20 6f 62 6a 65  ject.  This obje
17f00 63 74 20 73 70 65 63 69 66 69 65 73 20 74 68 65  ct specifies the
17f10 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 74 6f   interface.** to
17f20 20 61 20 63 75 73 74 6f 6d 20 70 61 67 65 20 63   a custom page c
17f30 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ache implementat
17f40 69 6f 6e 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20  ion.)^  ^SQLite 
17f50 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20  makes a copy of 
17f60 74 68 65 0a 2a 2a 20 6f 62 6a 65 63 74 20 61 6e  the.** object an
17f70 64 20 75 73 65 73 20 69 74 20 66 6f 72 20 70 61  d uses it for pa
17f80 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20  ge cache memory 
17f90 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 3c 2f 64 64  allocations.</dd
17fa0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
17fb0 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48  _CONFIG_GETPCACH
17fc0 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  E2]] <dt>SQLITE_
17fd0 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
17fe0 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  2</dt>.** <dd> ^
17ff0 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b  (This option tak
18000 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
18010 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20  ment which is a 
18020 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a  pointer to an.**
18030 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65   [sqlite3_pcache
18040 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63  _methods2] objec
18050 74 2e 20 20 53 51 4c 69 74 65 20 63 6f 70 69 65  t.  SQLite copie
18060 73 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74  s of the current
18070 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20 69  .** page cache i
18080 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e  mplementation in
18090 74 6f 20 74 68 61 74 20 6f 62 6a 65 63 74 2e 29  to that object.)
180a0 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  ^ </dd>.**.** [[
180b0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
180c0 47 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  G]] <dt>SQLITE_C
180d0 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a  ONFIG_LOG</dt>.*
180e0 2a 20 3c 64 64 3e 20 54 68 65 20 53 51 4c 49 54  * <dd> The SQLIT
180f0 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74  E_CONFIG_LOG opt
18100 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 63  ion is used to c
18110 6f 6e 66 69 67 75 72 65 20 74 68 65 20 53 51 4c  onfigure the SQL
18120 69 74 65 0a 2a 2a 20 67 6c 6f 62 61 6c 20 5b 65  ite.** global [e
18130 72 72 6f 72 20 6c 6f 67 5d 2e 0a 2a 2a 20 28 5e  rror log]..** (^
18140 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
18150 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 74 61 6b  G_LOG option tak
18160 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73  es two arguments
18170 3a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  : a pointer to a
18180 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69 74  .** function wit
18190 68 20 61 20 63 61 6c 6c 20 73 69 67 6e 61 74 75  h a call signatu
181a0 72 65 20 6f 66 20 76 6f 69 64 28 2a 29 28 76 6f  re of void(*)(vo
181b0 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68  id*,int,const ch
181c0 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20 61 20  ar*), .** and a 
181d0 70 6f 69 6e 74 65 72 20 74 6f 20 76 6f 69 64 2e  pointer to void.
181e0 20 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f   ^If the functio
181f0 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74  n pointer is not
18200 20 4e 55 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a 20   NULL, it is.** 
18210 69 6e 76 6f 6b 65 64 20 62 79 20 5b 73 71 6c 69  invoked by [sqli
18220 74 65 33 5f 6c 6f 67 28 29 5d 20 74 6f 20 70 72  te3_log()] to pr
18230 6f 63 65 73 73 20 65 61 63 68 20 6c 6f 67 67 69  ocess each loggi
18240 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74  ng event.  ^If t
18250 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70  he.** function p
18260 6f 69 6e 74 65 72 20 69 73 20 4e 55 4c 4c 2c 20  ointer is NULL, 
18270 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67  the [sqlite3_log
18280 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 62 65  ()] interface be
18290 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a  comes a no-op..*
182a0 2a 20 5e 54 68 65 20 76 6f 69 64 20 70 6f 69 6e  * ^The void poin
182b0 74 65 72 20 74 68 61 74 20 69 73 20 74 68 65 20  ter that is the 
182c0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
182d0 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  to SQLITE_CONFIG
182e0 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70 61 73 73 65  _LOG is.** passe
182f0 64 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65  d through as the
18300 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
18310 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74   to the applicat
18320 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67  ion-defined logg
18330 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77  er.** function w
18340 68 65 6e 65 76 65 72 20 74 68 61 74 20 66 75 6e  henever that fun
18350 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64  ction is invoked
18360 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70  .  ^The second p
18370 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74  arameter to.** t
18380 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69  he logger functi
18390 6f 6e 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20  on is a copy of 
183a0 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
183b0 74 65 72 20 74 6f 20 74 68 65 20 63 6f 72 72 65  ter to the corre
183c0 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c  sponding.** [sql
183d0 69 74 65 33 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c  ite3_log()] call
183e0 20 61 6e 64 20 69 73 20 69 6e 74 65 6e 64 65 64   and is intended
183f0 20 74 6f 20 62 65 20 61 20 5b 72 65 73 75 6c 74   to be a [result
18400 20 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20   code] or an.** 
18410 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
18420 20 63 6f 64 65 5d 2e 20 20 5e 54 68 65 20 74 68   code].  ^The th
18430 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 70 61  ird parameter pa
18440 73 73 65 64 20 74 6f 20 74 68 65 20 6c 6f 67 67  ssed to the logg
18450 65 72 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73  er is.** log mes
18460 73 61 67 65 20 61 66 74 65 72 20 66 6f 72 6d 61  sage after forma
18470 74 74 69 6e 67 20 76 69 61 20 5b 73 71 6c 69 74  tting via [sqlit
18480 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 2e 0a  e3_snprintf()]..
18490 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 6c 6f  ** The SQLite lo
184a0 67 67 69 6e 67 20 69 6e 74 65 72 66 61 63 65 20  gging interface 
184b0 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74  is not reentrant
184c0 3b 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e  ; the logger fun
184d0 63 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69 65  ction.** supplie
184e0 64 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61  d by the applica
184f0 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 69 6e  tion must not in
18500 76 6f 6b 65 20 61 6e 79 20 53 51 4c 69 74 65 20  voke any SQLite 
18510 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49 6e  interface..** In
18520 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65   a multi-threade
18530 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74  d application, t
18540 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
18550 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a  efined logger.**
18560 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 62   function must b
18570 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 3c 2f  e threadsafe. </
18580 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
18590 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 5d 20  TE_CONFIG_URI]] 
185a0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
185b0 47 5f 55 52 49 0a 2a 2a 20 3c 64 64 3e 20 54 68  G_URI.** <dd> Th
185c0 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
185d0 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
185e0 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2e 20 49  t of type int. I
185f0 66 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e  f non-zero, then
18600 0a 2a 2a 20 55 52 49 20 68 61 6e 64 6c 69 6e 67  .** URI handling
18610 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e 61   is globally ena
18620 62 6c 65 64 2e 20 49 66 20 74 68 65 20 70 61 72  bled. If the par
18630 61 6d 65 74 65 72 20 69 73 20 7a 65 72 6f 2c 20  ameter is zero, 
18640 74 68 65 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e  then URI handlin
18650 67 0a 2a 2a 20 69 73 20 67 6c 6f 62 61 6c 6c 79  g.** is globally
18660 20 64 69 73 61 62 6c 65 64 2e 20 49 66 20 55 52   disabled. If UR
18670 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c  I handling is gl
18680 6f 62 61 6c 6c 79 20 65 6e 61 62 6c 65 64 2c 20  obally enabled, 
18690 61 6c 6c 20 66 69 6c 65 6e 61 6d 65 73 0a 2a 2a  all filenames.**
186a0 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69   passed to [sqli
186b0 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71  te3_open()], [sq
186c0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
186d0 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  , [sqlite3_open1
186e0 36 28 29 5d 20 6f 72 0a 2a 2a 20 73 70 65 63 69  6()] or.** speci
186f0 66 69 65 64 20 61 73 20 70 61 72 74 20 6f 66 20  fied as part of 
18700 5b 41 54 54 41 43 48 5d 20 63 6f 6d 6d 61 6e 64  [ATTACH] command
18710 73 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65  s are interprete
18720 64 20 61 73 20 55 52 49 73 2c 20 72 65 67 61 72  d as URIs, regar
18730 64 6c 65 73 73 0a 2a 2a 20 6f 66 20 77 68 65 74  dless.** of whet
18740 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 5b  her or not the [
18750 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d  SQLITE_OPEN_URI]
18760 20 66 6c 61 67 20 69 73 20 73 65 74 20 77 68 65   flag is set whe
18770 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  n the database.*
18780 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  * connection is 
18790 6f 70 65 6e 65 64 2e 20 49 66 20 69 74 20 69 73  opened. If it is
187a0 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c   globally disabl
187b0 65 64 2c 20 66 69 6c 65 6e 61 6d 65 73 20 61 72  ed, filenames ar
187c0 65 0a 2a 2a 20 6f 6e 6c 79 20 69 6e 74 65 72 70  e.** only interp
187d0 72 65 74 65 64 20 61 73 20 55 52 49 73 20 69 66  reted as URIs if
187e0 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e   the SQLITE_OPEN
187f0 5f 55 52 49 20 66 6c 61 67 20 69 73 20 73 65 74  _URI flag is set
18800 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 64 61 74   when the.** dat
18810 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
18820 20 69 73 20 6f 70 65 6e 65 64 2e 20 42 79 20 64   is opened. By d
18830 65 66 61 75 6c 74 2c 20 55 52 49 20 68 61 6e 64  efault, URI hand
18840 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79  ling is globally
18850 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 20 54 68  .** disabled. Th
18860 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20  e default value 
18870 6d 61 79 20 62 65 20 63 68 61 6e 67 65 64 20 62  may be changed b
18880 79 20 63 6f 6d 70 69 6c 69 6e 67 20 77 69 74 68  y compiling with
18890 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
188a0 55 53 45 5f 55 52 49 5d 20 73 79 6d 62 6f 6c 20  USE_URI] symbol 
188b0 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b  defined..**.** [
188c0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43  [SQLITE_CONFIG_C
188d0 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43  OVERING_INDEX_SC
188e0 41 4e 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  AN]] <dt>SQLITE_
188f0 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f  CONFIG_COVERING_
18900 49 4e 44 45 58 5f 53 43 41 4e 0a 2a 2a 20 3c 64  INDEX_SCAN.** <d
18910 64 3e 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 74  d> This option t
18920 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 69 6e  akes a single in
18930 74 65 67 65 72 20 61 72 67 75 6d 65 6e 74 20 77  teger argument w
18940 68 69 63 68 20 69 73 20 69 6e 74 65 72 70 72 65  hich is interpre
18950 74 65 64 20 61 73 0a 2a 2a 20 61 20 62 6f 6f 6c  ted as.** a bool
18960 65 61 6e 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ean in order to 
18970 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c  enable or disabl
18980 65 20 74 68 65 20 75 73 65 20 6f 66 20 63 6f 76  e the use of cov
18990 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20 66 6f  ering indices fo
189a0 72 0a 2a 2a 20 66 75 6c 6c 20 74 61 62 6c 65 20  r.** full table 
189b0 73 63 61 6e 73 20 69 6e 20 74 68 65 20 71 75 65  scans in the que
189c0 72 79 20 6f 70 74 69 6d 69 7a 65 72 2e 20 20 54  ry optimizer.  T
189d0 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 74 69  he default setti
189e0 6e 67 20 69 73 20 64 65 74 65 72 6d 69 6e 65 64  ng is determined
189f0 0a 2a 2a 20 62 79 20 74 68 65 20 5b 53 51 4c 49  .** by the [SQLI
18a00 54 45 5f 41 4c 4c 4f 57 5f 43 4f 56 45 52 49 4e  TE_ALLOW_COVERIN
18a10 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 20 63 6f  G_INDEX_SCAN] co
18a20 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
18a30 6e 2c 20 6f 72 20 69 73 20 22 6f 6e 22 0a 2a 2a  n, or is "on".**
18a40 20 69 66 20 74 68 61 74 20 63 6f 6d 70 69 6c 65   if that compile
18a50 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20  -time option is 
18a60 6f 6d 69 74 74 65 64 2e 0a 2a 2a 20 54 68 65 20  omitted..** The 
18a70 61 62 69 6c 69 74 79 20 74 6f 20 64 69 73 61 62  ability to disab
18a80 6c 65 20 74 68 65 20 75 73 65 20 6f 66 20 63 6f  le the use of co
18a90 76 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20 66  vering indices f
18aa0 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 63  or full table sc
18ab0 61 6e 73 0a 2a 2a 20 69 73 20 62 65 63 61 75 73  ans.** is becaus
18ac0 65 20 73 6f 6d 65 20 69 6e 63 6f 72 72 65 63 74  e some incorrect
18ad0 6c 79 20 63 6f 64 65 64 20 6c 65 67 61 63 79 20  ly coded legacy 
18ae0 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 69 67  applications mig
18af0 68 74 20 6d 61 6c 66 75 6e 63 74 69 6f 6e 0a 2a  ht malfunction.*
18b00 2a 20 6d 61 6c 66 75 6e 63 74 69 6f 6e 20 77 68  * malfunction wh
18b10 65 6e 20 74 68 65 20 6f 70 74 69 6d 69 7a 61 74  en the optimizat
18b20 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 20  ion is enabled. 
18b30 20 50 72 6f 76 69 64 69 6e 67 20 74 68 65 20 61   Providing the a
18b40 62 69 6c 69 74 79 20 74 6f 0a 2a 2a 20 64 69 73  bility to.** dis
18b50 61 62 6c 65 20 74 68 65 20 6f 70 74 69 6d 69 7a  able the optimiz
18b60 61 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 74 68 65  ation allows the
18b70 20 6f 6c 64 65 72 2c 20 62 75 67 67 79 20 61 70   older, buggy ap
18b80 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 74  plication code t
18b90 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69 74 68 6f 75  o work.** withou
18ba0 74 20 63 68 61 6e 67 65 20 65 76 65 6e 20 77 69  t change even wi
18bb0 74 68 20 6e 65 77 65 72 20 76 65 72 73 69 6f 6e  th newer version
18bc0 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a  s of SQLite..**.
18bd0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
18be0 49 47 5f 50 43 41 43 48 45 5d 5d 20 5b 5b 53 51  IG_PCACHE]] [[SQ
18bf0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50  LITE_CONFIG_GETP
18c00 43 41 43 48 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53  CACHE]].** <dt>S
18c10 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
18c20 43 48 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 43  CHE and SQLITE_C
18c30 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 0a  ONFIG_GETPCACHE.
18c40 2a 2a 20 3c 64 64 3e 20 54 68 65 73 65 20 6f 70  ** <dd> These op
18c50 74 69 6f 6e 73 20 61 72 65 20 6f 62 73 6f 6c 65  tions are obsole
18c60 74 65 20 61 6e 64 20 73 68 6f 75 6c 64 20 6e 6f  te and should no
18c70 74 20 62 65 20 75 73 65 64 20 62 79 20 6e 65 77  t be used by new
18c80 20 63 6f 64 65 2e 0a 2a 2a 20 54 68 65 79 20 61   code..** They a
18c90 72 65 20 72 65 74 61 69 6e 65 64 20 66 6f 72 20  re retained for 
18ca0 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
18cb0 69 62 69 6c 69 74 79 20 62 75 74 20 61 72 65 20  ibility but are 
18cc0 6e 6f 77 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 20 3c  now no-ops..** <
18cd0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
18ce0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f  ITE_CONFIG_SQLLO
18cf0 47 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  G]].** <dt>SQLIT
18d00 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 0a  E_CONFIG_SQLLOG.
18d10 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69  ** <dd>This opti
18d20 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c  on is only avail
18d30 61 62 6c 65 20 69 66 20 73 71 6c 69 74 65 20 69  able if sqlite i
18d40 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
18d50 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45  the.** [SQLITE_E
18d60 4e 41 42 4c 45 5f 53 51 4c 4c 4f 47 5d 20 70 72  NABLE_SQLLOG] pr
18d70 65 2d 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  e-processor macr
18d80 6f 20 64 65 66 69 6e 65 64 2e 20 54 68 65 20 66  o defined. The f
18d90 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 73 68  irst argument sh
18da0 6f 75 6c 64 0a 2a 2a 20 62 65 20 61 20 70 6f 69  ould.** be a poi
18db0 6e 74 65 72 20 74 6f 20 61 20 66 75 6e 63 74 69  nter to a functi
18dc0 6f 6e 20 6f 66 20 74 79 70 65 20 76 6f 69 64 28  on of type void(
18dd0 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33  *)(void*,sqlite3
18de0 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69  *,const char*, i
18df0 6e 74 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f  nt)..** The seco
18e00 6e 64 20 73 68 6f 75 6c 64 20 62 65 20 6f 66 20  nd should be of 
18e10 74 79 70 65 20 28 76 6f 69 64 2a 29 2e 20 54 68  type (void*). Th
18e20 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  e callback is in
18e30 76 6f 6b 65 64 20 62 79 20 74 68 65 20 6c 69 62  voked by the lib
18e40 72 61 72 79 0a 2a 2a 20 69 6e 20 74 68 72 65 65  rary.** in three
18e50 20 73 65 70 61 72 61 74 65 20 63 69 72 63 75 6d   separate circum
18e60 73 74 61 6e 63 65 73 2c 20 69 64 65 6e 74 69 66  stances, identif
18e70 69 65 64 20 62 79 20 74 68 65 20 76 61 6c 75 65  ied by the value
18e80 20 70 61 73 73 65 64 20 61 73 20 74 68 65 0a 2a   passed as the.*
18e90 2a 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  * fourth paramet
18ea0 65 72 2e 20 49 66 20 74 68 65 20 66 6f 75 72 74  er. If the fourt
18eb0 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 30  h parameter is 0
18ec0 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  , then the datab
18ed0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
18ee0 2a 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  * passed as the 
18ef0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
18f00 68 61 73 20 6a 75 73 74 20 62 65 65 6e 20 6f 70  has just been op
18f10 65 6e 65 64 2e 20 54 68 65 20 74 68 69 72 64 20  ened. The third 
18f20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 70 6f 69 6e  argument.** poin
18f30 74 73 20 74 6f 20 61 20 62 75 66 66 65 72 20 63  ts to a buffer c
18f40 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e 61  ontaining the na
18f50 6d 65 20 6f 66 20 74 68 65 20 6d 61 69 6e 20 64  me of the main d
18f60 61 74 61 62 61 73 65 20 66 69 6c 65 2e 20 49 66  atabase file. If
18f70 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70   the.** fourth p
18f80 61 72 61 6d 65 74 65 72 20 69 73 20 31 2c 20 74  arameter is 1, t
18f90 68 65 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74  hen the SQL stat
18fa0 65 6d 65 6e 74 20 74 68 61 74 20 74 68 65 20 74  ement that the t
18fb0 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 0a 2a  hird parameter.*
18fc0 2a 20 70 6f 69 6e 74 73 20 74 6f 20 68 61 73 20  * points to has 
18fd0 6a 75 73 74 20 62 65 65 6e 20 65 78 65 63 75 74  just been execut
18fe0 65 64 2e 20 4f 72 2c 20 69 66 20 74 68 65 20 66  ed. Or, if the f
18ff0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
19000 69 73 20 32 2c 20 74 68 65 6e 0a 2a 2a 20 74 68  is 2, then.** th
19010 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 65 69  e connection bei
19020 6e 67 20 70 61 73 73 65 64 20 61 73 20 74 68 65  ng passed as the
19030 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
19040 72 20 69 73 20 62 65 69 6e 67 20 63 6c 6f 73 65  r is being close
19050 64 2e 20 54 68 65 0a 2a 2a 20 74 68 69 72 64 20  d. The.** third 
19060 70 61 72 61 6d 65 74 65 72 20 69 73 20 70 61 73  parameter is pas
19070 73 65 64 20 4e 55 4c 4c 20 49 6e 20 74 68 69 73  sed NULL In this
19080 20 63 61 73 65 2e 20 20 41 6e 20 65 78 61 6d 70   case.  An examp
19090 6c 65 20 6f 66 20 75 73 69 6e 67 20 74 68 69 73  le of using this
190a0 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  .** configuratio
190b0 6e 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20  n option can be 
190c0 73 65 65 6e 20 69 6e 20 74 68 65 20 22 74 65 73  seen in the "tes
190d0 74 5f 73 71 6c 6c 6f 67 2e 63 22 20 73 6f 75 72  t_sqllog.c" sour
190e0 63 65 20 66 69 6c 65 20 69 6e 0a 2a 2a 20 74 68  ce file in.** th
190f0 65 20 63 61 6e 6f 6e 69 63 61 6c 20 53 51 4c 69  e canonical SQLi
19100 74 65 20 73 6f 75 72 63 65 20 74 72 65 65 2e 3c  te source tree.<
19110 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
19120 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f  ITE_CONFIG_MMAP_
19130 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51  SIZE]].** <dt>SQ
19140 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50  LITE_CONFIG_MMAP
19150 5f 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e 53 51 4c  _SIZE.** <dd>SQL
19160 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f  ITE_CONFIG_MMAP_
19170 53 49 5a 45 20 74 61 6b 65 73 20 74 77 6f 20 36  SIZE takes two 6
19180 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20 28 73  4-bit integer (s
19190 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 20 76 61  qlite3_int64) va
191a0 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 61 72 65  lues.** that are
191b0 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 6d 61   the default mma
191c0 70 20 73 69 7a 65 20 6c 69 6d 69 74 20 28 74 68  p size limit (th
191d0 65 20 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e  e default settin
191e0 67 20 66 6f 72 0a 2a 2a 20 5b 50 52 41 47 4d 41  g for.** [PRAGMA
191f0 20 6d 6d 61 70 5f 73 69 7a 65 5d 29 20 61 6e 64   mmap_size]) and
19200 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c   the maximum all
19210 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a 65 20 6c  owed mmap size l
19220 69 6d 69 74 2e 0a 2a 2a 20 54 68 65 20 64 65 66  imit..** The def
19230 61 75 6c 74 20 73 65 74 74 69 6e 67 20 63 61 6e  ault setting can
19240 20 62 65 20 6f 76 65 72 72 69 64 64 65 6e 20 62   be overridden b
19250 79 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20  y each database 
19260 63 6f 6e 6e 65 63 74 69 6f 6e 20 75 73 69 6e 67  connection using
19270 0a 2a 2a 20 65 69 74 68 65 72 20 74 68 65 20 5b  .** either the [
19280 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65  PRAGMA mmap_size
19290 5d 20 63 6f 6d 6d 61 6e 64 2c 20 6f 72 20 62 79  ] command, or by
192a0 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 53   using the.** [S
192b0 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50  QLITE_FCNTL_MMAP
192c0 5f 53 49 5a 45 5d 20 66 69 6c 65 20 63 6f 6e 74  _SIZE] file cont
192d0 72 6f 6c 2e 20 20 54 68 65 20 6d 61 78 69 6d 75  rol.  The maximu
192e0 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73  m allowed mmap s
192f0 69 7a 65 0a 2a 2a 20 63 61 6e 6e 6f 74 20 62 65  ize.** cannot be
19300 20 63 68 61 6e 67 65 64 20 61 74 20 72 75 6e 2d   changed at run-
19310 74 69 6d 65 2e 20 20 4e 6f 72 20 6d 61 79 20 74  time.  Nor may t
19320 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77  he maximum allow
19330 65 64 20 6d 6d 61 70 20 73 69 7a 65 0a 2a 2a 20  ed mmap size.** 
19340 65 78 63 65 65 64 20 74 68 65 20 63 6f 6d 70 69  exceed the compi
19350 6c 65 2d 74 69 6d 65 20 6d 61 78 69 6d 75 6d 20  le-time maximum 
19360 6d 6d 61 70 20 73 69 7a 65 20 73 65 74 20 62 79  mmap size set by
19370 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
19380 4d 41 58 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 63  MAX_MMAP_SIZE] c
19390 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
193a0 6f 6e 2e 20 20 0a 2a 2a 20 49 66 20 65 69 74 68  on.  .** If eith
193b0 65 72 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  er argument to t
193c0 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6e 65  his option is ne
193d0 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 61  gative, then tha
193e0 74 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a  t argument is.**
193f0 20 63 68 61 6e 67 65 64 20 74 6f 20 69 74 73 20   changed to its 
19400 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 64 65 66  compile-time def
19410 61 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  ault..** </dl>.*
19420 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
19430 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
19440 52 45 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20  READ  1  /* nil 
19450 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
19460 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48  E_CONFIG_MULTITH
19470 52 45 41 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c  READ   2  /* nil
19480 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
19490 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c  TE_CONFIG_SERIAL
194a0 49 5a 45 44 20 20 20 20 33 20 20 2f 2a 20 6e 69  IZED    3  /* ni
194b0 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  l */.#define SQL
194c0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
194d0 43 20 20 20 20 20 20 20 20 34 20 20 2f 2a 20 73  C        4  /* s
194e0 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
194f0 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ds* */.#define S
19500 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
19510 4d 41 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a  MALLOC     5  /*
19520 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74   sqlite3_mem_met
19530 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  hods* */.#define
19540 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
19550 43 52 41 54 43 48 20 20 20 20 20 20 20 36 20 20  CRATCH       6  
19560 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a  /* void*, int sz
19570 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69  , int N */.#defi
19580 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
19590 5f 50 41 47 45 43 41 43 48 45 20 20 20 20 20 37  _PAGECACHE     7
195a0 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20    /* void*, int 
195b0 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65  sz, int N */.#de
195c0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
195d0 49 47 5f 48 45 41 50 20 20 20 20 20 20 20 20 20  IG_HEAP         
195e0 20 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e   8  /* void*, in
195f0 74 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e  t nByte, int min
19600 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
19610 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41  TE_CONFIG_MEMSTA
19620 54 55 53 20 20 20 20 20 39 20 20 2f 2a 20 62 6f  TUS     9  /* bo
19630 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65  olean */.#define
19640 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
19650 55 54 45 58 20 20 20 20 20 20 20 20 31 30 20 20  UTEX        10  
19660 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  /* sqlite3_mutex
19670 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65  _methods* */.#de
19680 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
19690 49 47 5f 47 45 54 4d 55 54 45 58 20 20 20 20 20  IG_GETMUTEX     
196a0 31 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d  11  /* sqlite3_m
196b0 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f  utex_methods* */
196c0 0a 2f 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 53  ./* previously S
196d0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55  QLITE_CONFIG_CHU
196e0 4e 4b 41 4c 4c 4f 43 20 31 32 20 77 68 69 63 68  NKALLOC 12 which
196f0 20 69 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20   is now unused. 
19700 2a 2f 20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  */ .#define SQLI
19710 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  TE_CONFIG_LOOKAS
19720 49 44 45 20 20 20 20 31 33 20 20 2f 2a 20 69 6e  IDE    13  /* in
19730 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65  t int */.#define
19740 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
19750 43 41 43 48 45 20 20 20 20 20 20 20 31 34 20 20  CACHE       14  
19760 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66  /* no-op */.#def
19770 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
19780 47 5f 47 45 54 50 43 41 43 48 45 20 20 20 20 31  G_GETPCACHE    1
19790 35 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23  5  /* no-op */.#
197a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
197b0 4e 46 49 47 5f 4c 4f 47 20 20 20 20 20 20 20 20  NFIG_LOG        
197c0 20 20 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c 20    16  /* xFunc, 
197d0 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  void* */.#define
197e0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55   SQLITE_CONFIG_U
197f0 52 49 20 20 20 20 20 20 20 20 20 20 31 37 20 20  RI          17  
19800 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e  /* int */.#defin
19810 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
19820 50 43 41 43 48 45 32 20 20 20 20 20 20 31 38 20  PCACHE2      18 
19830 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63   /* sqlite3_pcac
19840 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a  he_methods2* */.
19850 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
19860 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32  ONFIG_GETPCACHE2
19870 20 20 20 31 39 20 20 2f 2a 20 73 71 6c 69 74 65     19  /* sqlite
19880 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73  3_pcache_methods
19890 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  2* */.#define SQ
198a0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45  LITE_CONFIG_COVE
198b0 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20  RING_INDEX_SCAN 
198c0 32 30 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64  20  /* int */.#d
198d0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
198e0 46 49 47 5f 53 51 4c 4c 4f 47 20 20 20 20 20 20  FIG_SQLLOG      
198f0 20 32 31 20 20 2f 2a 20 78 53 71 6c 6c 6f 67 2c   21  /* xSqllog,
19900 20 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e   void* */.#defin
19910 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
19920 4d 4d 41 50 5f 53 49 5a 45 20 20 20 20 32 32 20  MMAP_SIZE    22 
19930 20 2f 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 36   /* sqlite3_int6
19940 34 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  4, sqlite3_int64
19950 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
19960 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f  REF: Database Co
19970 6e 6e 65 63 74 69 6f 6e 20 43 6f 6e 66 69 67 75  nnection Configu
19980 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a  ration Options.*
19990 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
199a0 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61  ants are the ava
199b0 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63  ilable integer c
199c0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
199d0 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e  ions that.** can
199e0 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68   be passed as th
199f0 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
19a00 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  t to the [sqlite
19a10 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69  3_db_config()] i
19a20 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
19a30 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  New configuratio
19a40 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65  n options may be
19a50 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
19a60 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c   releases of SQL
19a70 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67  ite..** Existing
19a80 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
19a90 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20  ptions might be 
19aa0 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41  discontinued.  A
19ab0 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73  pplications.** s
19ac0 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20  hould check the 
19ad0 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d  return code from
19ae0 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e   [sqlite3_db_con
19af0 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73  fig()] to make s
19b00 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  ure that.** the 
19b10 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 5e 54  call worked.  ^T
19b20 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63  he [sqlite3_db_c
19b30 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61  onfig()] interfa
19b40 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61  ce will return a
19b50 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72  .** non-zero [er
19b60 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64  ror code] if a d
19b70 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75  iscontinued or u
19b80 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69  nsupported confi
19b90 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a  guration option.
19ba0 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a  ** is invoked..*
19bb0 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74  *.** <dl>.** <dt
19bc0 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  >SQLITE_DBCONFIG
19bd0 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a  _LOOKASIDE</dt>.
19be0 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70  ** <dd> ^This op
19bf0 74 69 6f 6e 20 74 61 6b 65 73 20 74 68 72 65 65  tion takes three
19c00 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75   additional argu
19c10 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72  ments that deter
19c20 6d 69 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f  mine the .** [lo
19c30 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61  okaside memory a
19c40 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67  llocator] config
19c50 75 72 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20  uration for the 
19c60 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
19c70 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66  tion]..** ^The f
19c80 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 28 74  irst argument (t
19c90 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
19ca0 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64  er to [sqlite3_d
19cb0 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 73 20 61  b_config()] is a
19cc0 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  .** pointer to a
19cd0 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74   memory buffer t
19ce0 6f 20 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73  o use for lookas
19cf0 69 64 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e  ide memory..** ^
19d00 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
19d10 6e 74 20 61 66 74 65 72 20 74 68 65 20 53 51 4c  nt after the SQL
19d20 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
19d30 4b 41 53 49 44 45 20 76 65 72 62 0a 2a 2a 20 6d  KASIDE verb.** m
19d40 61 79 20 62 65 20 4e 55 4c 4c 20 69 6e 20 77 68  ay be NULL in wh
19d50 69 63 68 20 63 61 73 65 20 53 51 4c 69 74 65 20  ich case SQLite 
19d60 77 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 74 68  will allocate th
19d70 65 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65 20 62  e.** lookaside b
19d80 75 66 66 65 72 20 69 74 73 65 6c 66 20 75 73 69  uffer itself usi
19d90 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ng [sqlite3_mall
19da0 6f 63 28 29 5d 2e 20 5e 54 68 65 20 73 65 63 6f  oc()]. ^The seco
19db0 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  nd argument is t
19dc0 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61  he.** size of ea
19dd0 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66  ch lookaside buf
19de0 66 65 72 20 73 6c 6f 74 2e 20 20 5e 54 68 65 20  fer slot.  ^The 
19df0 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69  third argument i
19e00 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  s the number of.
19e10 2a 2a 20 73 6c 6f 74 73 2e 20 20 54 68 65 20 73  ** slots.  The s
19e20 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 65  ize of the buffe
19e30 72 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61  r in the first a
19e40 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20  rgument must be 
19e50 67 72 65 61 74 65 72 20 74 68 61 6e 0a 2a 2a 20  greater than.** 
19e60 6f 72 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20  or equal to the 
19e70 70 72 6f 64 75 63 74 20 6f 66 20 74 68 65 20 73  product of the s
19e80 65 63 6f 6e 64 20 61 6e 64 20 74 68 69 72 64 20  econd and third 
19e90 61 72 67 75 6d 65 6e 74 73 2e 20 20 54 68 65 20  arguments.  The 
19ea0 62 75 66 66 65 72 0a 2a 2a 20 6d 75 73 74 20 62  buffer.** must b
19eb0 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20  e aligned to an 
19ec0 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2e  8-byte boundary.
19ed0 20 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e 64    ^If the second
19ee0 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
19ef0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
19f00 4c 4f 4f 4b 41 53 49 44 45 20 69 73 20 6e 6f 74  LOOKASIDE is not
19f10 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38   a multiple of 8
19f20 2c 20 69 74 20 69 73 20 69 6e 74 65 72 6e 61 6c  , it is internal
19f30 6c 79 0a 2a 2a 20 72 6f 75 6e 64 65 64 20 64 6f  ly.** rounded do
19f40 77 6e 20 74 6f 20 74 68 65 20 6e 65 78 74 20 73  wn to the next s
19f50 6d 61 6c 6c 65 72 20 6d 75 6c 74 69 70 6c 65 20  maller multiple 
19f60 6f 66 20 38 2e 20 20 5e 28 54 68 65 20 6c 6f 6f  of 8.  ^(The loo
19f70 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a  kaside memory.**
19f80 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66   configuration f
19f90 6f 72 20 61 20 64 61 74 61 62 61 73 65 20 63 6f  or a database co
19fa0 6e 6e 65 63 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c  nnection can onl
19fb0 79 20 62 65 20 63 68 61 6e 67 65 64 20 77 68 65  y be changed whe
19fc0 6e 20 74 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63  n that.** connec
19fd0 74 69 6f 6e 20 69 73 20 6e 6f 74 20 63 75 72 72  tion is not curr
19fe0 65 6e 74 6c 79 20 75 73 69 6e 67 20 6c 6f 6f 6b  ently using look
19ff0 61 73 69 64 65 20 6d 65 6d 6f 72 79 2c 20 6f 72  aside memory, or
1a000 20 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 0a   in other words.
1a010 2a 2a 20 77 68 65 6e 20 74 68 65 20 22 63 75 72  ** when the "cur
1a020 72 65 6e 74 20 76 61 6c 75 65 22 20 72 65 74 75  rent value" retu
1a030 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69  rned by.** [sqli
1a040 74 65 33 5f 64 62 5f 73 74 61 74 75 73 5d 28 44  te3_db_status](D
1a050 2c 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  ,[SQLITE_CONFIG_
1a060 4c 4f 4f 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29 20  LOOKASIDE],...) 
1a070 69 73 20 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20  is zero..** Any 
1a080 61 74 74 65 6d 70 74 20 74 6f 20 63 68 61 6e 67  attempt to chang
1a090 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20  e the lookaside 
1a0a0 6d 65 6d 6f 72 79 20 63 6f 6e 66 69 67 75 72 61  memory configura
1a0b0 74 69 6f 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61 73  tion when lookas
1a0c0 69 64 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69 73  ide.** memory is
1a0d0 20 69 6e 20 75 73 65 20 6c 65 61 76 65 73 20 74   in use leaves t
1a0e0 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  he configuration
1a0f0 20 75 6e 63 68 61 6e 67 65 64 20 61 6e 64 20 72   unchanged and r
1a100 65 74 75 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49  eturns .** [SQLI
1a110 54 45 5f 42 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e  TE_BUSY].)^</dd>
1a120 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
1a130 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c  E_DBCONFIG_ENABL
1a140 45 5f 46 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20 3c  E_FKEY</dt>.** <
1a150 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  dd> ^This option
1a160 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62   is used to enab
1a170 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68  le or disable th
1a180 65 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 66  e enforcement of
1a190 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79  .** [foreign key
1a1a0 20 63 6f 6e 73 74 72 61 69 6e 74 73 5d 2e 20 20   constraints].  
1a1b0 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20  There should be 
1a1c0 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61  two additional a
1a1d0 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65  rguments..** The
1a1e0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
1a1f0 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68  is an integer wh
1a200 69 63 68 20 69 73 20 30 20 74 6f 20 64 69 73 61  ich is 0 to disa
1a210 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65  ble FK enforceme
1a220 6e 74 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20  nt,.** positive 
1a230 74 6f 20 65 6e 61 62 6c 65 20 46 4b 20 65 6e 66  to enable FK enf
1a240 6f 72 63 65 6d 65 6e 74 20 6f 72 20 6e 65 67 61  orcement or nega
1a250 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 46 4b  tive to leave FK
1a260 20 65 6e 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a 20   enforcement.** 
1a270 75 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20  unchanged.  The 
1a280 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
1a290 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
1a2a0 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f   an integer into
1a2b0 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69   which.** is wri
1a2c0 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69  tten 0 or 1 to i
1a2d0 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20  ndicate whether 
1a2e0 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 69  FK enforcement i
1a2f0 73 20 6f 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20 66  s off or on.** f
1a300 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61  ollowing this ca
1a310 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20  ll.  The second 
1a320 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65  parameter may be
1a330 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
1a340 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73   in.** which cas
1a350 65 20 74 68 65 20 46 4b 20 65 6e 66 6f 72 63 65  e the FK enforce
1a360 6d 65 6e 74 20 73 65 74 74 69 6e 67 20 69 73 20  ment setting is 
1a370 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 63  not reported bac
1a380 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  k. </dd>.**.** <
1a390 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  dt>SQLITE_DBCONF
1a3a0 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45  IG_ENABLE_TRIGGE
1a3b0 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  R</dt>.** <dd> ^
1a3c0 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75  This option is u
1a3d0 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72  sed to enable or
1a3e0 20 64 69 73 61 62 6c 65 20 5b 43 52 45 41 54 45   disable [CREATE
1a3f0 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67   TRIGGER | trigg
1a400 65 72 73 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73  ers]..** There s
1a410 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64  hould be two add
1a420 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74  itional argument
1a430 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  s..** The first 
1a440 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69  argument is an i
1a450 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20  nteger which is 
1a460 30 20 74 6f 20 64 69 73 61 62 6c 65 20 74 72 69  0 to disable tri
1a470 67 67 65 72 73 2c 0a 2a 2a 20 70 6f 73 69 74 69  ggers,.** positi
1a480 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 74 72 69  ve to enable tri
1a490 67 67 65 72 73 20 6f 72 20 6e 65 67 61 74 69 76  ggers or negativ
1a4a0 65 20 74 6f 20 6c 65 61 76 65 20 74 68 65 20 73  e to leave the s
1a4b0 65 74 74 69 6e 67 20 75 6e 63 68 61 6e 67 65 64  etting unchanged
1a4c0 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  ..** The second 
1a4d0 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70  parameter is a p
1a4e0 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74  ointer to an int
1a4f0 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a  eger into which.
1a500 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 20  ** is written 0 
1a510 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65  or 1 to indicate
1a520 20 77 68 65 74 68 65 72 20 74 72 69 67 67 65 72   whether trigger
1a530 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 6f  s are disabled o
1a540 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c  r enabled.** fol
1a550 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c  lowing this call
1a560 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  .  The second pa
1a570 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61  rameter may be a
1a580 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69   NULL pointer, i
1a590 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20  n.** which case 
1a5a0 74 68 65 20 74 72 69 67 67 65 72 20 73 65 74 74  the trigger sett
1a5b0 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72  ing is not repor
1a5c0 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a  ted back. </dd>.
1a5d0 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23  **.** </dl>.*/.#
1a5e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42  define SQLITE_DB
1a5f0 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
1a600 20 20 20 20 20 20 20 31 30 30 31 20 20 2f 2a 20         1001  /* 
1a610 76 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f  void* int int */
1a620 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1a630 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f  DBCONFIG_ENABLE_
1a640 46 4b 45 59 20 20 20 20 20 31 30 30 32 20 20 2f  FKEY     1002  /
1a650 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64  * int int* */.#d
1a660 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43  efine SQLITE_DBC
1a670 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49  ONFIG_ENABLE_TRI
1a680 47 47 45 52 20 20 31 30 30 33 20 20 2f 2a 20 69  GGER  1003  /* i
1a690 6e 74 20 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a  nt int* */.../*.
1a6a0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61  ** CAPI3REF: Ena
1a6b0 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45  ble Or Disable E
1a6c0 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43  xtended Result C
1a6d0 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  odes.**.** ^The 
1a6e0 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
1a6f0 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 20  _result_codes() 
1a700 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20  routine enables 
1a710 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 0a  or disables the.
1a720 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  ** [extended res
1a730 75 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 74 75  ult codes] featu
1a740 72 65 20 6f 66 20 53 51 4c 69 74 65 2e 20 5e 54  re of SQLite. ^T
1a750 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  he extended resu
1a760 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65 20  lt.** codes are 
1a770 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61  disabled by defa
1a780 75 6c 74 20 66 6f 72 20 68 69 73 74 6f 72 69 63  ult for historic
1a790 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  al compatibility
1a7a0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
1a7b0 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65  int sqlite3_exte
1a7c0 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65  nded_result_code
1a7d0 73 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20  s(sqlite3*, int 
1a7e0 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  onoff);../*.** C
1a7f0 41 50 49 33 52 45 46 3a 20 4c 61 73 74 20 49 6e  API3REF: Last In
1a800 73 65 72 74 20 52 6f 77 69 64 0a 2a 2a 0a 2a 2a  sert Rowid.**.**
1a810 20 5e 45 61 63 68 20 65 6e 74 72 79 20 69 6e 20   ^Each entry in 
1a820 61 6e 20 53 51 4c 69 74 65 20 74 61 62 6c 65 20  an SQLite table 
1a830 68 61 73 20 61 20 75 6e 69 71 75 65 20 36 34 2d  has a unique 64-
1a840 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20 69 6e  bit signed.** in
1a850 74 65 67 65 72 20 6b 65 79 20 63 61 6c 6c 65 64  teger key called
1a860 20 74 68 65 20 5b 52 4f 57 49 44 20 7c 20 22 72   the [ROWID | "r
1a870 6f 77 69 64 22 5d 2e 20 5e 54 68 65 20 72 6f 77  owid"]. ^The row
1a880 69 64 20 69 73 20 61 6c 77 61 79 73 20 61 76 61  id is always ava
1a890 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61 6e 20  ilable.** as an 
1a8a0 75 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d  undeclared colum
1a8b0 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c 20 4f  n named ROWID, O
1a8c0 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f 20 61  ID, or _ROWID_ a
1a8d0 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73 65 0a  s long as those.
1a8e0 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e 6f 74  ** names are not
1a8f0 20 61 6c 73 6f 20 75 73 65 64 20 62 79 20 65 78   also used by ex
1a900 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65  plicitly declare
1a910 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66 0a 2a  d columns. ^If.*
1a920 2a 20 74 68 65 20 74 61 62 6c 65 20 68 61 73 20  * the table has 
1a930 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 70 65  a column of type
1a940 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52   [INTEGER PRIMAR
1a950 59 20 4b 45 59 5d 20 74 68 65 6e 20 74 68 61 74  Y KEY] then that
1a960 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e   column.** is an
1a970 6f 74 68 65 72 20 61 6c 69 61 73 20 66 6f 72 20  other alias for 
1a980 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a  the rowid..**.**
1a990 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72   ^This routine r
1a9a0 65 74 75 72 6e 73 20 74 68 65 20 5b 72 6f 77 69  eturns the [rowi
1a9b0 64 5d 20 6f 66 20 74 68 65 20 6d 6f 73 74 20 72  d] of the most r
1a9c0 65 63 65 6e 74 0a 2a 2a 20 73 75 63 63 65 73 73  ecent.** success
1a9d0 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 69 6e 74  ful [INSERT] int
1a9e0 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  o the database f
1a9f0 72 6f 6d 20 74 68 65 20 5b 64 61 74 61 62 61 73  rom the [databas
1aa00 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a  e connection].**
1aa10 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
1aa20 67 75 6d 65 6e 74 2e 20 20 5e 41 73 20 6f 66 20  gument.  ^As of 
1aa30 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33  SQLite version 3
1aa40 2e 37 2e 37 2c 20 74 68 69 73 20 72 6f 75 74 69  .7.7, this routi
1aa50 6e 65 73 0a 2a 2a 20 72 65 63 6f 72 64 73 20 74  nes.** records t
1aa60 68 65 20 6c 61 73 74 20 69 6e 73 65 72 74 20 72  he last insert r
1aa70 6f 77 69 64 20 6f 66 20 62 6f 74 68 20 6f 72 64  owid of both ord
1aa80 69 6e 61 72 79 20 74 61 62 6c 65 73 20 61 6e 64  inary tables and
1aa90 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73   [virtual tables
1aaa0 5d 2e 0a 2a 2a 20 5e 49 66 20 6e 6f 20 73 75 63  ]..** ^If no suc
1aab0 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d  cessful [INSERT]
1aac0 73 0a 2a 2a 20 68 61 76 65 20 65 76 65 72 20 6f  s.** have ever o
1aad0 63 63 75 72 72 65 64 20 6f 6e 20 74 68 61 74 20  ccurred on that 
1aae0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1aaf0 69 6f 6e 2c 20 7a 65 72 6f 20 69 73 20 72 65 74  ion, zero is ret
1ab00 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49  urned..**.** ^(I
1ab10 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 6f 63  f an [INSERT] oc
1ab20 63 75 72 73 20 77 69 74 68 69 6e 20 61 20 74 72  curs within a tr
1ab30 69 67 67 65 72 20 6f 72 20 77 69 74 68 69 6e 20  igger or within 
1ab40 61 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65  a [virtual table
1ab50 5d 0a 2a 2a 20 6d 65 74 68 6f 64 2c 20 74 68 65  ].** method, the
1ab60 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  n this routine w
1ab70 69 6c 6c 20 72 65 74 75 72 6e 20 74 68 65 20 5b  ill return the [
1ab80 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 69 6e  rowid] of the in
1ab90 73 65 72 74 65 64 0a 2a 2a 20 72 6f 77 20 61 73  serted.** row as
1aba0 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 72 69   long as the tri
1abb0 67 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c 20  gger or virtual 
1abc0 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 69 73 20  table method is 
1abd0 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74 20  running..** But 
1abe0 6f 6e 63 65 20 74 68 65 20 74 72 69 67 67 65 72  once the trigger
1abf0 20 6f 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c   or virtual tabl
1ac00 65 20 6d 65 74 68 6f 64 20 65 6e 64 73 2c 20 74  e method ends, t
1ac10 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
1ac20 64 20 0a 2a 2a 20 62 79 20 74 68 69 73 20 72 6f  d .** by this ro
1ac30 75 74 69 6e 65 20 72 65 76 65 72 74 73 20 74 6f  utine reverts to
1ac40 20 77 68 61 74 20 69 74 20 77 61 73 20 62 65 66   what it was bef
1ac50 6f 72 65 20 74 68 65 20 74 72 69 67 67 65 72 20  ore the trigger 
1ac60 6f 72 20 76 69 72 74 75 61 6c 0a 2a 2a 20 74 61  or virtual.** ta
1ac70 62 6c 65 20 6d 65 74 68 6f 64 20 62 65 67 61 6e  ble method began
1ac80 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b 49  .)^.**.** ^An [I
1ac90 4e 53 45 52 54 5d 20 74 68 61 74 20 66 61 69 6c  NSERT] that fail
1aca0 73 20 64 75 65 20 74 6f 20 61 20 63 6f 6e 73 74  s due to a const
1acb0 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20  raint violation 
1acc0 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63 63  is not a.** succ
1acd0 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20  essful [INSERT] 
1ace0 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63 68 61  and does not cha
1acf0 6e 67 65 20 74 68 65 20 76 61 6c 75 65 20 72 65  nge the value re
1ad00 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 0a 2a  turned by this.*
1ad10 2a 20 72 6f 75 74 69 6e 65 2e 20 20 5e 54 68 75  * routine.  ^Thu
1ad20 73 20 49 4e 53 45 52 54 20 4f 52 20 46 41 49 4c  s INSERT OR FAIL
1ad30 2c 20 49 4e 53 45 52 54 20 4f 52 20 49 47 4e 4f  , INSERT OR IGNO
1ad40 52 45 2c 20 49 4e 53 45 52 54 20 4f 52 20 52 4f  RE, INSERT OR RO
1ad50 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49  LLBACK,.** and I
1ad60 4e 53 45 52 54 20 4f 52 20 41 42 4f 52 54 20 6d  NSERT OR ABORT m
1ad70 61 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73 20 74  ake no changes t
1ad80 6f 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  o the return val
1ad90 75 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72 6f  ue of this.** ro
1ada0 75 74 69 6e 65 20 77 68 65 6e 20 74 68 65 69 72  utine when their
1adb0 20 69 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 73   insertion fails
1adc0 2e 20 20 5e 28 57 68 65 6e 20 49 4e 53 45 52 54  .  ^(When INSERT
1add0 20 4f 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20 65   OR REPLACE.** e
1ade0 6e 63 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e 73  ncounters a cons
1adf0 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e  traint violation
1ae00 2c 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 66 61  , it does not fa
1ae10 69 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45  il.  The.** INSE
1ae20 52 54 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20  RT continues to 
1ae30 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65 72  completion after
1ae40 20 64 65 6c 65 74 69 6e 67 20 72 6f 77 73 20 74   deleting rows t
1ae50 68 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 74 68  hat caused.** th
1ae60 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f  e constraint pro
1ae70 62 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f  blem so INSERT O
1ae80 52 20 52 45 50 4c 41 43 45 20 77 69 6c 6c 20 61  R REPLACE will a
1ae90 6c 77 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20  lways change.** 
1aea0 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
1aeb0 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66 61   of this interfa
1aec0 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72  ce.)^.**.** ^For
1aed0 20 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66   the purposes of
1aee0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 61   this routine, a
1aef0 6e 20 5b 49 4e 53 45 52 54 5d 20 69 73 20 63 6f  n [INSERT] is co
1af00 6e 73 69 64 65 72 65 64 20 74 6f 0a 2a 2a 20 62  nsidered to.** b
1af10 65 20 73 75 63 63 65 73 73 66 75 6c 20 65 76 65  e successful eve
1af20 6e 20 69 66 20 69 74 20 69 73 20 73 75 62 73 65  n if it is subse
1af30 71 75 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 20 62  quently rolled b
1af40 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ack..**.** This 
1af50 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 63 63 65  function is acce
1af60 73 73 69 62 6c 65 20 74 6f 20 53 51 4c 20 73 74  ssible to SQL st
1af70 61 74 65 6d 65 6e 74 73 20 76 69 61 20 74 68 65  atements via the
1af80 0a 2a 2a 20 5b 6c 61 73 74 5f 69 6e 73 65 72 74  .** [last_insert
1af90 5f 72 6f 77 69 64 28 29 20 53 51 4c 20 66 75 6e  _rowid() SQL fun
1afa0 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66  ction]..**.** If
1afb0 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65   a separate thre
1afc0 61 64 20 70 65 72 66 6f 72 6d 73 20 61 20 6e 65  ad performs a ne
1afd0 77 20 5b 49 4e 53 45 52 54 5d 20 6f 6e 20 74 68  w [INSERT] on th
1afe0 65 20 73 61 6d 65 0a 2a 2a 20 64 61 74 61 62 61  e same.** databa
1aff0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68  se connection wh
1b000 69 6c 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ile the [sqlite3
1b010 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
1b020 69 64 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f  id()].** functio
1b030 6e 20 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64  n is running and
1b040 20 74 68 75 73 20 63 68 61 6e 67 65 73 20 74 68   thus changes th
1b050 65 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72  e last insert [r
1b060 6f 77 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74  owid],.** then t
1b070 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
1b080 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61  d by [sqlite3_la
1b090 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
1b0a0 29 5d 20 69 73 0a 2a 2a 20 75 6e 70 72 65 64 69  )] is.** unpredi
1b0b0 63 74 61 62 6c 65 20 61 6e 64 20 6d 69 67 68 74  ctable and might
1b0c0 20 6e 6f 74 20 65 71 75 61 6c 20 65 69 74 68 65   not equal eithe
1b0d0 72 20 74 68 65 20 6f 6c 64 20 6f 72 20 74 68 65  r the old or the
1b0e0 20 6e 65 77 0a 2a 2a 20 6c 61 73 74 20 69 6e 73   new.** last ins
1b0f0 65 72 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a  ert [rowid]..*/.
1b100 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74  SQLITE_API sqlit
1b110 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
1b120 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
1b130 69 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  id(sqlite3*);../
1b140 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
1b150 6f 75 6e 74 20 54 68 65 20 4e 75 6d 62 65 72 20  ount The Number 
1b160 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64  Of Rows Modified
1b170 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e  .**.** ^This fun
1b180 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
1b190 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 61 74 61  e number of data
1b1a0 62 61 73 65 20 72 6f 77 73 20 74 68 61 74 20 77  base rows that w
1b1b0 65 72 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 6f  ere changed.** o
1b1c0 72 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65  r inserted or de
1b1d0 6c 65 74 65 64 20 62 79 20 74 68 65 20 6d 6f 73  leted by the mos
1b1e0 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c  t recently compl
1b1f0 65 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65  eted SQL stateme
1b200 6e 74 0a 2a 2a 20 6f 6e 20 74 68 65 20 5b 64 61  nt.** on the [da
1b210 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1b220 6e 5d 20 73 70 65 63 69 66 69 65 64 20 62 79 20  n] specified by 
1b230 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
1b240 74 65 72 2e 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 63  ter..** ^(Only c
1b250 68 61 6e 67 65 73 20 74 68 61 74 20 61 72 65 20  hanges that are 
1b260 64 69 72 65 63 74 6c 79 20 73 70 65 63 69 66 69  directly specifi
1b270 65 64 20 62 79 20 74 68 65 20 5b 49 4e 53 45 52  ed by the [INSER
1b280 54 5d 2c 20 5b 55 50 44 41 54 45 5d 2c 0a 2a 2a  T], [UPDATE],.**
1b290 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61   or [DELETE] sta
1b2a0 74 65 6d 65 6e 74 20 61 72 65 20 63 6f 75 6e 74  tement are count
1b2b0 65 64 2e 20 20 41 75 78 69 6c 69 61 72 79 20 63  ed.  Auxiliary c
1b2c0 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79  hanges caused by
1b2d0 0a 2a 2a 20 74 72 69 67 67 65 72 73 20 6f 72 20  .** triggers or 
1b2e0 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74  [foreign key act
1b2f0 69 6f 6e 73 5d 20 61 72 65 20 6e 6f 74 20 63 6f  ions] are not co
1b300 75 6e 74 65 64 2e 29 5e 20 55 73 65 20 74 68 65  unted.)^ Use the
1b310 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74  .** [sqlite3_tot
1b320 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 66 75  al_changes()] fu
1b330 6e 63 74 69 6f 6e 20 74 6f 20 66 69 6e 64 20 74  nction to find t
1b340 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20  he total number 
1b350 6f 66 20 63 68 61 6e 67 65 73 0a 2a 2a 20 69 6e  of changes.** in
1b360 63 6c 75 64 69 6e 67 20 63 68 61 6e 67 65 73 20  cluding changes 
1b370 63 61 75 73 65 64 20 62 79 20 74 72 69 67 67 65  caused by trigge
1b380 72 73 20 61 6e 64 20 66 6f 72 65 69 67 6e 20 6b  rs and foreign k
1b390 65 79 20 61 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a  ey actions..**.*
1b3a0 2a 20 5e 43 68 61 6e 67 65 73 20 74 6f 20 61 20  * ^Changes to a 
1b3b0 76 69 65 77 20 74 68 61 74 20 61 72 65 20 73 69  view that are si
1b3c0 6d 75 6c 61 74 65 64 20 62 79 20 61 6e 20 5b 49  mulated by an [I
1b3d0 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65  NSTEAD OF trigge
1b3e0 72 5d 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 63 6f  r].** are not co
1b3f0 75 6e 74 65 64 2e 20 20 4f 6e 6c 79 20 72 65 61  unted.  Only rea
1b400 6c 20 74 61 62 6c 65 20 63 68 61 6e 67 65 73 20  l table changes 
1b410 61 72 65 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a  are counted..**.
1b420 2a 2a 20 5e 28 41 20 22 72 6f 77 20 63 68 61 6e  ** ^(A "row chan
1b430 67 65 22 20 69 73 20 61 20 63 68 61 6e 67 65 20  ge" is a change 
1b440 74 6f 20 61 20 73 69 6e 67 6c 65 20 72 6f 77 20  to a single row 
1b450 6f 66 20 61 20 73 69 6e 67 6c 65 20 74 61 62 6c  of a single tabl
1b460 65 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20 61  e.** caused by a
1b470 6e 20 49 4e 53 45 52 54 2c 20 44 45 4c 45 54 45  n INSERT, DELETE
1b480 2c 20 6f 72 20 55 50 44 41 54 45 20 73 74 61 74  , or UPDATE stat
1b490 65 6d 65 6e 74 2e 20 20 52 6f 77 73 20 74 68 61  ement.  Rows tha
1b4a0 74 0a 2a 2a 20 61 72 65 20 63 68 61 6e 67 65 64  t.** are changed
1b4b0 20 61 73 20 73 69 64 65 20 65 66 66 65 63 74 73   as side effects
1b4c0 20 6f 66 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f   of [REPLACE] co
1b4d0 6e 73 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74  nstraint resolut
1b4e0 69 6f 6e 2c 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b  ion,.** rollback
1b4f0 2c 20 41 42 4f 52 54 20 70 72 6f 63 65 73 73 69  , ABORT processi
1b500 6e 67 2c 20 5b 44 52 4f 50 20 54 41 42 4c 45 5d  ng, [DROP TABLE]
1b510 2c 20 6f 72 20 62 79 20 61 6e 79 20 6f 74 68 65  , or by any othe
1b520 72 0a 2a 2a 20 6d 65 63 68 61 6e 69 73 6d 73 20  r.** mechanisms 
1b530 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20  do not count as 
1b540 64 69 72 65 63 74 20 72 6f 77 20 63 68 61 6e 67  direct row chang
1b550 65 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 22 74  es.)^.**.** A "t
1b560 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 22 20  rigger context" 
1b570 69 73 20 61 20 73 63 6f 70 65 20 6f 66 20 65 78  is a scope of ex
1b580 65 63 75 74 69 6f 6e 20 74 68 61 74 20 62 65 67  ecution that beg
1b590 69 6e 73 20 61 6e 64 0a 2a 2a 20 65 6e 64 73 20  ins and.** ends 
1b5a0 77 69 74 68 20 74 68 65 20 73 63 72 69 70 74 20  with the script 
1b5b0 6f 66 20 61 20 5b 43 52 45 41 54 45 20 54 52 49  of a [CREATE TRI
1b5c0 47 47 45 52 20 7c 20 74 72 69 67 67 65 72 5d 2e  GGER | trigger].
1b5d0 20 0a 2a 2a 20 4d 6f 73 74 20 53 51 4c 20 73 74   .** Most SQL st
1b5e0 61 74 65 6d 65 6e 74 73 20 61 72 65 0a 2a 2a 20  atements are.** 
1b5f0 65 76 61 6c 75 61 74 65 64 20 6f 75 74 73 69 64  evaluated outsid
1b600 65 20 6f 66 20 61 6e 79 20 74 72 69 67 67 65 72  e of any trigger
1b610 2e 20 20 54 68 69 73 20 69 73 20 74 68 65 20 22  .  This is the "
1b620 74 6f 70 20 6c 65 76 65 6c 22 0a 2a 2a 20 74 72  top level".** tr
1b630 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 20 20  igger context.  
1b640 49 66 20 61 20 74 72 69 67 67 65 72 20 66 69 72  If a trigger fir
1b650 65 73 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 20  es from the top 
1b660 6c 65 76 65 6c 2c 20 61 0a 2a 2a 20 6e 65 77 20  level, a.** new 
1b670 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 20  trigger context 
1b680 69 73 20 65 6e 74 65 72 65 64 20 66 6f 72 20 74  is entered for t
1b690 68 65 20 64 75 72 61 74 69 6f 6e 20 6f 66 20 74  he duration of t
1b6a0 68 61 74 20 6f 6e 65 0a 2a 2a 20 74 72 69 67 67  hat one.** trigg
1b6b0 65 72 2e 20 20 53 75 62 74 72 69 67 67 65 72 73  er.  Subtriggers
1b6c0 20 63 72 65 61 74 65 20 73 75 62 63 6f 6e 74 65   create subconte
1b6d0 78 74 73 20 66 6f 72 20 74 68 65 69 72 20 64 75  xts for their du
1b6e0 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 43  ration..**.** ^C
1b6f0 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
1b700 65 78 65 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69  exec()] or [sqli
1b710 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65 63 75  te3_step()] recu
1b720 72 73 69 76 65 6c 79 20 64 6f 65 73 0a 2a 2a 20  rsively does.** 
1b730 6e 6f 74 20 63 72 65 61 74 65 20 61 20 6e 65 77  not create a new
1b740 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74   trigger context
1b750 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75  ..**.** ^This fu
1b760 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74  nction returns t
1b770 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 69 72  he number of dir
1b780 65 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73 20  ect row changes 
1b790 69 6e 20 74 68 65 0a 2a 2a 20 6d 6f 73 74 20 72  in the.** most r
1b7a0 65 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 50  ecent INSERT, UP
1b7b0 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 20  DATE, or DELETE 
1b7c0 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e  statement within
1b7d0 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 74 72 69   the same.** tri
1b7e0 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a  gger context..**
1b7f0 0a 2a 2a 20 5e 54 68 75 73 2c 20 77 68 65 6e 20  .** ^Thus, when 
1b800 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20  called from the 
1b810 74 6f 70 20 6c 65 76 65 6c 2c 20 74 68 69 73 20  top level, this 
1b820 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
1b830 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f   the.** number o
1b840 66 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65  f changes in the
1b850 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53   most recent INS
1b860 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20  ERT, UPDATE, or 
1b870 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 61  DELETE.** that a
1b880 6c 73 6f 20 6f 63 63 75 72 72 65 64 20 61 74 20  lso occurred at 
1b890 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2e 20 20  the top level.  
1b8a0 5e 28 57 69 74 68 69 6e 20 74 68 65 20 62 6f 64  ^(Within the bod
1b8b0 79 20 6f 66 20 61 20 74 72 69 67 67 65 72 2c 0a  y of a trigger,.
1b8c0 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  ** the sqlite3_c
1b8d0 68 61 6e 67 65 73 28 29 20 69 6e 74 65 72 66 61  hanges() interfa
1b8e0 63 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64  ce can be called
1b8f0 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d   to find the num
1b900 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 6e 67 65  ber of.** change
1b910 73 20 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 65  s in the most re
1b920 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64  cently completed
1b930 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c   INSERT, UPDATE,
1b940 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74   or DELETE.** st
1b950 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74  atement within t
1b960 68 65 20 62 6f 64 79 20 6f 66 20 74 68 65 20 73  he body of the s
1b970 61 6d 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a 20  ame trigger..** 
1b980 48 6f 77 65 76 65 72 2c 20 74 68 65 20 6e 75 6d  However, the num
1b990 62 65 72 20 72 65 74 75 72 6e 65 64 20 64 6f 65  ber returned doe
1b9a0 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63 68  s not include ch
1b9b0 61 6e 67 65 73 0a 2a 2a 20 63 61 75 73 65 64 20  anges.** caused 
1b9c0 62 79 20 73 75 62 74 72 69 67 67 65 72 73 20 73  by subtriggers s
1b9d0 69 6e 63 65 20 74 68 6f 73 65 20 68 61 76 65 20  ince those have 
1b9e0 74 68 65 69 72 20 6f 77 6e 20 63 6f 6e 74 65 78  their own contex
1b9f0 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  t.)^.**.** See a
1ba00 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33  lso the [sqlite3
1ba10 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29  _total_changes()
1ba20 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65  ] interface, the
1ba30 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67  .** [count_chang
1ba40 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20  es pragma], and 
1ba50 74 68 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53  the [changes() S
1ba60 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a  QL function]..**
1ba70 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74  .** If a separat
1ba80 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63  e thread makes c
1ba90 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61  hanges on the sa
1baa0 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
1bab0 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20  ection.** while 
1bac0 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73  [sqlite3_changes
1bad0 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74  ()] is running t
1bae0 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65  hen the value re
1baf0 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70  turned.** is unp
1bb00 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e  redictable and n
1bb10 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a  ot meaningful..*
1bb20 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
1bb30 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73   sqlite3_changes
1bb40 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
1bb50 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 6f 74  ** CAPI3REF: Tot
1bb60 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77  al Number Of Row
1bb70 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a  s Modified.**.**
1bb80 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20   ^This function 
1bb90 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
1bba0 65 72 20 6f 66 20 72 6f 77 20 63 68 61 6e 67 65  er of row change
1bbb0 73 20 63 61 75 73 65 64 20 62 79 20 5b 49 4e 53  s caused by [INS
1bbc0 45 52 54 5d 2c 0a 2a 2a 20 5b 55 50 44 41 54 45  ERT],.** [UPDATE
1bbd0 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74  ] or [DELETE] st
1bbe0 61 74 65 6d 65 6e 74 73 20 73 69 6e 63 65 20 74  atements since t
1bbf0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
1bc00 6e 65 63 74 69 6f 6e 5d 20 77 61 73 20 6f 70 65  nection] was ope
1bc10 6e 65 64 2e 0a 2a 2a 20 5e 28 54 68 65 20 63 6f  ned..** ^(The co
1bc20 75 6e 74 20 72 65 74 75 72 6e 65 64 20 62 79 20  unt returned by 
1bc30 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
1bc40 61 6e 67 65 73 28 29 20 69 6e 63 6c 75 64 65 73  anges() includes
1bc50 20 61 6c 6c 20 63 68 61 6e 67 65 73 0a 2a 2a 20   all changes.** 
1bc60 66 72 6f 6d 20 61 6c 6c 20 5b 43 52 45 41 54 45  from all [CREATE
1bc70 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67   TRIGGER | trigg
1bc80 65 72 5d 20 63 6f 6e 74 65 78 74 73 20 61 6e 64  er] contexts and
1bc90 20 63 68 61 6e 67 65 73 20 6d 61 64 65 20 62 79   changes made by
1bca0 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79  .** [foreign key
1bcb0 20 61 63 74 69 6f 6e 73 5d 2e 20 48 6f 77 65 76   actions]. Howev
1bcc0 65 72 2c 0a 2a 2a 20 74 68 65 20 63 6f 75 6e 74  er,.** the count
1bcd0 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64   does not includ
1bce0 65 20 63 68 61 6e 67 65 73 20 75 73 65 64 20 74  e changes used t
1bcf0 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b 52 45 50  o implement [REP
1bd00 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74  LACE] constraint
1bd10 73 2c 0a 2a 2a 20 64 6f 20 72 6f 6c 6c 62 61 63  s,.** do rollbac
1bd20 6b 73 20 6f 72 20 41 42 4f 52 54 20 70 72 6f 63  ks or ABORT proc
1bd30 65 73 73 69 6e 67 2c 20 6f 72 20 5b 44 52 4f 50  essing, or [DROP
1bd40 20 54 41 42 4c 45 5d 20 70 72 6f 63 65 73 73 69   TABLE] processi
1bd50 6e 67 2e 20 20 54 68 65 0a 2a 2a 20 63 6f 75 6e  ng.  The.** coun
1bd60 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75  t does not inclu
1bd70 64 65 20 72 6f 77 73 20 6f 66 20 76 69 65 77 73  de rows of views
1bd80 20 74 68 61 74 20 66 69 72 65 20 61 6e 20 5b 49   that fire an [I
1bd90 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65  NSTEAD OF trigge
1bda0 72 5d 2c 0a 2a 2a 20 74 68 6f 75 67 68 20 69 66  r],.** though if
1bdb0 20 74 68 65 20 49 4e 53 54 45 41 44 20 4f 46 20   the INSTEAD OF 
1bdc0 74 72 69 67 67 65 72 20 6d 61 6b 65 73 20 63 68  trigger makes ch
1bdd0 61 6e 67 65 73 20 6f 66 20 69 74 73 20 6f 77 6e  anges of its own
1bde0 2c 20 74 68 6f 73 65 20 63 68 61 6e 67 65 73 20  , those changes 
1bdf0 0a 2a 2a 20 61 72 65 20 63 6f 75 6e 74 65 64 2e  .** are counted.
1be00 29 5e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  )^.** ^The sqlit
1be10 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
1be20 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 6f 75 6e  () function coun
1be30 74 73 20 74 68 65 20 63 68 61 6e 67 65 73 20 61  ts the changes a
1be40 73 20 73 6f 6f 6e 20 61 73 0a 2a 2a 20 74 68 65  s soon as.** the
1be50 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20   statement that 
1be60 6d 61 6b 65 73 20 74 68 65 6d 20 69 73 20 63 6f  makes them is co
1be70 6d 70 6c 65 74 65 64 20 28 77 68 65 6e 20 74 68  mpleted (when th
1be80 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  e statement hand
1be90 6c 65 0a 2a 2a 20 69 73 20 70 61 73 73 65 64 20  le.** is passed 
1bea0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  to [sqlite3_rese
1beb0 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  t()] or [sqlite3
1bec0 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 29 2e 0a 2a  _finalize()])..*
1bed0 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68  *.** See also th
1bee0 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  e [sqlite3_chang
1bef0 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c  es()] interface,
1bf00 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63   the.** [count_c
1bf10 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20  hanges pragma], 
1bf20 61 6e 64 20 74 68 65 20 5b 74 6f 74 61 6c 5f 63  and the [total_c
1bf30 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e  hanges() SQL fun
1bf40 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66  ction]..**.** If
1bf50 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65   a separate thre
1bf60 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73  ad makes changes
1bf70 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74   on the same dat
1bf80 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1bf90 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74  .** while [sqlit
1bfa0 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
1bfb0 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74  ()] is running t
1bfc0 68 65 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a  hen the value.**
1bfd0 20 72 65 74 75 72 6e 65 64 20 69 73 20 75 6e 70   returned is unp
1bfe0 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e  redictable and n
1bff0 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a  ot meaningful..*
1c000 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
1c010 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63   sqlite3_total_c
1c020 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29  hanges(sqlite3*)
1c030 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1c040 46 3a 20 49 6e 74 65 72 72 75 70 74 20 41 20 4c  F: Interrupt A L
1c050 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72  ong-Running Quer
1c060 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75  y.**.** ^This fu
1c070 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20 61 6e  nction causes an
1c080 79 20 70 65 6e 64 69 6e 67 20 64 61 74 61 62 61  y pending databa
1c090 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20  se operation to 
1c0a0 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 65 74  abort and.** ret
1c0b0 75 72 6e 20 61 74 20 69 74 73 20 65 61 72 6c 69  urn at its earli
1c0c0 65 73 74 20 6f 70 70 6f 72 74 75 6e 69 74 79 2e  est opportunity.
1c0d0 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73   This routine is
1c0e0 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 63 61   typically.** ca
1c0f0 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e 73 65  lled in response
1c100 20 74 6f 20 61 20 75 73 65 72 20 61 63 74 69 6f   to a user actio
1c110 6e 20 73 75 63 68 20 61 73 20 70 72 65 73 73 69  n such as pressi
1c120 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f  ng "Cancel".** o
1c130 72 20 43 74 72 6c 2d 43 20 77 68 65 72 65 20 74  r Ctrl-C where t
1c140 68 65 20 75 73 65 72 20 77 61 6e 74 73 20 61 20  he user wants a 
1c150 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70 65 72 61  long query opera
1c160 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a 20  tion to halt.** 
1c170 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a  immediately..**.
1c180 2a 2a 20 5e 49 74 20 69 73 20 73 61 66 65 20 74  ** ^It is safe t
1c190 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74  o call this rout
1c1a0 69 6e 65 20 66 72 6f 6d 20 61 20 74 68 72 65 61  ine from a threa
1c1b0 64 20 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d  d different from
1c1c0 20 74 68 65 0a 2a 2a 20 74 68 72 65 61 64 20 74   the.** thread t
1c1d0 68 61 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79  hat is currently
1c1e0 20 72 75 6e 6e 69 6e 67 20 74 68 65 20 64 61 74   running the dat
1c1f0 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 2e  abase operation.
1c200 20 20 42 75 74 20 69 74 0a 2a 2a 20 69 73 20 6e    But it.** is n
1c210 6f 74 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20  ot safe to call 
1c220 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74  this routine wit
1c230 68 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  h a [database co
1c240 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 0a 2a  nnection] that.*
1c250 2a 20 69 73 20 63 6c 6f 73 65 64 20 6f 72 20 6d  * is closed or m
1c260 69 67 68 74 20 63 6c 6f 73 65 20 62 65 66 6f 72  ight close befor
1c270 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  e sqlite3_interr
1c280 75 70 74 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a  upt() returns..*
1c290 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 53 51 4c 20  *.** ^If an SQL 
1c2a0 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 76 65 72  operation is ver
1c2b0 79 20 6e 65 61 72 6c 79 20 66 69 6e 69 73 68 65  y nearly finishe
1c2c0 64 20 61 74 20 74 68 65 20 74 69 6d 65 20 77 68  d at the time wh
1c2d0 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e  en.** sqlite3_in
1c2e0 74 65 72 72 75 70 74 28 29 20 69 73 20 63 61 6c  terrupt() is cal
1c2f0 6c 65 64 2c 20 74 68 65 6e 20 69 74 20 6d 69 67  led, then it mig
1c300 68 74 20 6e 6f 74 20 68 61 76 65 20 61 6e 20 6f  ht not have an o
1c310 70 70 6f 72 74 75 6e 69 74 79 0a 2a 2a 20 74 6f  pportunity.** to
1c320 20 62 65 20 69 6e 74 65 72 72 75 70 74 65 64 20   be interrupted 
1c330 61 6e 64 20 6d 69 67 68 74 20 63 6f 6e 74 69 6e  and might contin
1c340 75 65 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e  ue to completion
1c350 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 53 51 4c 20  ..**.** ^An SQL 
1c360 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20 69  operation that i
1c370 73 20 69 6e 74 65 72 72 75 70 74 65 64 20 77 69  s interrupted wi
1c380 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ll return [SQLIT
1c390 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a  E_INTERRUPT]..**
1c3a0 20 5e 49 66 20 74 68 65 20 69 6e 74 65 72 72 75   ^If the interru
1c3b0 70 74 65 64 20 53 51 4c 20 6f 70 65 72 61 74 69  pted SQL operati
1c3c0 6f 6e 20 69 73 20 61 6e 20 49 4e 53 45 52 54 2c  on is an INSERT,
1c3d0 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45   UPDATE, or DELE
1c3e0 54 45 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e  TE.** that is in
1c3f0 73 69 64 65 20 61 6e 20 65 78 70 6c 69 63 69 74  side an explicit
1c400 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68   transaction, th
1c410 65 6e 20 74 68 65 20 65 6e 74 69 72 65 20 74 72  en the entire tr
1c420 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c  ansaction.** wil
1c430 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b  l be rolled back
1c440 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a   automatically..
1c450 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1c460 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20  e3_interrupt(D) 
1c470 63 61 6c 6c 20 69 73 20 69 6e 20 65 66 66 65 63  call is in effec
1c480 74 20 75 6e 74 69 6c 20 61 6c 6c 20 63 75 72 72  t until all curr
1c490 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 0a 2a 2a  ently running.**
1c4a0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
1c4b0 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  on [database con
1c4c0 6e 65 63 74 69 6f 6e 5d 20 44 20 63 6f 6d 70 6c  nection] D compl
1c4d0 65 74 65 2e 20 20 5e 41 6e 79 20 6e 65 77 20 53  ete.  ^Any new S
1c4e0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
1c4f0 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65   that are starte
1c500 64 20 61 66 74 65 72 20 74 68 65 20 73 71 6c 69  d after the sqli
1c510 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20  te3_interrupt() 
1c520 63 61 6c 6c 20 61 6e 64 20 62 65 66 6f 72 65 20  call and before 
1c530 74 68 65 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20  the .** running 
1c540 73 74 61 74 65 6d 65 6e 74 73 20 72 65 61 63 68  statements reach
1c550 65 73 20 7a 65 72 6f 20 61 72 65 20 69 6e 74 65  es zero are inte
1c560 72 72 75 70 74 65 64 20 61 73 20 69 66 20 74 68  rrupted as if th
1c570 65 79 20 68 61 64 20 62 65 65 6e 0a 2a 2a 20 72  ey had been.** r
1c580 75 6e 6e 69 6e 67 20 70 72 69 6f 72 20 74 6f 20  unning prior to 
1c590 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  the sqlite3_inte
1c5a0 72 72 75 70 74 28 29 20 63 61 6c 6c 2e 20 20 5e  rrupt() call.  ^
1c5b0 4e 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  New SQL statemen
1c5c0 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73  ts.** that are s
1c5d0 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65  tarted after the
1c5e0 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65   running stateme
1c5f0 6e 74 20 63 6f 75 6e 74 20 72 65 61 63 68 65 73  nt count reaches
1c600 20 7a 65 72 6f 20 61 72 65 0a 2a 2a 20 6e 6f 74   zero are.** not
1c610 20 65 66 66 65 63 74 65 64 20 62 79 20 74 68 65   effected by the
1c620 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
1c630 70 74 28 29 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c  pt()..** ^A call
1c640 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 74 65   to sqlite3_inte
1c650 72 72 75 70 74 28 44 29 20 74 68 61 74 20 6f 63  rrupt(D) that oc
1c660 63 75 72 73 20 77 68 65 6e 20 74 68 65 72 65 20  curs when there 
1c670 61 72 65 20 6e 6f 20 72 75 6e 6e 69 6e 67 0a 2a  are no running.*
1c680 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  * SQL statements
1c690 20 69 73 20 61 20 6e 6f 2d 6f 70 20 61 6e 64 20   is a no-op and 
1c6a0 68 61 73 20 6e 6f 20 65 66 66 65 63 74 20 6f 6e  has no effect on
1c6b0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
1c6c0 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72  ** that are star
1c6d0 74 65 64 20 61 66 74 65 72 20 74 68 65 20 73 71  ted after the sq
1c6e0 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
1c6f0 29 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 0a  ) call returns..
1c700 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 64 61 74  **.** If the dat
1c710 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1c720 20 63 6c 6f 73 65 73 20 77 68 69 6c 65 20 5b 73   closes while [s
1c730 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
1c740 28 29 5d 0a 2a 2a 20 69 73 20 72 75 6e 6e 69 6e  ()].** is runnin
1c750 67 20 74 68 65 6e 20 62 61 64 20 74 68 69 6e 67  g then bad thing
1c760 73 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 68 61  s will likely ha
1c770 70 70 65 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  ppen..*/.SQLITE_
1c780 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33  API void sqlite3
1c790 5f 69 6e 74 65 72 72 75 70 74 28 73 71 6c 69 74  _interrupt(sqlit
1c7a0 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
1c7b0 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65  I3REF: Determine
1c7c0 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65   If An SQL State
1c7d0 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74 65  ment Is Complete
1c7e0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
1c7f0 74 69 6e 65 73 20 61 72 65 20 75 73 65 66 75 6c  tines are useful
1c800 20 64 75 72 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d   during command-
1c810 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f 20 64 65  line input to de
1c820 74 65 72 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a  termine if the.*
1c830 2a 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65  * currently ente
1c840 72 65 64 20 74 65 78 74 20 73 65 65 6d 73 20 74  red text seems t
1c850 6f 20 66 6f 72 6d 20 61 20 63 6f 6d 70 6c 65 74  o form a complet
1c860 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
1c870 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69 74 69 6f  or.** if additio
1c880 6e 61 6c 20 69 6e 70 75 74 20 69 73 20 6e 65 65  nal input is nee
1c890 64 65 64 20 62 65 66 6f 72 65 20 73 65 6e 64 69  ded before sendi
1c8a0 6e 67 20 74 68 65 20 74 65 78 74 20 69 6e 74 6f  ng the text into
1c8b0 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72 20 70  .** SQLite for p
1c8c0 61 72 73 69 6e 67 2e 20 20 5e 54 68 65 73 65 20  arsing.  ^These 
1c8d0 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
1c8e0 31 20 69 66 20 74 68 65 20 69 6e 70 75 74 20 73  1 if the input s
1c8f0 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72 73  tring.** appears
1c900 20 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65 74   to be a complet
1c910 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e  e SQL statement.
1c920 20 20 5e 41 20 73 74 61 74 65 6d 65 6e 74 20 69    ^A statement i
1c930 73 20 6a 75 64 67 65 64 20 74 6f 20 62 65 0a 2a  s judged to be.*
1c940 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66 20 69 74  * complete if it
1c950 20 65 6e 64 73 20 77 69 74 68 20 61 20 73 65 6d   ends with a sem
1c960 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64  icolon token and
1c970 20 69 73 20 6e 6f 74 20 61 20 70 72 65 66 69 78   is not a prefix
1c980 20 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f   of a.** well-fo
1c990 72 6d 65 64 20 43 52 45 41 54 45 20 54 52 49 47  rmed CREATE TRIG
1c9a0 47 45 52 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  GER statement.  
1c9b0 5e 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 68 61 74  ^Semicolons that
1c9c0 20 61 72 65 20 65 6d 62 65 64 64 65 64 20 77 69   are embedded wi
1c9d0 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e 67 20 6c  thin.** string l
1c9e0 69 74 65 72 61 6c 73 20 6f 72 20 71 75 6f 74 65  iterals or quote
1c9f0 64 20 69 64 65 6e 74 69 66 69 65 72 20 6e 61 6d  d identifier nam
1ca00 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 20 61  es or comments a
1ca10 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70 65  re not.** indepe
1ca20 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20 28 74 68  ndent tokens (th
1ca30 65 79 20 61 72 65 20 70 61 72 74 20 6f 66 20 74  ey are part of t
1ca40 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77 68 69 63  he token in whic
1ca50 68 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 65 6d  h they are.** em
1ca60 62 65 64 64 65 64 29 20 61 6e 64 20 74 68 75 73  bedded) and thus
1ca70 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73   do not count as
1ca80 20 61 20 73 74 61 74 65 6d 65 6e 74 20 74 65 72   a statement ter
1ca90 6d 69 6e 61 74 6f 72 2e 20 20 5e 57 68 69 74 65  minator.  ^White
1caa0 73 70 61 63 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d  space.** and com
1cab0 6d 65 6e 74 73 20 74 68 61 74 20 66 6f 6c 6c 6f  ments that follo
1cac0 77 20 74 68 65 20 66 69 6e 61 6c 20 73 65 6d 69  w the final semi
1cad0 63 6f 6c 6f 6e 20 61 72 65 20 69 67 6e 6f 72 65  colon are ignore
1cae0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  d..**.** ^These 
1caf0 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
1cb00 30 20 69 66 20 74 68 65 20 73 74 61 74 65 6d 65  0 if the stateme
1cb10 6e 74 20 69 73 20 69 6e 63 6f 6d 70 6c 65 74 65  nt is incomplete
1cb20 2e 20 20 5e 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f  .  ^If a.** memo
1cb30 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61  ry allocation fa
1cb40 69 6c 73 2c 20 74 68 65 6e 20 53 51 4c 49 54 45  ils, then SQLITE
1cb50 5f 4e 4f 4d 45 4d 20 69 73 20 72 65 74 75 72 6e  _NOMEM is return
1cb60 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  ed..**.** ^These
1cb70 20 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f 74   routines do not
1cb80 20 70 61 72 73 65 20 74 68 65 20 53 51 4c 20 73   parse the SQL s
1cb90 74 61 74 65 6d 65 6e 74 73 20 74 68 75 73 0a 2a  tatements thus.*
1cba0 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65 63  * will not detec
1cbb0 74 20 73 79 6e 74 61 63 74 69 63 61 6c 6c 79 20  t syntactically 
1cbc0 69 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a 2a  incorrect SQL..*
1cbd0 2a 0a 2a 2a 20 5e 28 49 66 20 53 51 4c 69 74 65  *.** ^(If SQLite
1cbe0 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 69 6e   has not been in
1cbf0 69 74 69 61 6c 69 7a 65 64 20 75 73 69 6e 67 20  itialized using 
1cc00 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c  [sqlite3_initial
1cc10 69 7a 65 28 29 5d 20 70 72 69 6f 72 20 0a 2a 2a  ize()] prior .**
1cc20 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 20 73 71 6c   to invoking sql
1cc30 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
1cc40 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 69  ) then sqlite3_i
1cc50 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69  nitialize() is i
1cc60 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d 61  nvoked.** automa
1cc70 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74  tically by sqlit
1cc80 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 2e  e3_complete16().
1cc90 20 20 49 66 20 74 68 61 74 20 69 6e 69 74 69 61    If that initia
1cca0 6c 69 7a 61 74 69 6f 6e 20 66 61 69 6c 73 2c 0a  lization fails,.
1ccb0 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 65 74 75  ** then the retu
1ccc0 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71  rn value from sq
1ccd0 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36  lite3_complete16
1cce0 28 29 20 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a  () will be non-z
1ccf0 65 72 6f 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73  ero.** regardles
1cd00 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20  s of whether or 
1cd10 6e 6f 74 20 74 68 65 20 69 6e 70 75 74 20 53 51  not the input SQ
1cd20 4c 20 69 73 20 63 6f 6d 70 6c 65 74 65 2e 29 5e  L is complete.)^
1cd30 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74  .**.** The input
1cd40 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d   to [sqlite3_com
1cd50 70 6c 65 74 65 28 29 5d 20 6d 75 73 74 20 62 65  plete()] must be
1cd60 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
1cd70 65 64 0a 2a 2a 20 55 54 46 2d 38 20 73 74 72 69  ed.** UTF-8 stri
1cd80 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e  ng..**.** The in
1cd90 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  put to [sqlite3_
1cda0 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20 6d 75  complete16()] mu
1cdb0 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72  st be a zero-ter
1cdc0 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31  minated.** UTF-1
1cdd0 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69  6 string in nati
1cde0 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a  ve byte order..*
1cdf0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
1ce00 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74   sqlite3_complet
1ce10 65 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  e(const char *sq
1ce20 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  l);.SQLITE_API i
1ce30 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  nt sqlite3_compl
1ce40 65 74 65 31 36 28 63 6f 6e 73 74 20 76 6f 69 64  ete16(const void
1ce50 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43   *sql);../*.** C
1ce60 41 50 49 33 52 45 46 3a 20 52 65 67 69 73 74 65  API3REF: Registe
1ce70 72 20 41 20 43 61 6c 6c 62 61 63 6b 20 54 6f 20  r A Callback To 
1ce80 48 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f 42 55  Handle SQLITE_BU
1ce90 53 59 20 45 72 72 6f 72 73 0a 2a 2a 0a 2a 2a 20  SY Errors.**.** 
1cea0 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65  ^This routine se
1ceb0 74 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75  ts a callback fu
1cec0 6e 63 74 69 6f 6e 20 74 68 61 74 20 6d 69 67 68  nction that migh
1ced0 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65  t be invoked whe
1cee0 6e 65 76 65 72 0a 2a 2a 20 61 6e 20 61 74 74 65  never.** an atte
1cef0 6d 70 74 20 69 73 20 6d 61 64 65 20 74 6f 20 6f  mpt is made to o
1cf00 70 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 74  pen a database t
1cf10 61 62 6c 65 20 74 68 61 74 20 61 6e 6f 74 68 65  able that anothe
1cf20 72 20 74 68 72 65 61 64 0a 2a 2a 20 6f 72 20 70  r thread.** or p
1cf30 72 6f 63 65 73 73 20 68 61 73 20 6c 6f 63 6b 65  rocess has locke
1cf40 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  d..**.** ^If the
1cf50 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69   busy callback i
1cf60 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 51  s NULL, then [SQ
1cf70 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53  LITE_BUSY] or [S
1cf80 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43  QLITE_IOERR_BLOC
1cf90 4b 45 44 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72  KED].** is retur
1cfa0 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 20  ned immediately 
1cfb0 75 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 72 69 6e  upon encounterin
1cfc0 67 20 74 68 65 20 6c 6f 63 6b 2e 20 20 5e 49 66  g the lock.  ^If
1cfd0 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61   the busy callba
1cfe0 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c  ck.** is not NUL
1cff0 4c 2c 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c  L, then the call
1d000 62 61 63 6b 20 6d 69 67 68 74 20 62 65 20 69 6e  back might be in
1d010 76 6f 6b 65 64 20 77 69 74 68 20 74 77 6f 20 61  voked with two a
1d020 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  rguments..**.** 
1d030 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d  ^The first argum
1d040 65 6e 74 20 74 6f 20 74 68 65 20 62 75 73 79 20  ent to the busy 
1d050 68 61 6e 64 6c 65 72 20 69 73 20 61 20 63 6f 70  handler is a cop
1d060 79 20 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 70  y of the void* p
1d070 6f 69 6e 74 65 72 20 77 68 69 63 68 0a 2a 2a 20  ointer which.** 
1d080 69 73 20 74 68 65 20 74 68 69 72 64 20 61 72 67  is the third arg
1d090 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
1d0a0 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 2e  _busy_handler().
1d0b0 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72    ^The second ar
1d0c0 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 65  gument to.** the
1d0d0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63 61   busy handler ca
1d0e0 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e 75  llback is the nu
1d0f0 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20 74 68  mber of times th
1d100 61 74 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  at the busy hand
1d110 6c 65 72 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20  ler has.** been 
1d120 69 6e 76 6f 6b 65 64 20 66 6f 72 20 74 68 69 73  invoked for this
1d130 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e 20   locking event. 
1d140 20 5e 49 66 20 74 68 65 0a 2a 2a 20 62 75 73 79   ^If the.** busy
1d150 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
1d160 73 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61 64 64  s 0, then no add
1d170 69 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70 74 73  itional attempts
1d180 20 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a 2a 20   are made to.** 
1d190 61 63 63 65 73 73 20 74 68 65 20 64 61 74 61 62  access the datab
1d1a0 61 73 65 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f  ase and [SQLITE_
1d1b0 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45  BUSY] or [SQLITE
1d1c0 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20  _IOERR_BLOCKED] 
1d1d0 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20  is returned..** 
1d1e0 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  ^If the callback
1d1f0 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72   returns non-zer
1d200 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68 65 72 20  o, then another 
1d210 61 74 74 65 6d 70 74 0a 2a 2a 20 69 73 20 6d 61  attempt.** is ma
1d220 64 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64  de to open the d
1d230 61 74 61 62 61 73 65 20 66 6f 72 20 72 65 61 64  atabase for read
1d240 69 6e 67 20 61 6e 64 20 74 68 65 20 63 79 63 6c  ing and the cycl
1d250 65 20 72 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a  e repeats..**.**
1d260 20 54 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66   The presence of
1d270 20 61 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20   a busy handler 
1d280 64 6f 65 73 20 6e 6f 74 20 67 75 61 72 61 6e 74  does not guarant
1d290 65 65 20 74 68 61 74 20 69 74 20 77 69 6c 6c 20  ee that it will 
1d2a0 62 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68  be invoked.** wh
1d2b0 65 6e 20 74 68 65 72 65 20 69 73 20 6c 6f 63 6b  en there is lock
1d2c0 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20 5e 49 66   contention. ^If
1d2d0 20 53 51 4c 69 74 65 20 64 65 74 65 72 6d 69 6e   SQLite determin
1d2e0 65 73 20 74 68 61 74 20 69 6e 76 6f 6b 69 6e 67  es that invoking
1d2f0 20 74 68 65 20 62 75 73 79 0a 2a 2a 20 68 61 6e   the busy.** han
1d300 64 6c 65 72 20 63 6f 75 6c 64 20 72 65 73 75 6c  dler could resul
1d310 74 20 69 6e 20 61 20 64 65 61 64 6c 6f 63 6b 2c  t in a deadlock,
1d320 20 69 74 20 77 69 6c 6c 20 67 6f 20 61 68 65 61   it will go ahea
1d330 64 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51  d and return [SQ
1d340 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 6f 72  LITE_BUSY].** or
1d350 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42   [SQLITE_IOERR_B
1d360 4c 4f 43 4b 45 44 5d 20 69 6e 73 74 65 61 64 20  LOCKED] instead 
1d370 6f 66 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20  of invoking the 
1d380 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a  busy handler..**
1d390 20 43 6f 6e 73 69 64 65 72 20 61 20 73 63 65 6e   Consider a scen
1d3a0 61 72 69 6f 20 77 68 65 72 65 20 6f 6e 65 20 70  ario where one p
1d3b0 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e  rocess is holdin
1d3c0 67 20 61 20 72 65 61 64 20 6c 6f 63 6b 20 74 68  g a read lock th
1d3d0 61 74 0a 2a 2a 20 69 74 20 69 73 20 74 72 79 69  at.** it is tryi
1d3e0 6e 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f  ng to promote to
1d3f0 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b   a reserved lock
1d400 20 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f 6e 64   and.** a second
1d410 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64   process is hold
1d420 69 6e 67 20 61 20 72 65 73 65 72 76 65 64 20 6c  ing a reserved l
1d430 6f 63 6b 20 74 68 61 74 20 69 74 20 69 73 20 74  ock that it is t
1d440 72 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d  rying.** to prom
1d450 6f 74 65 20 74 6f 20 61 6e 20 65 78 63 6c 75 73  ote to an exclus
1d460 69 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65 20 66  ive lock.  The f
1d470 69 72 73 74 20 70 72 6f 63 65 73 73 20 63 61 6e  irst process can
1d480 6e 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a 20 62  not proceed.** b
1d490 65 63 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f  ecause it is blo
1d4a0 63 6b 65 64 20 62 79 20 74 68 65 20 73 65 63 6f  cked by the seco
1d4b0 6e 64 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e  nd and the secon
1d4c0 64 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74  d process cannot
1d4d0 0a 2a 2a 20 70 72 6f 63 65 65 64 20 62 65 63 61  .** proceed beca
1d4e0 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65  use it is blocke
1d4f0 64 20 62 79 20 74 68 65 20 66 69 72 73 74 2e 20  d by the first. 
1d500 20 49 66 20 62 6f 74 68 20 70 72 6f 63 65 73 73   If both process
1d510 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65  es.** invoke the
1d520 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2c 20   busy handlers, 
1d530 6e 65 69 74 68 65 72 20 77 69 6c 6c 20 6d 61 6b  neither will mak
1d540 65 20 61 6e 79 20 70 72 6f 67 72 65 73 73 2e 20  e any progress. 
1d550 20 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 53   Therefore,.** S
1d560 51 4c 69 74 65 20 72 65 74 75 72 6e 73 20 5b 53  QLite returns [S
1d570 51 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f 72 20  QLITE_BUSY] for 
1d580 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73  the first proces
1d590 73 2c 20 68 6f 70 69 6e 67 20 74 68 61 74 20 74  s, hoping that t
1d5a0 68 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 75  his.** will indu
1d5b0 63 65 20 74 68 65 20 66 69 72 73 74 20 70 72 6f  ce the first pro
1d5c0 63 65 73 73 20 74 6f 20 72 65 6c 65 61 73 65 20  cess to release 
1d5d0 69 74 73 20 72 65 61 64 20 6c 6f 63 6b 20 61 6e  its read lock an
1d5e0 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 73  d allow.** the s
1d5f0 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 74 6f  econd process to
1d600 20 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20   proceed..**.** 
1d610 5e 54 68 65 20 64 65 66 61 75 6c 74 20 62 75 73  ^The default bus
1d620 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55  y callback is NU
1d630 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b  LL..**.** ^The [
1d640 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 65 72 72  SQLITE_BUSY] err
1d650 6f 72 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20  or is converted 
1d660 74 6f 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  to [SQLITE_IOERR
1d670 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 77 68 65  _BLOCKED].** whe
1d680 6e 20 53 51 4c 69 74 65 20 69 73 20 69 6e 20 74  n SQLite is in t
1d690 68 65 20 6d 69 64 64 6c 65 20 6f 66 20 61 20 6c  he middle of a l
1d6a0 61 72 67 65 20 74 72 61 6e 73 61 63 74 69 6f 6e  arge transaction
1d6b0 20 77 68 65 72 65 20 61 6c 6c 20 74 68 65 0a 2a   where all the.*
1d6c0 2a 20 63 68 61 6e 67 65 73 20 77 69 6c 6c 20 6e  * changes will n
1d6d0 6f 74 20 66 69 74 20 69 6e 74 6f 20 74 68 65 20  ot fit into the 
1d6e0 69 6e 2d 6d 65 6d 6f 72 79 20 63 61 63 68 65 2e  in-memory cache.
1d6f0 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a    SQLite will.**
1d700 20 61 6c 72 65 61 64 79 20 68 6f 6c 64 20 61 20   already hold a 
1d710 52 45 53 45 52 56 45 44 20 6c 6f 63 6b 20 6f 6e  RESERVED lock on
1d720 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
1d730 6c 65 2c 20 62 75 74 20 69 74 20 6e 65 65 64 73  le, but it needs
1d740 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74  .** to promote t
1d750 68 69 73 20 6c 6f 63 6b 20 74 6f 20 45 58 43 4c  his lock to EXCL
1d760 55 53 49 56 45 20 73 6f 20 74 68 61 74 20 69 74  USIVE so that it
1d770 20 63 61 6e 20 73 70 69 6c 6c 20 63 61 63 68 65   can spill cache
1d780 0a 2a 2a 20 70 61 67 65 73 20 69 6e 74 6f 20 74  .** pages into t
1d790 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
1d7a0 20 77 69 74 68 6f 75 74 20 68 61 72 6d 20 74 6f   without harm to
1d7b0 20 63 6f 6e 63 75 72 72 65 6e 74 0a 2a 2a 20 72   concurrent.** r
1d7c0 65 61 64 65 72 73 2e 20 20 5e 49 66 20 69 74 20  eaders.  ^If it 
1d7d0 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 70 72 6f  is unable to pro
1d7e0 6d 6f 74 65 20 74 68 65 20 6c 6f 63 6b 2c 20 74  mote the lock, t
1d7f0 68 65 6e 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72  hen the in-memor
1d800 79 0a 2a 2a 20 63 61 63 68 65 20 77 69 6c 6c 20  y.** cache will 
1d810 62 65 20 6c 65 66 74 20 69 6e 20 61 6e 20 69 6e  be left in an in
1d820 63 6f 6e 73 69 73 74 65 6e 74 20 73 74 61 74 65  consistent state
1d830 20 61 6e 64 20 73 6f 20 74 68 65 20 65 72 72 6f   and so the erro
1d840 72 0a 2a 2a 20 63 6f 64 65 20 69 73 20 70 72 6f  r.** code is pro
1d850 6d 6f 74 65 64 20 66 72 6f 6d 20 74 68 65 20 72  moted from the r
1d860 65 6c 61 74 69 76 65 6c 79 20 62 65 6e 69 67 6e  elatively benign
1d870 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 74   [SQLITE_BUSY] t
1d880 6f 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 65  o.** the more se
1d890 76 65 72 65 20 5b 53 51 4c 49 54 45 5f 49 4f 45  vere [SQLITE_IOE
1d8a0 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 20 20 5e 54  RR_BLOCKED].  ^T
1d8b0 68 69 73 20 65 72 72 6f 72 20 63 6f 64 65 20 70  his error code p
1d8c0 72 6f 6d 6f 74 69 6f 6e 0a 2a 2a 20 66 6f 72 63  romotion.** forc
1d8d0 65 73 20 61 6e 20 61 75 74 6f 6d 61 74 69 63 20  es an automatic 
1d8e0 72 6f 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20  rollback of the 
1d8f0 63 68 61 6e 67 65 73 2e 20 20 53 65 65 20 74 68  changes.  See th
1d900 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22 2f 63  e.** <a href="/c
1d910 76 73 74 72 61 63 2f 77 69 6b 69 3f 70 3d 43 6f  vstrac/wiki?p=Co
1d920 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e  rruptionFollowin
1d930 67 42 75 73 79 45 72 72 6f 72 22 3e 0a 2a 2a 20  gBusyError">.** 
1d940 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77  CorruptionFollow
1d950 69 6e 67 42 75 73 79 45 72 72 6f 72 3c 2f 61 3e  ingBusyError</a>
1d960 20 77 69 6b 69 20 70 61 67 65 20 66 6f 72 20 61   wiki page for a
1d970 20 64 69 73 63 75 73 73 69 6f 6e 20 6f 66 20 77   discussion of w
1d980 68 79 0a 2a 2a 20 74 68 69 73 20 69 73 20 69 6d  hy.** this is im
1d990 70 6f 72 74 61 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e  portant..**.** ^
1d9a0 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20  (There can only 
1d9b0 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79  be a single busy
1d9c0 20 68 61 6e 64 6c 65 72 20 64 65 66 69 6e 65 64   handler defined
1d9d0 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 5b 64 61   for each.** [da
1d9e0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1d9f0 6e 5d 2e 20 20 53 65 74 74 69 6e 67 20 61 20 6e  n].  Setting a n
1da00 65 77 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  ew busy handler 
1da10 63 6c 65 61 72 73 20 61 6e 79 0a 2a 2a 20 70 72  clears any.** pr
1da20 65 76 69 6f 75 73 6c 79 20 73 65 74 20 68 61 6e  eviously set han
1da30 64 6c 65 72 2e 29 5e 20 20 5e 4e 6f 74 65 20 74  dler.)^  ^Note t
1da40 68 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c  hat calling [sql
1da50 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75  ite3_busy_timeou
1da60 74 28 29 5d 0a 2a 2a 20 77 69 6c 6c 20 61 6c 73  t()].** will als
1da70 6f 20 73 65 74 20 6f 72 20 63 6c 65 61 72 20 74  o set or clear t
1da80 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e  he busy handler.
1da90 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62 75 73 79 20  .**.** The busy 
1daa0 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 20  callback should 
1dab0 6e 6f 74 20 74 61 6b 65 20 61 6e 79 20 61 63 74  not take any act
1dac0 69 6f 6e 73 20 77 68 69 63 68 20 6d 6f 64 69 66  ions which modif
1dad0 79 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  y the.** databas
1dae0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61  e connection tha
1daf0 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75  t invoked the bu
1db00 73 79 20 68 61 6e 64 6c 65 72 2e 20 20 41 6e 79  sy handler.  Any
1db10 20 73 75 63 68 20 61 63 74 69 6f 6e 73 0a 2a 2a   such actions.**
1db20 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66   result in undef
1db30 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a  ined behavior..*
1db40 2a 20 0a 2a 2a 20 41 20 62 75 73 79 20 68 61 6e  * .** A busy han
1db50 64 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20 63 6c  dler must not cl
1db60 6f 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65  ose the database
1db70 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f   connection.** o
1db80 72 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  r [prepared stat
1db90 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 6e 76 6f  ement] that invo
1dba0 6b 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e  ked the busy han
1dbb0 64 6c 65 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  dler..*/.SQLITE_
1dbc0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
1dbd0 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c  busy_handler(sql
1dbe0 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f  ite3*, int(*)(vo
1dbf0 69 64 2a 2c 69 6e 74 29 2c 20 76 6f 69 64 2a 29  id*,int), void*)
1dc00 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1dc10 46 3a 20 53 65 74 20 41 20 42 75 73 79 20 54 69  F: Set A Busy Ti
1dc20 6d 65 6f 75 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  meout.**.** ^Thi
1dc30 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61  s routine sets a
1dc40 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68   [sqlite3_busy_h
1dc50 61 6e 64 6c 65 72 20 7c 20 62 75 73 79 20 68 61  andler | busy ha
1dc60 6e 64 6c 65 72 5d 20 74 68 61 74 20 73 6c 65 65  ndler] that slee
1dc70 70 73 0a 2a 2a 20 66 6f 72 20 61 20 73 70 65 63  ps.** for a spec
1dc80 69 66 69 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20  ified amount of 
1dc90 74 69 6d 65 20 77 68 65 6e 20 61 20 74 61 62 6c  time when a tabl
1dca0 65 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20 5e 54  e is locked.  ^T
1dcb0 68 65 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 69  he handler.** wi
1dcc0 6c 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69 70 6c  ll sleep multipl
1dcd0 65 20 74 69 6d 65 73 20 75 6e 74 69 6c 20 61 74  e times until at
1dce0 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c   least "ms" mill
1dcf0 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65  iseconds of slee
1dd00 70 69 6e 67 0a 2a 2a 20 68 61 76 65 20 61 63 63  ping.** have acc
1dd10 75 6d 75 6c 61 74 65 64 2e 20 20 5e 41 66 74 65  umulated.  ^Afte
1dd20 72 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20  r at least "ms" 
1dd30 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20  milliseconds of 
1dd40 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74 68 65  sleeping,.** the
1dd50 20 68 61 6e 64 6c 65 72 20 72 65 74 75 72 6e 73   handler returns
1dd60 20 30 20 77 68 69 63 68 20 63 61 75 73 65 73 20   0 which causes 
1dd70 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1dd80 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53   to return.** [S
1dd90 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b  QLITE_BUSY] or [
1dda0 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
1ddb0 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61  CKED]..**.** ^Ca
1ddc0 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69  lling this routi
1ddd0 6e 65 20 77 69 74 68 20 61 6e 20 61 72 67 75 6d  ne with an argum
1dde0 65 6e 74 20 6c 65 73 73 20 74 68 61 6e 20 6f 72  ent less than or
1ddf0 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a   equal to zero.*
1de00 2a 20 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c 20  * turns off all 
1de10 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a 2a  busy handlers..*
1de20 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e  *.** ^(There can
1de30 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c   only be a singl
1de40 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66  e busy handler f
1de50 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a  or a particular.
1de60 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
1de70 6e 65 63 74 69 6f 6e 5d 20 61 6e 79 20 61 6e 79  nection] any any
1de80 20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20   given moment.  
1de90 49 66 20 61 6e 6f 74 68 65 72 20 62 75 73 79 20  If another busy 
1dea0 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73 20 64  handler.** was d
1deb0 65 66 69 6e 65 64 20 20 28 75 73 69 6e 67 20 5b  efined  (using [
1dec0 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e  sqlite3_busy_han
1ded0 64 6c 65 72 28 29 5d 29 20 70 72 69 6f 72 20 74  dler()]) prior t
1dee0 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69  o calling.** thi
1def0 73 20 72 6f 75 74 69 6e 65 2c 20 74 68 61 74 20  s routine, that 
1df00 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c  other busy handl
1df10 65 72 20 69 73 20 63 6c 65 61 72 65 64 2e 29 5e  er is cleared.)^
1df20 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
1df30 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  nt sqlite3_busy_
1df40 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 33 2a  timeout(sqlite3*
1df50 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a  , int ms);../*.*
1df60 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 76  * CAPI3REF: Conv
1df70 65 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e 65 73  enience Routines
1df80 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75 65   For Running Que
1df90 72 69 65 73 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ries.**.** This 
1dfa0 69 73 20 61 20 6c 65 67 61 63 79 20 69 6e 74 65  is a legacy inte
1dfb0 72 66 61 63 65 20 74 68 61 74 20 69 73 20 70 72  rface that is pr
1dfc0 65 73 65 72 76 65 64 20 66 6f 72 20 62 61 63 6b  eserved for back
1dfd0 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c  wards compatibil
1dfe0 69 74 79 2e 0a 2a 2a 20 55 73 65 20 6f 66 20 74  ity..** Use of t
1dff0 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73  his interface is
1e000 20 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e 64 65 64   not recommended
1e010 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74 69  ..**.** Definiti
1e020 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74 20  on: A <b>result 
1e030 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65 6d  table</b> is mem
1e040 6f 72 79 20 64 61 74 61 20 73 74 72 75 63 74 75  ory data structu
1e050 72 65 20 63 72 65 61 74 65 64 20 62 79 20 74 68  re created by th
1e060 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65  e.** [sqlite3_ge
1e070 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74 65 72  t_table()] inter
1e080 66 61 63 65 2e 20 20 41 20 72 65 73 75 6c 74 20  face.  A result 
1e090 74 61 62 6c 65 20 72 65 63 6f 72 64 73 20 74 68  table records th
1e0a0 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71 75  e.** complete qu
1e0b0 65 72 79 20 72 65 73 75 6c 74 73 20 66 72 6f 6d  ery results from
1e0c0 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75 65   one or more que
1e0d0 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ries..**.** The 
1e0e0 74 61 62 6c 65 20 63 6f 6e 63 65 70 74 75 61 6c  table conceptual
1e0f0 6c 79 20 68 61 73 20 61 20 6e 75 6d 62 65 72 20  ly has a number 
1e100 6f 66 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c 75  of rows and colu
1e110 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68 65  mns.  But.** the
1e120 73 65 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6e  se numbers are n
1e130 6f 74 20 70 61 72 74 20 6f 66 20 74 68 65 20 72  ot part of the r
1e140 65 73 75 6c 74 20 74 61 62 6c 65 20 69 74 73 65  esult table itse
1e150 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e 75  lf.  These.** nu
1e160 6d 62 65 72 73 20 61 72 65 20 6f 62 74 61 69 6e  mbers are obtain
1e170 65 64 20 73 65 70 61 72 61 74 65 6c 79 2e 20 20  ed separately.  
1e180 4c 65 74 20 4e 20 62 65 20 74 68 65 20 6e 75 6d  Let N be the num
1e190 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20 61  ber of rows.** a
1e1a0 6e 64 20 4d 20 62 65 20 74 68 65 20 6e 75 6d 62  nd M be the numb
1e1b0 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a  er of columns..*
1e1c0 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61  *.** A result ta
1e1d0 62 6c 65 20 69 73 20 61 6e 20 61 72 72 61 79 20  ble is an array 
1e1e0 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a  of pointers to z
1e1f0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55  ero-terminated U
1e200 54 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a  TF-8 strings..**
1e210 20 54 68 65 72 65 20 61 72 65 20 28 4e 2b 31 29   There are (N+1)
1e220 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20 74  *M elements in t
1e230 68 65 20 61 72 72 61 79 2e 20 20 54 68 65 20 66  he array.  The f
1e240 69 72 73 74 20 4d 20 70 6f 69 6e 74 65 72 73 20  irst M pointers 
1e250 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f  point.** to zero
1e260 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69  -terminated stri
1e270 6e 67 73 20 74 68 61 74 20 20 63 6f 6e 74 61 69  ngs that  contai
1e280 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 74  n the names of t
1e290 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54  he columns..** T
1e2a0 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e 74  he remaining ent
1e2b0 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20 74  ries all point t
1e2c0 6f 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 2e  o query results.
1e2d0 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20 72 65    NULL values re
1e2e0 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20  sult.** in NULL 
1e2f0 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c 20 6f  pointers.  All o
1e300 74 68 65 72 20 76 61 6c 75 65 73 20 61 72 65 20  ther values are 
1e310 69 6e 20 74 68 65 69 72 20 55 54 46 2d 38 20 7a  in their UTF-8 z
1e320 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  ero-terminated.*
1e330 2a 20 73 74 72 69 6e 67 20 72 65 70 72 65 73 65  * string represe
1e340 6e 74 61 74 69 6f 6e 20 61 73 20 72 65 74 75 72  ntation as retur
1e350 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
1e360 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a  column_text()]..
1e370 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74  **.** A result t
1e380 61 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73 69  able might consi
1e390 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72  st of one or mor
1e3a0 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
1e3b0 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20 6e  ions..** It is n
1e3c0 6f 74 20 73 61 66 65 20 74 6f 20 70 61 73 73 20  ot safe to pass 
1e3d0 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 64  a result table d
1e3e0 69 72 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c 69  irectly to [sqli
1e3f0 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 20  te3_free()]..** 
1e400 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 73  A result table s
1e410 68 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f 63  hould be dealloc
1e420 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  ated using [sqli
1e430 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29  te3_free_table()
1e440 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73 20 61 6e  ]..**.** ^(As an
1e450 20 65 78 61 6d 70 6c 65 20 6f 66 20 74 68 65 20   example of the 
1e460 72 65 73 75 6c 74 20 74 61 62 6c 65 20 66 6f 72  result table for
1e470 6d 61 74 2c 20 73 75 70 70 6f 73 65 20 61 20 71  mat, suppose a q
1e480 75 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20 69  uery result.** i
1e490 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a  s as follows:.**
1e4a0 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
1e4b0 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20  <pre>.**        
1e4c0 4e 61 6d 65 20 20 20 20 20 20 20 20 7c 20 41 67  Name        | Ag
1e4d0 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d  e.**        ----
1e4e0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
1e4f0 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c  ---.**        Al
1e500 69 63 65 20 20 20 20 20 20 20 7c 20 34 33 0a 2a  ice       | 43.*
1e510 2a 20 20 20 20 20 20 20 20 42 6f 62 20 20 20 20  *        Bob    
1e520 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20       | 28.**    
1e530 20 20 20 20 43 69 6e 64 79 20 20 20 20 20 20 20      Cindy       
1e540 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  | 21.** </pre></
1e550 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
1e560 2a 20 54 68 65 72 65 20 61 72 65 20 74 77 6f 20  * There are two 
1e570 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e  column (M==2) an
1e580 64 20 74 68 72 65 65 20 72 6f 77 73 20 28 4e 3d  d three rows (N=
1e590 3d 33 29 2e 20 20 54 68 75 73 20 74 68 65 0a 2a  =3).  Thus the.*
1e5a0 2a 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 68  * result table h
1e5b0 61 73 20 38 20 65 6e 74 72 69 65 73 2e 20 20 53  as 8 entries.  S
1e5c0 75 70 70 6f 73 65 20 74 68 65 20 72 65 73 75 6c  uppose the resul
1e5d0 74 20 74 61 62 6c 65 20 69 73 20 73 74 6f 72 65  t table is store
1e5e0 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61 79  d.** in an array
1e5f0 20 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c 74 2e   names azResult.
1e600 20 20 54 68 65 6e 20 61 7a 52 65 73 75 6c 74 20    Then azResult 
1e610 68 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e 74 65  holds this conte
1e620 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  nt:.**.** <block
1e630 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
1e640 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
1e650 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a  91;0] = "Name";.
1e660 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
1e670 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22 41 67 65  lt&#91;1] = "Age
1e680 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
1e690 65 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20 22  esult&#91;2] = "
1e6a0 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20 20  Alice";.**      
1e6b0 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 33    azResult&#91;3
1e6c0 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20 20  ] = "43";.**    
1e6d0 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
1e6e0 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20  ;4] = "Bob";.** 
1e6f0 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
1e700 23 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a  #91;5] = "28";.*
1e710 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
1e720 74 26 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e 64  t&#91;6] = "Cind
1e730 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  y";.**        az
1e740 52 65 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d 20  Result&#91;7] = 
1e750 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  "21";.** </pre><
1e760 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a  /blockquote>)^.*
1e770 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1e780 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 66 75  3_get_table() fu
1e790 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61 74 65 73  nction evaluates
1e7a0 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20   one or more.** 
1e7b0 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61  semicolon-separa
1e7c0 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ted SQL statemen
1e7d0 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74  ts in the zero-t
1e7e0 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 0a  erminated UTF-8.
1e7f0 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20 69 74 73  ** string of its
1e800 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61   2nd parameter a
1e810 6e 64 20 72 65 74 75 72 6e 73 20 61 20 72 65 73  nd returns a res
1e820 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 74 68 65  ult table to the
1e830 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69 76 65  .** pointer give
1e840 6e 20 69 6e 20 69 74 73 20 33 72 64 20 70 61 72  n in its 3rd par
1e850 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66  ameter..**.** Af
1e860 74 65 72 20 74 68 65 20 61 70 70 6c 69 63 61 74  ter the applicat
1e870 69 6f 6e 20 68 61 73 20 66 69 6e 69 73 68 65 64  ion has finished
1e880 20 77 69 74 68 20 74 68 65 20 72 65 73 75 6c 74   with the result
1e890 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 67 65   from sqlite3_ge
1e8a0 74 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a 20 69 74  t_table(),.** it
1e8b0 20 6d 75 73 74 20 70 61 73 73 20 74 68 65 20 72   must pass the r
1e8c0 65 73 75 6c 74 20 74 61 62 6c 65 20 70 6f 69 6e  esult table poin
1e8d0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 66  ter to sqlite3_f
1e8e0 72 65 65 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f  ree_table() in o
1e8f0 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c 65 61  rder to.** relea
1e900 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 68  se the memory th
1e910 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64 2e  at was malloced.
1e920 20 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65    Because of the
1e930 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c   way the.** [sql
1e940 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68  ite3_malloc()] h
1e950 61 70 70 65 6e 73 20 77 69 74 68 69 6e 20 73 71  appens within sq
1e960 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
1e970 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a 2a  ), the calling.*
1e980 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20  * function must 
1e990 6e 6f 74 20 74 72 79 20 74 6f 20 63 61 6c 6c 20  not try to call 
1e9a0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
1e9b0 20 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79   directly.  Only
1e9c0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  .** [sqlite3_fre
1e9d0 65 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 61 62  e_table()] is ab
1e9e0 6c 65 20 74 6f 20 72 65 6c 65 61 73 65 20 74 68  le to release th
1e9f0 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c  e memory properl
1ea00 79 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a  y and safely..**
1ea10 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
1ea20 67 65 74 5f 74 61 62 6c 65 28 29 20 69 6e 74 65  get_table() inte
1ea30 72 66 61 63 65 20 69 73 20 69 6d 70 6c 65 6d 65  rface is impleme
1ea40 6e 74 65 64 20 61 73 20 61 20 77 72 61 70 70 65  nted as a wrappe
1ea50 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c  r around.** [sql
1ea60 69 74 65 33 5f 65 78 65 63 28 29 5d 2e 20 20 54  ite3_exec()].  T
1ea70 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  he sqlite3_get_t
1ea80 61 62 6c 65 28 29 20 72 6f 75 74 69 6e 65 20 64  able() routine d
1ea90 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 61 63 63  oes not have acc
1eaa0 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69 6e  ess.** to any in
1eab0 74 65 72 6e 61 6c 20 64 61 74 61 20 73 74 72 75  ternal data stru
1eac0 63 74 75 72 65 73 20 6f 66 20 53 51 4c 69 74 65  ctures of SQLite
1ead0 2e 20 20 49 74 20 75 73 65 73 20 6f 6e 6c 79 20  .  It uses only 
1eae0 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69 6e  the public.** in
1eaf0 74 65 72 66 61 63 65 20 64 65 66 69 6e 65 64 20  terface defined 
1eb00 68 65 72 65 2e 20 20 41 73 20 61 20 63 6f 6e 73  here.  As a cons
1eb10 65 71 75 65 6e 63 65 2c 20 65 72 72 6f 72 73 20  equence, errors 
1eb20 74 68 61 74 20 6f 63 63 75 72 20 69 6e 20 74 68  that occur in th
1eb30 65 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c 61 79  e.** wrapper lay
1eb40 65 72 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68  er outside of th
1eb50 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c 69  e internal [sqli
1eb60 74 65 33 5f 65 78 65 63 28 29 5d 20 63 61 6c 6c  te3_exec()] call
1eb70 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c   are not.** refl
1eb80 65 63 74 65 64 20 69 6e 20 73 75 62 73 65 71 75  ected in subsequ
1eb90 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  ent calls to [sq
1eba0 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d  lite3_errcode()]
1ebb0 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
1ebc0 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a 53 51  errmsg()]..*/.SQ
1ebd0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
1ebe0 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a  ite3_get_table(.
1ebf0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
1ec00 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70          /* An op
1ec10 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20  en database */. 
1ec20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71   const char *zSq
1ec30 6c 2c 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f  l,     /* SQL to
1ec40 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f   be evaluated */
1ec50 0a 20 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52 65  .  char ***pazRe
1ec60 73 75 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73 75  sult,    /* Resu
1ec70 6c 74 73 20 6f 66 20 74 68 65 20 71 75 65 72 79  lts of the query
1ec80 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f 77   */.  int *pnRow
1ec90 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e  ,           /* N
1eca0 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20  umber of result 
1ecb0 72 6f 77 73 20 77 72 69 74 74 65 6e 20 68 65 72  rows written her
1ecc0 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43 6f  e */.  int *pnCo
1ecd0 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a 20  lumn,        /* 
1ece0 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74  Number of result
1ecf0 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e   columns written
1ed00 20 68 65 72 65 20 2a 2f 0a 20 20 63 68 61 72 20   here */.  char 
1ed10 2a 2a 70 7a 45 72 72 6d 73 67 20 20 20 20 20 20  **pzErrmsg      
1ed20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72   /* Error msg wr
1ed30 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b  itten here */.);
1ed40 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
1ed50 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61   sqlite3_free_ta
1ed60 62 6c 65 28 63 68 61 72 20 2a 2a 72 65 73 75 6c  ble(char **resul
1ed70 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
1ed80 52 45 46 3a 20 46 6f 72 6d 61 74 74 65 64 20 53  REF: Formatted S
1ed90 74 72 69 6e 67 20 50 72 69 6e 74 69 6e 67 20 46  tring Printing F
1eda0 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54  unctions.**.** T
1edb0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
1edc0 65 20 77 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f 66  e work-alikes of
1edd0 20 74 68 65 20 22 70 72 69 6e 74 66 28 29 22 20   the "printf()" 
1ede0 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74 69  family of functi
1edf0 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20  ons.** from the 
1ee00 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61  standard C libra
1ee10 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ry..**.** ^The s
1ee20 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29  qlite3_mprintf()
1ee30 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 6d 70   and sqlite3_vmp
1ee40 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 73  rintf() routines
1ee50 20 77 72 69 74 65 20 74 68 65 69 72 0a 2a 2a 20   write their.** 
1ee60 72 65 73 75 6c 74 73 20 69 6e 74 6f 20 6d 65 6d  results into mem
1ee70 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ory obtained fro
1ee80 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
1ee90 63 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72  c()]..** The str
1eea0 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79  ings returned by
1eeb0 20 74 68 65 73 65 20 74 77 6f 20 72 6f 75 74 69   these two routi
1eec0 6e 65 73 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a  nes should be.**
1eed0 20 72 65 6c 65 61 73 65 64 20 62 79 20 5b 73 71   released by [sq
1eee0 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 20 20  lite3_free()].  
1eef0 5e 42 6f 74 68 20 72 6f 75 74 69 6e 65 73 20 72  ^Both routines r
1ef00 65 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20  eturn a.** NULL 
1ef10 70 6f 69 6e 74 65 72 20 69 66 20 5b 73 71 6c 69  pointer if [sqli
1ef20 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 73  te3_malloc()] is
1ef30 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63   unable to alloc
1ef40 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65  ate enough.** me
1ef50 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65  mory to hold the
1ef60 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e   resulting strin
1ef70 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73  g..**.** ^(The s
1ef80 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
1ef90 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d  ) routine is sim
1efa0 69 6c 61 72 20 74 6f 20 22 73 6e 70 72 69 6e 74  ilar to "snprint
1efb0 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65  f()" from.** the
1efc0 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72   standard C libr
1efd0 61 72 79 2e 20 20 54 68 65 20 72 65 73 75 6c 74  ary.  The result
1efe0 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f   is written into
1eff0 20 74 68 65 0a 2a 2a 20 62 75 66 66 65 72 20 73   the.** buffer s
1f000 75 70 70 6c 69 65 64 20 61 73 20 74 68 65 20 73  upplied as the s
1f010 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
1f020 77 68 6f 73 65 20 73 69 7a 65 20 69 73 20 67 69  whose size is gi
1f030 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65 20 66 69  ven by.** the fi
1f040 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 20 4e  rst parameter. N
1f050 6f 74 65 20 74 68 61 74 20 74 68 65 20 6f 72 64  ote that the ord
1f060 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72  er of the.** fir
1f070 73 74 20 74 77 6f 20 70 61 72 61 6d 65 74 65 72  st two parameter
1f080 73 20 69 73 20 72 65 76 65 72 73 65 64 20 66 72  s is reversed fr
1f090 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e 29 5e  om snprintf().)^
1f0a0 20 20 54 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20    This is an.** 
1f0b0 68 69 73 74 6f 72 69 63 61 6c 20 61 63 63 69 64  historical accid
1f0c0 65 6e 74 20 74 68 61 74 20 63 61 6e 6e 6f 74 20  ent that cannot 
1f0d0 62 65 20 66 69 78 65 64 20 77 69 74 68 6f 75 74  be fixed without
1f0e0 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63   breaking.** bac
1f0f0 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
1f100 6c 69 74 79 2e 20 20 5e 28 4e 6f 74 65 20 61 6c  lity.  ^(Note al
1f110 73 6f 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f  so that sqlite3_
1f120 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65  snprintf().** re
1f130 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
1f140 74 6f 20 69 74 73 20 62 75 66 66 65 72 20 69 6e  to its buffer in
1f150 73 74 65 61 64 20 6f 66 20 74 68 65 20 6e 75 6d  stead of the num
1f160 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63  ber of.** charac
1f170 74 65 72 73 20 61 63 74 75 61 6c 6c 79 20 77 72  ters actually wr
1f180 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 62  itten into the b
1f190 75 66 66 65 72 2e 29 5e 20 20 57 65 20 61 64 6d  uffer.)^  We adm
1f1a0 69 74 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e  it that.** the n
1f1b0 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74  umber of charact
1f1c0 65 72 73 20 77 72 69 74 74 65 6e 20 77 6f 75 6c  ers written woul
1f1d0 64 20 62 65 20 61 20 6d 6f 72 65 20 75 73 65 66  d be a more usef
1f1e0 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c  ul return.** val
1f1f0 75 65 20 62 75 74 20 77 65 20 63 61 6e 6e 6f 74  ue but we cannot
1f200 20 63 68 61 6e 67 65 20 74 68 65 20 69 6d 70 6c   change the impl
1f210 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71  ementation of sq
1f220 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
1f230 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74 20  .** now without 
1f240 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69  breaking compati
1f250 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41  bility..**.** ^A
1f260 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 62 75  s long as the bu
1f270 66 66 65 72 20 73 69 7a 65 20 69 73 20 67 72 65  ffer size is gre
1f280 61 74 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20  ater than zero, 
1f290 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
1f2a0 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 73  ().** guarantees
1f2b0 20 74 68 61 74 20 74 68 65 20 62 75 66 66 65 72   that the buffer
1f2c0 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d   is always zero-
1f2d0 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68  terminated.  ^Th
1f2e0 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d  e first.** param
1f2f0 65 74 65 72 20 22 6e 22 20 69 73 20 74 68 65 20  eter "n" is the 
1f300 74 6f 74 61 6c 20 73 69 7a 65 20 6f 66 20 74 68  total size of th
1f310 65 20 62 75 66 66 65 72 2c 20 69 6e 63 6c 75 64  e buffer, includ
1f320 69 6e 67 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a  ing space for.**
1f330 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e   the zero termin
1f340 61 74 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f  ator.  So the lo
1f350 6e 67 65 73 74 20 73 74 72 69 6e 67 20 74 68 61  ngest string tha
1f360 74 20 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74  t can be complet
1f370 65 6c 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77  ely.** written w
1f380 69 6c 6c 20 62 65 20 6e 2d 31 20 63 68 61 72 61  ill be n-1 chara
1f390 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  cters..**.** ^Th
1f3a0 65 20 73 71 6c 69 74 65 33 5f 76 73 6e 70 72 69  e sqlite3_vsnpri
1f3b0 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73  ntf() routine is
1f3c0 20 61 20 76 61 72 61 72 67 73 20 76 65 72 73 69   a varargs versi
1f3d0 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e  on of sqlite3_sn
1f3e0 70 72 69 6e 74 66 28 29 2e 0a 2a 2a 0a 2a 2a 20  printf()..**.** 
1f3f0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
1f400 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d  ll implement som
1f410 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 6f 72  e additional for
1f420 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f  matting.** optio
1f430 6e 73 20 74 68 61 74 20 61 72 65 20 75 73 65 66  ns that are usef
1f440 75 6c 20 66 6f 72 20 63 6f 6e 73 74 72 75 63 74  ul for construct
1f450 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ing SQL statemen
1f460 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74 68  ts..** All of th
1f470 65 20 75 73 75 61 6c 20 70 72 69 6e 74 66 28 29  e usual printf()
1f480 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69   formatting opti
1f490 6f 6e 73 20 61 70 70 6c 79 2e 20 20 49 6e 20 61  ons apply.  In a
1f4a0 64 64 69 74 69 6f 6e 2c 20 74 68 65 72 65 0a 2a  ddition, there.*
1f4b0 2a 20 69 73 20 61 72 65 20 22 25 71 22 2c 20 22  * is are "%q", "
1f4c0 25 51 22 2c 20 61 6e 64 20 22 25 7a 22 20 6f 70  %Q", and "%z" op
1f4d0 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  tions..**.** ^(T
1f4e0 68 65 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72  he %q option wor
1f4f0 6b 73 20 6c 69 6b 65 20 25 73 20 69 6e 20 74 68  ks like %s in th
1f500 61 74 20 69 74 20 73 75 62 73 74 69 74 75 74 65  at it substitute
1f510 73 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74  s a nul-terminat
1f520 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f  ed.** string fro
1f530 6d 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 6c  m the argument l
1f540 69 73 74 2e 20 20 42 75 74 20 25 71 20 61 6c 73  ist.  But %q als
1f550 6f 20 64 6f 75 62 6c 65 73 20 65 76 65 72 79 20  o doubles every 
1f560 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 2e 0a  '\'' character..
1f570 2a 2a 20 25 71 20 69 73 20 64 65 73 69 67 6e 65  ** %q is designe
1f580 64 20 66 6f 72 20 75 73 65 20 69 6e 73 69 64 65  d for use inside
1f590 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61   a string litera
1f5a0 6c 2e 29 5e 20 20 42 79 20 64 6f 75 62 6c 69 6e  l.)^  By doublin
1f5b0 67 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63  g each '\''.** c
1f5c0 68 61 72 61 63 74 65 72 20 69 74 20 65 73 63 61  haracter it esca
1f5d0 70 65 73 20 74 68 61 74 20 63 68 61 72 61 63 74  pes that charact
1f5e0 65 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74  er and allows it
1f5f0 20 74 6f 20 62 65 20 69 6e 73 65 72 74 65 64 20   to be inserted 
1f600 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69  into.** the stri
1f610 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78  ng..**.** For ex
1f620 61 6d 70 6c 65 2c 20 61 73 73 75 6d 65 20 74 68  ample, assume th
1f630 65 20 73 74 72 69 6e 67 20 76 61 72 69 61 62 6c  e string variabl
1f640 65 20 7a 54 65 78 74 20 63 6f 6e 74 61 69 6e 73  e zText contains
1f650 20 74 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73   text as follows
1f660 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
1f670 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68  ote><pre>.**  ch
1f680 61 72 20 2a 7a 54 65 78 74 20 3d 20 22 49 74 27  ar *zText = "It'
1f690 73 20 61 20 68 61 70 70 79 20 64 61 79 21 22 3b  s a happy day!";
1f6a0 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
1f6b0 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e  kquote>.**.** On
1f6c0 65 20 63 61 6e 20 75 73 65 20 74 68 69 73 20 74  e can use this t
1f6d0 65 78 74 20 69 6e 20 61 6e 20 53 51 4c 20 73 74  ext in an SQL st
1f6e0 61 74 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f  atement as follo
1f6f0 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
1f700 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
1f710 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c  char *zSQL = sql
1f720 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e  ite3_mprintf("IN
1f730 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20  SERT INTO table 
1f740 56 41 4c 55 45 53 28 27 25 71 27 29 22 2c 20 7a  VALUES('%q')", z
1f750 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74  Text);.**  sqlit
1f760 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c  e3_exec(db, zSQL
1f770 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20  , 0, 0, 0);.**  
1f780 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51  sqlite3_free(zSQ
1f790 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  L);.** </pre></b
1f7a0 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
1f7b0 20 42 65 63 61 75 73 65 20 74 68 65 20 25 71 20   Because the %q 
1f7c0 66 6f 72 6d 61 74 20 73 74 72 69 6e 67 20 69 73  format string is
1f7d0 20 75 73 65 64 2c 20 74 68 65 20 27 5c 27 27 20   used, the '\'' 
1f7e0 63 68 61 72 61 63 74 65 72 20 69 6e 20 7a 54 65  character in zTe
1f7f0 78 74 0a 2a 2a 20 69 73 20 65 73 63 61 70 65 64  xt.** is escaped
1f800 20 61 6e 64 20 74 68 65 20 53 51 4c 20 67 65 6e   and the SQL gen
1f810 65 72 61 74 65 64 20 69 73 20 61 73 20 66 6f 6c  erated is as fol
1f820 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lows:.**.** <blo
1f830 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
1f840 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61    INSERT INTO ta
1f850 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 27  ble1 VALUES('It'
1f860 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27  's a happy day!'
1f870 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ).** </pre></blo
1f880 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54  ckquote>.**.** T
1f890 68 69 73 20 69 73 20 63 6f 72 72 65 63 74 2e 20  his is correct. 
1f8a0 20 48 61 64 20 77 65 20 75 73 65 64 20 25 73 20   Had we used %s 
1f8b0 69 6e 73 74 65 61 64 20 6f 66 20 25 71 2c 20 74  instead of %q, t
1f8c0 68 65 20 67 65 6e 65 72 61 74 65 64 20 53 51 4c  he generated SQL
1f8d0 0a 2a 2a 20 77 6f 75 6c 64 20 68 61 76 65 20 6c  .** would have l
1f8e0 6f 6f 6b 65 64 20 6c 69 6b 65 20 74 68 69 73 3a  ooked like this:
1f8f0 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
1f900 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53  te><pre>.**  INS
1f910 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20  ERT INTO table1 
1f920 56 41 4c 55 45 53 28 27 49 74 27 73 20 61 20 68  VALUES('It's a h
1f930 61 70 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20  appy day!');.** 
1f940 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
1f950 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73  te>.**.** This s
1f960 65 63 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69 73  econd example is
1f970 20 61 6e 20 53 51 4c 20 73 79 6e 74 61 78 20 65   an SQL syntax e
1f980 72 72 6f 72 2e 20 20 41 73 20 61 20 67 65 6e 65  rror.  As a gene
1f990 72 61 6c 20 72 75 6c 65 20 79 6f 75 20 73 68 6f  ral rule you sho
1f9a0 75 6c 64 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73  uld.** always us
1f9b0 65 20 25 71 20 69 6e 73 74 65 61 64 20 6f 66 20  e %q instead of 
1f9c0 25 73 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e  %s when insertin
1f9d0 67 20 74 65 78 74 20 69 6e 74 6f 20 61 20 73 74  g text into a st
1f9e0 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a  ring literal..**
1f9f0 0a 2a 2a 20 5e 28 54 68 65 20 25 51 20 6f 70 74  .** ^(The %Q opt
1fa00 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25  ion works like %
1fa10 71 20 65 78 63 65 70 74 20 69 74 20 61 6c 73 6f  q except it also
1fa20 20 61 64 64 73 20 73 69 6e 67 6c 65 20 71 75 6f   adds single quo
1fa30 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68  tes around.** th
1fa40 65 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65  e outside of the
1fa50 20 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e 20 20   total string.  
1fa60 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 69 66  Additionally, if
1fa70 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69   the parameter i
1fa80 6e 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e  n the.** argumen
1fa90 74 20 6c 69 73 74 20 69 73 20 61 20 4e 55 4c 4c  t list is a NULL
1faa0 20 70 6f 69 6e 74 65 72 2c 20 25 51 20 73 75 62   pointer, %Q sub
1fab0 73 74 69 74 75 74 65 73 20 74 68 65 20 74 65 78  stitutes the tex
1fac0 74 20 22 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75  t "NULL" (withou
1fad0 74 0a 2a 2a 20 73 69 6e 67 6c 65 20 71 75 6f 74  t.** single quot
1fae0 65 73 29 2e 29 5e 20 20 53 6f 2c 20 66 6f 72 20  es).)^  So, for 
1faf0 65 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75  example, one cou
1fb00 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ld say:.**.** <b
1fb10 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
1fb20 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d  **  char *zSQL =
1fb30 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66   sqlite3_mprintf
1fb40 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61  ("INSERT INTO ta
1fb50 62 6c 65 20 56 41 4c 55 45 53 28 25 51 29 22 2c  ble VALUES(%Q)",
1fb60 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c   zText);.**  sql
1fb70 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53  ite3_exec(db, zS
1fb80 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a  QL, 0, 0, 0);.**
1fb90 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a    sqlite3_free(z
1fba0 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  SQL);.** </pre><
1fbb0 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
1fbc0 2a 2a 20 54 68 65 20 63 6f 64 65 20 61 62 6f 76  ** The code abov
1fbd0 65 20 77 69 6c 6c 20 72 65 6e 64 65 72 20 61 20  e will render a 
1fbe0 63 6f 72 72 65 63 74 20 53 51 4c 20 73 74 61 74  correct SQL stat
1fbf0 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 7a 53 51  ement in the zSQ
1fc00 4c 0a 2a 2a 20 76 61 72 69 61 62 6c 65 20 65 76  L.** variable ev
1fc10 65 6e 20 69 66 20 74 68 65 20 7a 54 65 78 74 20  en if the zText 
1fc20 76 61 72 69 61 62 6c 65 20 69 73 20 61 20 4e 55  variable is a NU
1fc30 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
1fc40 2a 20 5e 28 54 68 65 20 22 25 7a 22 20 66 6f 72  * ^(The "%z" for
1fc50 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 77  matting option w
1fc60 6f 72 6b 73 20 6c 69 6b 65 20 22 25 73 22 20 62  orks like "%s" b
1fc70 75 74 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 61  ut with the.** a
1fc80 64 64 69 74 69 6f 6e 20 74 68 61 74 20 61 66 74  ddition that aft
1fc90 65 72 20 74 68 65 20 73 74 72 69 6e 67 20 68 61  er the string ha
1fca0 73 20 62 65 65 6e 20 72 65 61 64 20 61 6e 64 20  s been read and 
1fcb0 63 6f 70 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74  copied into.** t
1fcc0 68 65 20 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69  he result, [sqli
1fcd0 74 65 33 5f 66 72 65 65 28 29 5d 20 69 73 20 63  te3_free()] is c
1fce0 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 69 6e 70  alled on the inp
1fcf0 75 74 20 73 74 72 69 6e 67 2e 29 5e 0a 2a 2f 0a  ut string.)^.*/.
1fd00 53 51 4c 49 54 45 5f 41 50 49 20 63 68 61 72 20  SQLITE_API char 
1fd10 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66  *sqlite3_mprintf
1fd20 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e  (const char*,...
1fd30 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 68  );.SQLITE_API ch
1fd40 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 6d 70 72  ar *sqlite3_vmpr
1fd50 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a  intf(const char*
1fd60 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 53 51 4c 49  , va_list);.SQLI
1fd70 54 45 5f 41 50 49 20 63 68 61 72 20 2a 73 71 6c  TE_API char *sql
1fd80 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 69 6e  ite3_snprintf(in
1fd90 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68  t,char*,const ch
1fda0 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 53 51 4c 49 54  ar*, ...);.SQLIT
1fdb0 45 5f 41 50 49 20 63 68 61 72 20 2a 73 71 6c 69  E_API char *sqli
1fdc0 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 69 6e  te3_vsnprintf(in
1fdd0 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68  t,char*,const ch
1fde0 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 0a  ar*, va_list);..
1fdf0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1fe00 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f  Memory Allocatio
1fe10 6e 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a  n Subsystem.**.*
1fe20 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72  * The SQLite cor
1fe30 65 20 75 73 65 73 20 74 68 65 73 65 20 74 68 72  e uses these thr
1fe40 65 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20  ee routines for 
1fe50 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a  all of its own.*
1fe60 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72  * internal memor
1fe70 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65  y allocation nee
1fe80 64 73 2e 20 22 43 6f 72 65 22 20 69 6e 20 74 68  ds. "Core" in th
1fe90 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65  e previous sente
1fea0 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20  nce.** does not 
1feb0 69 6e 63 6c 75 64 65 20 6f 70 65 72 61 74 69 6e  include operatin
1fec0 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 69  g-system specifi
1fed0 63 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  c VFS implementa
1fee0 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69  tion.  The.** Wi
1fef0 6e 64 6f 77 73 20 56 46 53 20 75 73 65 73 20 6e  ndows VFS uses n
1ff00 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61  ative malloc() a
1ff10 6e 64 20 66 72 65 65 28 29 20 66 6f 72 20 73 6f  nd free() for so
1ff20 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a  me operations..*
1ff30 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1ff40 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69  3_malloc() routi
1ff50 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ne returns a poi
1ff60 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a  nter to a block.
1ff70 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20  ** of memory at 
1ff80 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e  least N bytes in
1ff90 20 6c 65 6e 67 74 68 2c 20 77 68 65 72 65 20 4e   length, where N
1ffa0 20 69 73 20 74 68 65 20 70 61 72 61 6d 65 74 65   is the paramete
1ffb0 72 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65  r..** ^If sqlite
1ffc0 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e  3_malloc() is un
1ffd0 61 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20 73  able to obtain s
1ffe0 75 66 66 69 63 69 65 6e 74 20 66 72 65 65 0a 2a  ufficient free.*
1fff0 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65 74  * memory, it ret
20000 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  urns a NULL poin
20010 74 65 72 2e 20 20 5e 49 66 20 74 68 65 20 70 61  ter.  ^If the pa
20020 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20  rameter N to.** 
20030 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
20040 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61   is zero or nega
20050 74 69 76 65 20 74 68 65 6e 20 73 71 6c 69 74 65  tive then sqlite
20060 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75 72  3_malloc() retur
20070 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69  ns.** a NULL poi
20080 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c  nter..**.** ^Cal
20090 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65  ling sqlite3_fre
200a0 65 28 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74  e() with a point
200b0 65 72 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65  er previously re
200c0 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c  turned.** by sql
200d0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72  ite3_malloc() or
200e0 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
200f0 28 29 20 72 65 6c 65 61 73 65 73 20 74 68 61 74  () releases that
20100 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68   memory so.** th
20110 61 74 20 69 74 20 6d 69 67 68 74 20 62 65 20 72  at it might be r
20120 65 75 73 65 64 2e 20 20 5e 54 68 65 20 73 71 6c  eused.  ^The sql
20130 69 74 65 33 5f 66 72 65 65 28 29 20 72 6f 75 74  ite3_free() rout
20140 69 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f  ine is.** a no-o
20150 70 20 69 66 20 69 73 20 63 61 6c 6c 65 64 20 77  p if is called w
20160 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  ith a NULL point
20170 65 72 2e 20 20 50 61 73 73 69 6e 67 20 61 20 4e  er.  Passing a N
20180 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74  ULL pointer.** t
20190 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  o sqlite3_free()
201a0 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 20 20 41   is harmless.  A
201b0 66 74 65 72 20 62 65 69 6e 67 20 66 72 65 65 64  fter being freed
201c0 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75  , memory.** shou
201d0 6c 64 20 6e 65 69 74 68 65 72 20 62 65 20 72 65  ld neither be re
201e0 61 64 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20  ad nor written. 
201f0 20 45 76 65 6e 20 72 65 61 64 69 6e 67 20 70 72   Even reading pr
20200 65 76 69 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a  eviously freed.*
20210 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20 72  * memory might r
20220 65 73 75 6c 74 20 69 6e 20 61 20 73 65 67 6d 65  esult in a segme
20230 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72  ntation fault or
20240 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72   other severe er
20250 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63  ror..** Memory c
20260 6f 72 72 75 70 74 69 6f 6e 2c 20 61 20 73 65 67  orruption, a seg
20270 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c  mentation fault,
20280 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 65   or other severe
20290 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20   error.** might 
202a0 72 65 73 75 6c 74 20 69 66 20 73 71 6c 69 74 65  result if sqlite
202b0 33 5f 66 72 65 65 28 29 20 69 73 20 63 61 6c 6c  3_free() is call
202c0 65 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55  ed with a non-NU
202d0 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 61 74 0a  LL pointer that.
202e0 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74 61 69  ** was not obtai
202f0 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ned from sqlite3
20300 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c  _malloc() or sql
20310 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a  ite3_realloc()..
20320 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69  **.** ^(The sqli
20330 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 6e  te3_realloc() in
20340 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73  terface attempts
20350 20 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20   to resize a.** 
20360 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c  prior memory all
20370 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 61 74  ocation to be at
20380 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 2c 20   least N bytes, 
20390 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a  where N is the.*
203a0 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  * second paramet
203b0 65 72 2e 20 20 54 68 65 20 6d 65 6d 6f 72 79 20  er.  The memory 
203c0 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65  allocation to be
203d0 20 72 65 73 69 7a 65 64 20 69 73 20 74 68 65 20   resized is the 
203e0 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74  first.** paramet
203f0 65 72 2e 29 5e 20 5e 20 49 66 20 74 68 65 20 66  er.)^ ^ If the f
20400 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
20410 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  o sqlite3_reallo
20420 63 28 29 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c  c().** is a NULL
20430 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 69 74   pointer then it
20440 73 20 62 65 68 61 76 69 6f 72 20 69 73 20 69 64  s behavior is id
20450 65 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69  entical to calli
20460 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61  ng.** sqlite3_ma
20470 6c 6c 6f 63 28 4e 29 20 77 68 65 72 65 20 4e 20  lloc(N) where N 
20480 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  is the second pa
20490 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
204a0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a  e3_realloc()..**
204b0 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20   ^If the second 
204c0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
204d0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69  ite3_realloc() i
204e0 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67  s zero or.** neg
204f0 61 74 69 76 65 20 74 68 65 6e 20 74 68 65 20 62  ative then the b
20500 65 68 61 76 69 6f 72 20 69 73 20 65 78 61 63 74  ehavior is exact
20510 6c 79 20 74 68 65 20 73 61 6d 65 20 61 73 20 63  ly the same as c
20520 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65  alling.** sqlite
20530 33 5f 66 72 65 65 28 50 29 20 77 68 65 72 65 20  3_free(P) where 
20540 50 20 69 73 20 74 68 65 20 66 69 72 73 74 20 70  P is the first p
20550 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
20560 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a  te3_realloc()..*
20570 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  * ^sqlite3_reall
20580 6f 63 28 29 20 72 65 74 75 72 6e 73 20 61 20 70  oc() returns a p
20590 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f  ointer to a memo
205a0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a  ry allocation.**
205b0 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62   of at least N b
205c0 79 74 65 73 20 69 6e 20 73 69 7a 65 20 6f 72 20  ytes in size or 
205d0 4e 55 4c 4c 20 69 66 20 73 75 66 66 69 63 69 65  NULL if sufficie
205e0 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20 75 6e 61  nt memory is una
205f0 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66  vailable..** ^If
20600 20 4d 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f   M is the size o
20610 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f  f the prior allo
20620 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e  cation, then min
20630 28 4e 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f  (N,M) bytes.** o
20640 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f  f the prior allo
20650 63 61 74 69 6f 6e 20 61 72 65 20 63 6f 70 69 65  cation are copie
20660 64 20 69 6e 74 6f 20 74 68 65 20 62 65 67 69 6e  d into the begin
20670 6e 69 6e 67 20 6f 66 20 62 75 66 66 65 72 20 72  ning of buffer r
20680 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71  eturned.** by sq
20690 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20  lite3_realloc() 
206a0 61 6e 64 20 74 68 65 20 70 72 69 6f 72 20 61 6c  and the prior al
206b0 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65  location is free
206c0 64 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65  d..** ^If sqlite
206d0 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75  3_realloc() retu
206e0 72 6e 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74  rns NULL, then t
206f0 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  he prior allocat
20700 69 6f 6e 0a 2a 2a 20 69 73 20 6e 6f 74 20 66 72  ion.** is not fr
20710 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  eed..**.** ^The 
20720 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e 65 64 20  memory returned 
20730 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  by sqlite3_mallo
20740 63 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  c() and sqlite3_
20750 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20  realloc().** is 
20760 61 6c 77 61 79 73 20 61 6c 69 67 6e 65 64 20 74  always aligned t
20770 6f 20 61 74 20 6c 65 61 73 74 20 61 6e 20 38 20  o at least an 8 
20780 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2c 20 6f  byte boundary, o
20790 72 20 74 6f 20 61 0a 2a 2a 20 34 20 62 79 74 65  r to a.** 4 byte
207a0 20 62 6f 75 6e 64 61 72 79 20 69 66 20 74 68 65   boundary if the
207b0 20 5b 53 51 4c 49 54 45 5f 34 5f 42 59 54 45 5f   [SQLITE_4_BYTE_
207c0 41 4c 49 47 4e 45 44 5f 4d 41 4c 4c 4f 43 5d 20  ALIGNED_MALLOC] 
207d0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20  compile-time.** 
207e0 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a  option is used..
207f0 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20  **.** In SQLite 
20800 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e  version 3.5.0 an
20810 64 20 33 2e 35 2e 31 2c 20 69 74 20 77 61 73 20  d 3.5.1, it was 
20820 70 6f 73 73 69 62 6c 65 20 74 6f 20 64 65 66 69  possible to defi
20830 6e 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49 54 45  ne.** the SQLITE
20840 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c  _OMIT_MEMORY_ALL
20850 4f 43 41 54 49 4f 4e 20 77 68 69 63 68 20 77 6f  OCATION which wo
20860 75 6c 64 20 63 61 75 73 65 20 74 68 65 20 62 75  uld cause the bu
20870 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d  ilt-in.** implem
20880 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 73  entation of thes
20890 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65  e routines to be
208a0 20 6f 6d 69 74 74 65 64 2e 20 20 54 68 61 74 20   omitted.  That 
208b0 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73  capability.** is
208c0 20 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69   no longer provi
208d0 64 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74  ded.  Only built
208e0 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  -in memory alloc
208f0 61 74 6f 72 73 20 63 61 6e 20 62 65 20 75 73 65  ators can be use
20900 64 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72 20 74  d..**.** Prior t
20910 6f 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  o SQLite version
20920 20 33 2e 37 2e 31 30 2c 20 74 68 65 20 57 69 6e   3.7.10, the Win
20930 64 6f 77 73 20 4f 53 20 69 6e 74 65 72 66 61 63  dows OS interfac
20940 65 20 6c 61 79 65 72 20 63 61 6c 6c 65 64 0a 2a  e layer called.*
20950 2a 20 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c  * the system mal
20960 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29  loc() and free()
20970 20 64 69 72 65 63 74 6c 79 20 77 68 65 6e 20 63   directly when c
20980 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69 6c  onverting.** fil
20990 65 6e 61 6d 65 73 20 62 65 74 77 65 65 6e 20 74  enames between t
209a0 68 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e  he UTF-8 encodin
209b0 67 20 75 73 65 64 20 62 79 20 53 51 4c 69 74 65  g used by SQLite
209c0 0a 2a 2a 20 61 6e 64 20 77 68 61 74 65 76 65 72  .** and whatever
209d0 20 66 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 69   filename encodi
209e0 6e 67 20 69 73 20 75 73 65 64 20 62 79 20 74 68  ng is used by th
209f0 65 20 70 61 72 74 69 63 75 6c 61 72 20 57 69 6e  e particular Win
20a00 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61  dows.** installa
20a10 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 6c  tion.  Memory al
20a20 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 73 20  location errors 
20a30 77 65 72 65 20 64 65 74 65 63 74 65 64 2c 20 62  were detected, b
20a40 75 74 0a 2a 2a 20 74 68 65 79 20 77 65 72 65 20  ut.** they were 
20a50 72 65 70 6f 72 74 65 64 20 62 61 63 6b 20 61 73  reported back as
20a60 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45   [SQLITE_CANTOPE
20a70 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45  N] or.** [SQLITE
20a80 5f 49 4f 45 52 52 5d 20 72 61 74 68 65 72 20 74  _IOERR] rather t
20a90 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45  han [SQLITE_NOME
20aa0 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f  M]..**.** The po
20ab0 69 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 73 20  inter arguments 
20ac0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  to [sqlite3_free
20ad0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
20ae0 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d  _realloc()].** m
20af0 75 73 74 20 62 65 20 65 69 74 68 65 72 20 4e 55  ust be either NU
20b00 4c 4c 20 6f 72 20 65 6c 73 65 20 70 6f 69 6e 74  LL or else point
20b10 65 72 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ers obtained fro
20b20 6d 20 61 20 70 72 69 6f 72 0a 2a 2a 20 69 6e 76  m a prior.** inv
20b30 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69  ocation of [sqli
20b40 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72  te3_malloc()] or
20b50 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
20b60 63 28 29 5d 20 74 68 61 74 20 68 61 76 65 0a 2a  c()] that have.*
20b70 2a 20 6e 6f 74 20 79 65 74 20 62 65 65 6e 20 72  * not yet been r
20b80 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  eleased..**.** T
20b90 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
20ba0 75 73 74 20 6e 6f 74 20 72 65 61 64 20 6f 72 20  ust not read or 
20bb0 77 72 69 74 65 20 61 6e 79 20 70 61 72 74 20 6f  write any part o
20bc0 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f 66 20  f.** a block of 
20bd0 6d 65 6d 6f 72 79 20 61 66 74 65 72 20 69 74 20  memory after it 
20be0 68 61 73 20 62 65 65 6e 20 72 65 6c 65 61 73 65  has been release
20bf0 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  d using.** [sqli
20c00 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 72 20 5b  te3_free()] or [
20c10 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
20c20 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  )]..*/.SQLITE_AP
20c30 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  I void *sqlite3_
20c40 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 53 51 4c  malloc(int);.SQL
20c50 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71  ITE_API void *sq
20c60 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f  lite3_realloc(vo
20c70 69 64 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54  id*, int);.SQLIT
20c80 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74  E_API void sqlit
20c90 65 33 5f 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a  e3_free(void*);.
20ca0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
20cb0 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f   Memory Allocato
20cc0 72 20 53 74 61 74 69 73 74 69 63 73 0a 2a 2a 0a  r Statistics.**.
20cd0 2a 2a 20 53 51 4c 69 74 65 20 70 72 6f 76 69 64  ** SQLite provid
20ce0 65 73 20 74 68 65 73 65 20 74 77 6f 20 69 6e 74  es these two int
20cf0 65 72 66 61 63 65 73 20 66 6f 72 20 72 65 70 6f  erfaces for repo
20d00 72 74 69 6e 67 20 6f 6e 20 74 68 65 20 73 74 61  rting on the sta
20d10 74 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73  tus.** of the [s
20d20 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
20d30 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  , [sqlite3_free(
20d40 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  )], and [sqlite3
20d50 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72  _realloc()].** r
20d60 6f 75 74 69 6e 65 73 2c 20 77 68 69 63 68 20 66  outines, which f
20d70 6f 72 6d 20 74 68 65 20 62 75 69 6c 74 2d 69 6e  orm the built-in
20d80 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
20d90 6f 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a 2a 2a  on subsystem..**
20da0 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  .** ^The [sqlite
20db0 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
20dc0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
20dd0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
20de0 79 74 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72  ytes.** of memor
20df0 79 20 63 75 72 72 65 6e 74 6c 79 20 6f 75 74 73  y currently outs
20e00 74 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65  tanding (malloce
20e10 64 20 62 75 74 20 6e 6f 74 20 66 72 65 65 64 29  d but not freed)
20e20 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74  ..** ^The [sqlit
20e30 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
20e40 74 65 72 28 29 5d 20 72 6f 75 74 69 6e 65 20 72  ter()] routine r
20e50 65 74 75 72 6e 73 20 74 68 65 20 6d 61 78 69 6d  eturns the maxim
20e60 75 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 5b  um.** value of [
20e70 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
20e80 73 65 64 28 29 5d 20 73 69 6e 63 65 20 74 68 65  sed()] since the
20e90 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b   high-water mark
20ea0 0a 2a 2a 20 77 61 73 20 6c 61 73 74 20 72 65 73  .** was last res
20eb0 65 74 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 73  et.  ^The values
20ec0 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
20ed0 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
20ee0 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  d()] and.** [sql
20ef0 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
20f00 77 61 74 65 72 28 29 5d 20 69 6e 63 6c 75 64 65  water()] include
20f10 20 61 6e 79 20 6f 76 65 72 68 65 61 64 0a 2a 2a   any overhead.**
20f20 20 61 64 64 65 64 20 62 79 20 53 51 4c 69 74 65   added by SQLite
20f30 20 69 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e   in its implemen
20f40 74 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74  tation of [sqlit
20f50 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a  e3_malloc()],.**
20f60 20 62 75 74 20 6e 6f 74 20 6f 76 65 72 68 65 61   but not overhea
20f70 64 20 61 64 64 65 64 20 62 79 20 74 68 65 20 61  d added by the a
20f80 6e 79 20 75 6e 64 65 72 6c 79 69 6e 67 20 73 79  ny underlying sy
20f90 73 74 65 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20  stem library.** 
20fa0 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 5b 73  routines that [s
20fb0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
20fc0 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a   may call..**.**
20fd0 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 68 69 67   ^The memory hig
20fe0 68 2d 77 61 74 65 72 20 6d 61 72 6b 20 69 73 20  h-water mark is 
20ff0 72 65 73 65 74 20 74 6f 20 74 68 65 20 63 75 72  reset to the cur
21000 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a  rent value of.**
21010 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
21020 5f 75 73 65 64 28 29 5d 20 69 66 20 61 6e 64 20  _used()] if and 
21030 6f 6e 6c 79 20 69 66 20 74 68 65 20 70 61 72 61  only if the para
21040 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c  meter to.** [sql
21050 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
21060 77 61 74 65 72 28 29 5d 20 69 73 20 74 72 75 65  water()] is true
21070 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 20 72 65  .  ^The value re
21080 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 5b 73 71  turned.** by [sq
21090 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
210a0 68 77 61 74 65 72 28 31 29 5d 20 69 73 20 74 68  hwater(1)] is th
210b0 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72  e high-water mar
210c0 6b 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 74 68  k.** prior to th
210d0 65 20 72 65 73 65 74 2e 0a 2a 2f 0a 53 51 4c 49  e reset..*/.SQLI
210e0 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69  TE_API sqlite3_i
210f0 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d  nt64 sqlite3_mem
21100 6f 72 79 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a  ory_used(void);.
21110 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74  SQLITE_API sqlit
21120 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
21130 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
21140 72 28 69 6e 74 20 72 65 73 65 74 46 6c 61 67 29  r(int resetFlag)
21150 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
21160 46 3a 20 50 73 65 75 64 6f 2d 52 61 6e 64 6f 6d  F: Pseudo-Random
21170 20 4e 75 6d 62 65 72 20 47 65 6e 65 72 61 74 6f   Number Generato
21180 72 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63  r.**.** SQLite c
21190 6f 6e 74 61 69 6e 73 20 61 20 68 69 67 68 2d 71  ontains a high-q
211a0 75 61 6c 69 74 79 20 70 73 65 75 64 6f 2d 72 61  uality pseudo-ra
211b0 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67 65 6e 65  ndom number gene
211c0 72 61 74 6f 72 20 28 50 52 4e 47 29 20 75 73 65  rator (PRNG) use
211d0 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63 74 20 72  d to.** select r
211e0 61 6e 64 6f 6d 20 5b 52 4f 57 49 44 20 7c 20 52  andom [ROWID | R
211f0 4f 57 49 44 73 5d 20 77 68 65 6e 20 69 6e 73 65  OWIDs] when inse
21200 72 74 69 6e 67 20 6e 65 77 20 72 65 63 6f 72 64  rting new record
21210 73 20 69 6e 74 6f 20 61 20 74 61 62 6c 65 20 74  s into a table t
21220 68 61 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 75  hat.** already u
21230 73 65 73 20 74 68 65 20 6c 61 72 67 65 73 74 20  ses the largest 
21240 70 6f 73 73 69 62 6c 65 20 5b 52 4f 57 49 44 5d  possible [ROWID]
21250 2e 20 20 54 68 65 20 50 52 4e 47 20 69 73 20 61  .  The PRNG is a
21260 6c 73 6f 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20  lso used for.** 
21270 74 68 65 20 62 75 69 6c 64 2d 69 6e 20 72 61 6e  the build-in ran
21280 64 6f 6d 28 29 20 61 6e 64 20 72 61 6e 64 6f 6d  dom() and random
21290 62 6c 6f 62 28 29 20 53 51 4c 20 66 75 6e 63 74  blob() SQL funct
212a0 69 6f 6e 73 2e 20 20 54 68 69 73 20 69 6e 74 65  ions.  This inte
212b0 72 66 61 63 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20  rface allows.** 
212c0 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 6f 20  applications to 
212d0 61 63 63 65 73 73 20 74 68 65 20 73 61 6d 65 20  access the same 
212e0 50 52 4e 47 20 66 6f 72 20 6f 74 68 65 72 20 70  PRNG for other p
212f0 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e  urposes..**.** ^
21300 41 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 72  A call to this r
21310 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20 4e 20  outine stores N 
21320 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e  bytes of randomn
21330 65 73 73 20 69 6e 74 6f 20 62 75 66 66 65 72 20  ess into buffer 
21340 50 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  P..**.** ^The fi
21350 72 73 74 20 74 69 6d 65 20 74 68 69 73 20 72 6f  rst time this ro
21360 75 74 69 6e 65 20 69 73 20 69 6e 76 6f 6b 65 64  utine is invoked
21370 20 28 65 69 74 68 65 72 20 69 6e 74 65 72 6e 61   (either interna
21380 6c 6c 79 20 6f 72 20 62 79 0a 2a 2a 20 74 68 65  lly or by.** the
21390 20 61 70 70 6c 69 63 61 74 69 6f 6e 29 20 74 68   application) th
213a0 65 20 50 52 4e 47 20 69 73 20 73 65 65 64 65 64  e PRNG is seeded
213b0 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73   using randomnes
213c0 73 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72  s obtained.** fr
213d0 6f 6d 20 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65  om the xRandomne
213e0 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65  ss method of the
213f0 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65   default [sqlite
21400 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a  3_vfs] object..*
21410 2a 20 5e 4f 6e 20 61 6c 6c 20 73 75 62 73 65 71  * ^On all subseq
21420 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 73  uent invocations
21430 2c 20 74 68 65 20 70 73 65 75 64 6f 2d 72 61 6e  , the pseudo-ran
21440 64 6f 6d 6e 65 73 73 20 69 73 20 67 65 6e 65 72  domness is gener
21450 61 74 65 64 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c  ated.** internal
21460 6c 79 20 61 6e 64 20 77 69 74 68 6f 75 74 20 72  ly and without r
21470 65 63 6f 75 72 73 65 20 74 6f 20 74 68 65 20 5b  ecourse to the [
21480 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 52 61  sqlite3_vfs] xRa
21490 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74 68  ndomness.** meth
214a0 6f 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  od..*/.SQLITE_AP
214b0 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  I void sqlite3_r
214c0 61 6e 64 6f 6d 6e 65 73 73 28 69 6e 74 20 4e 2c  andomness(int N,
214d0 20 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a   void *P);../*.*
214e0 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70  * CAPI3REF: Comp
214f0 69 6c 65 2d 54 69 6d 65 20 41 75 74 68 6f 72 69  ile-Time Authori
21500 7a 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73  zation Callbacks
21510 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75  .**.** ^This rou
21520 74 69 6e 65 20 72 65 67 69 73 74 65 72 73 20 61  tine registers a
21530 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  n authorizer cal
21540 6c 62 61 63 6b 20 77 69 74 68 20 61 20 70 61 72  lback with a par
21550 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61  ticular.** [data
21560 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
21570 2c 20 73 75 70 70 6c 69 65 64 20 69 6e 20 74 68  , supplied in th
21580 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
21590 2e 0a 2a 2a 20 5e 54 68 65 20 61 75 74 68 6f 72  ..** ^The author
215a0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
215b0 20 69 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c 20   invoked as SQL 
215c0 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 62  statements are b
215d0 65 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a  eing compiled.**
215e0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   by [sqlite3_pre
215f0 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76  pare()] or its v
21600 61 72 69 61 6e 74 73 20 5b 73 71 6c 69 74 65 33  ariants [sqlite3
21610 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a  _prepare_v2()],.
21620 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
21630 61 72 65 31 36 28 29 5d 20 61 6e 64 20 5b 73 71  are16()] and [sq
21640 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
21650 76 32 28 29 5d 2e 20 20 5e 41 74 20 76 61 72 69  v2()].  ^At vari
21660 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75  ous.** points du
21670 72 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 61  ring the compila
21680 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61 73  tion process, as
21690 20 6c 6f 67 69 63 20 69 73 20 62 65 69 6e 67 20   logic is being 
216a0 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65  created.** to pe
216b0 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 61 63  rform various ac
216c0 74 69 6f 6e 73 2c 20 74 68 65 20 61 75 74 68 6f  tions, the autho
216d0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
216e0 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20  s invoked to.** 
216f0 73 65 65 20 69 66 20 74 68 6f 73 65 20 61 63 74  see if those act
21700 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65 64  ions are allowed
21710 2e 20 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a  .  ^The authoriz
21720 65 72 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75  er callback shou
21730 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51  ld.** return [SQ
21740 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f  LITE_OK] to allo
21750 77 20 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53  w the action, [S
21760 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f  QLITE_IGNORE] to
21770 20 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a   disallow the.**
21780 20 73 70 65 63 69 66 69 63 20 61 63 74 69 6f 6e   specific action
21790 20 62 75 74 20 61 6c 6c 6f 77 20 74 68 65 20 53   but allow the S
217a0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20  QL statement to 
217b0 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a  continue to be.*
217c0 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b  * compiled, or [
217d0 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20  SQLITE_DENY] to 
217e0 63 61 75 73 65 20 74 68 65 20 65 6e 74 69 72 65  cause the entire
217f0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
21800 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64  o be.** rejected
21810 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20   with an error. 
21820 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72 69   ^If the authori
21830 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  zer callback ret
21840 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75  urns.** any valu
21850 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  e other than [SQ
21860 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53  LITE_IGNORE], [S
21870 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53  QLITE_OK], or [S
21880 51 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74  QLITE_DENY].** t
21890 68 65 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33  hen the [sqlite3
218a0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
218b0 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c  r equivalent cal
218c0 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64  l that triggered
218d0 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a  .** the authoriz
218e0 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74  er will fail wit
218f0 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61  h an error messa
21900 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74  ge..**.** When t
21910 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
21920 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c  rns [SQLITE_OK],
21930 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20   that means the 
21940 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71  operation.** req
21950 75 65 73 74 65 64 20 69 73 20 6f 6b 2e 20 20 5e  uested is ok.  ^
21960 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63  When the callbac
21970 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  k returns [SQLIT
21980 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20  E_DENY], the.** 
21990 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
219a0 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61  _v2()] or equiva
219b0 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74  lent call that t
219c0 72 69 67 67 65 72 65 64 20 74 68 65 0a 2a 2a 20  riggered the.** 
219d0 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20  authorizer will 
219e0 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72  fail with an err
219f0 6f 72 20 6d 65 73 73 61 67 65 20 65 78 70 6c 61  or message expla
21a00 69 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63  ining that.** ac
21a10 63 65 73 73 20 69 73 20 64 65 6e 69 65 64 2e 20  cess is denied. 
21a20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
21a30 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  t parameter to t
21a40 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
21a50 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79  llback is a copy
21a60 20 6f 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a   of the third.**
21a70 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
21a80 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  e sqlite3_set_au
21a90 74 68 6f 72 69 7a 65 72 28 29 20 69 6e 74 65 72  thorizer() inter
21aa0 66 61 63 65 2e 20 5e 54 68 65 20 73 65 63 6f 6e  face. ^The secon
21ab0 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74  d parameter.** t
21ac0 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  o the callback i
21ad0 73 20 61 6e 20 69 6e 74 65 67 65 72 20 5b 53 51  s an integer [SQ
21ae0 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 69  LITE_COPY | acti
21af0 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70  on code] that sp
21b00 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 70  ecifies.** the p
21b10 61 72 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e  articular action
21b20 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65   to be authorize
21b30 64 2e 20 5e 54 68 65 20 74 68 69 72 64 20 74 68  d. ^The third th
21b40 72 6f 75 67 68 20 73 69 78 74 68 20 70 61 72 61  rough sixth para
21b50 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65  meters.** to the
21b60 20 63 61 6c 6c 62 61 63 6b 20 61 72 65 20 7a 65   callback are ze
21b70 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74  ro-terminated st
21b80 72 69 6e 67 73 20 74 68 61 74 20 63 6f 6e 74 61  rings that conta
21b90 69 6e 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a  in additional.**
21ba0 20 64 65 74 61 69 6c 73 20 61 62 6f 75 74 20 74   details about t
21bb0 68 65 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20  he action to be 
21bc0 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a  authorized..**.*
21bd0 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e  * ^If the action
21be0 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45   code is [SQLITE
21bf0 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68  _READ].** and th
21c00 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
21c10 6e 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  ns [SQLITE_IGNOR
21c20 45 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b  E] then the.** [
21c30 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
21c40 6e 74 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73  nt] statement is
21c50 20 63 6f 6e 73 74 72 75 63 74 65 64 20 74 6f 20   constructed to 
21c60 73 75 62 73 74 69 74 75 74 65 0a 2a 2a 20 61 20  substitute.** a 
21c70 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c  NULL value in pl
21c80 61 63 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65  ace of the table
21c90 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75   column that wou
21ca0 6c 64 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20  ld have.** been 
21cb0 72 65 61 64 20 69 66 20 5b 53 51 4c 49 54 45 5f  read if [SQLITE_
21cc0 4f 4b 5d 20 68 61 64 20 62 65 65 6e 20 72 65 74  OK] had been ret
21cd0 75 72 6e 65 64 2e 20 20 54 68 65 20 5b 53 51 4c  urned.  The [SQL
21ce0 49 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72  ITE_IGNORE].** r
21cf0 65 74 75 72 6e 20 63 61 6e 20 62 65 20 75 73 65  eturn can be use
21d00 64 20 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74  d to deny an unt
21d10 72 75 73 74 65 64 20 75 73 65 72 20 61 63 63 65  rusted user acce
21d20 73 73 20 74 6f 20 69 6e 64 69 76 69 64 75 61 6c  ss to individual
21d30 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61  .** columns of a
21d40 20 74 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 74   table..** ^If t
21d50 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69  he action code i
21d60 73 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45  s [SQLITE_DELETE
21d70 5d 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61  ] and the callba
21d80 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53  ck returns.** [S
21d90 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68  QLITE_IGNORE] th
21da0 65 6e 20 74 68 65 20 5b 44 45 4c 45 54 45 5d 20  en the [DELETE] 
21db0 6f 70 65 72 61 74 69 6f 6e 20 70 72 6f 63 65 65  operation procee
21dc0 64 73 20 62 75 74 20 74 68 65 0a 2a 2a 20 5b 74  ds but the.** [t
21dd0 72 75 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a 61  runcate optimiza
21de0 74 69 6f 6e 5d 20 69 73 20 64 69 73 61 62 6c 65  tion] is disable
21df0 64 20 61 6e 64 20 61 6c 6c 20 72 6f 77 73 20 61  d and all rows a
21e00 72 65 20 64 65 6c 65 74 65 64 20 69 6e 64 69 76  re deleted indiv
21e10 69 64 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41  idually..**.** A
21e20 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20  n authorizer is 
21e30 75 73 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74  used when [sqlit
21e40 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65  e3_prepare | pre
21e50 70 61 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73  paring].** SQL s
21e60 74 61 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61  tatements from a
21e70 6e 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72  n untrusted sour
21e80 63 65 2c 20 74 6f 20 65 6e 73 75 72 65 20 74 68  ce, to ensure th
21e90 61 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  at the SQL state
21ea0 6d 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20  ments.** do not 
21eb0 74 72 79 20 74 6f 20 61 63 63 65 73 73 20 64 61  try to access da
21ec0 74 61 20 74 68 65 79 20 61 72 65 20 6e 6f 74 20  ta they are not 
21ed0 61 6c 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c 20  allowed to see, 
21ee0 6f 72 20 74 68 61 74 20 74 68 65 79 20 64 6f 20  or that they do 
21ef0 6e 6f 74 0a 2a 2a 20 74 72 79 20 74 6f 20 65 78  not.** try to ex
21f00 65 63 75 74 65 20 6d 61 6c 69 63 69 6f 75 73 20  ecute malicious 
21f10 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20  statements that 
21f20 64 61 6d 61 67 65 20 74 68 65 20 64 61 74 61 62  damage the datab
21f30 61 73 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61  ase.  For.** exa
21f40 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61  mple, an applica
21f50 74 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 61  tion may allow a
21f60 20 75 73 65 72 20 74 6f 20 65 6e 74 65 72 20 61   user to enter a
21f70 72 62 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c 20  rbitrary.** SQL 
21f80 71 75 65 72 69 65 73 20 66 6f 72 20 65 76 61 6c  queries for eval
21f90 75 61 74 69 6f 6e 20 62 79 20 61 20 64 61 74 61  uation by a data
21fa0 62 61 73 65 2e 20 20 42 75 74 20 74 68 65 20 61  base.  But the a
21fb0 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 0a  pplication does.
21fc0 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74 68 65 20  ** not want the 
21fd0 75 73 65 72 20 74 6f 20 62 65 20 61 62 6c 65 20  user to be able 
21fe0 74 6f 20 6d 61 6b 65 20 61 72 62 69 74 72 61 72  to make arbitrar
21ff0 79 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65  y changes to the
22000 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 41  .** database.  A
22010 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 75  n authorizer cou
22020 6c 64 20 74 68 65 6e 20 62 65 20 70 75 74 20 69  ld then be put i
22030 6e 20 70 6c 61 63 65 20 77 68 69 6c 65 20 74 68  n place while th
22040 65 0a 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72 65  e.** user-entere
22050 64 20 53 51 4c 20 69 73 20 62 65 69 6e 67 20 5b  d SQL is being [
22060 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20  sqlite3_prepare 
22070 7c 20 70 72 65 70 61 72 65 64 5d 20 74 68 61 74  | prepared] that
22080 0a 2a 2a 20 64 69 73 61 6c 6c 6f 77 73 20 65 76  .** disallows ev
22090 65 72 79 74 68 69 6e 67 20 65 78 63 65 70 74 20  erything except 
220a0 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
220b0 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69  nts..**.** Appli
220c0 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6e 65 65  cations that nee
220d0 64 20 74 6f 20 70 72 6f 63 65 73 73 20 53 51 4c  d to process SQL
220e0 20 66 72 6f 6d 20 75 6e 74 72 75 73 74 65 64 20   from untrusted 
220f0 73 6f 75 72 63 65 73 0a 2a 2a 20 6d 69 67 68 74  sources.** might
22100 20 61 6c 73 6f 20 63 6f 6e 73 69 64 65 72 20 6c   also consider l
22110 6f 77 65 72 69 6e 67 20 72 65 73 6f 75 72 63 65  owering resource
22120 20 6c 69 6d 69 74 73 20 75 73 69 6e 67 20 5b 73   limits using [s
22130 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a  qlite3_limit()].
22140 2a 2a 20 61 6e 64 20 6c 69 6d 69 74 69 6e 67 20  ** and limiting 
22150 64 61 74 61 62 61 73 65 20 73 69 7a 65 20 75 73  database size us
22160 69 6e 67 20 74 68 65 20 5b 6d 61 78 5f 70 61 67  ing the [max_pag
22170 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41  e_count] [PRAGMA
22180 5d 0a 2a 2a 20 69 6e 20 61 64 64 69 74 69 6f 6e  ].** in addition
22190 20 74 6f 20 75 73 69 6e 67 20 61 6e 20 61 75 74   to using an aut
221a0 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  horizer..**.** ^
221b0 28 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 61  (Only a single a
221c0 75 74 68 6f 72 69 7a 65 72 20 63 61 6e 20 62 65  uthorizer can be
221d0 20 69 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20 64   in place on a d
221e0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
221f0 6f 6e 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65 2e  on.** at a time.
22200 20 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 73    Each call to s
22210 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
22220 72 69 7a 65 72 20 6f 76 65 72 72 69 64 65 73 20  rizer overrides 
22230 74 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20  the.** previous 
22240 63 61 6c 6c 2e 29 5e 20 20 5e 44 69 73 61 62 6c  call.)^  ^Disabl
22250 65 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  e the authorizer
22260 20 62 79 20 69 6e 73 74 61 6c 6c 69 6e 67 20 61   by installing a
22270 20 4e 55 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a   NULL callback..
22280 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65  ** The authorize
22290 72 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79  r is disabled by
222a0 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20   default..**.** 
222b0 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  The authorizer c
222c0 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74  allback must not
222d0 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61   do anything tha
222e0 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a  t will modify.**
222f0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
22300 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e  nnection that in
22310 76 6f 6b 65 64 20 74 68 65 20 61 75 74 68 6f 72  voked the author
22320 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a  izer callback..*
22330 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c  * Note that [sql
22340 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
22350 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
22360 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64  step()] both mod
22370 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74  ify their.** dat
22380 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
22390 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e  s for the meanin
223a0 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e  g of "modify" in
223b0 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e   this paragraph.
223c0 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 5b 73 71  .**.** ^When [sq
223d0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
223e0 28 29 5d 20 69 73 20 75 73 65 64 20 74 6f 20 70  ()] is used to p
223f0 72 65 70 61 72 65 20 61 20 73 74 61 74 65 6d 65  repare a stateme
22400 6e 74 2c 20 74 68 65 0a 2a 2a 20 73 74 61 74 65  nt, the.** state
22410 6d 65 6e 74 20 6d 69 67 68 74 20 62 65 20 72 65  ment might be re
22420 2d 70 72 65 70 61 72 65 64 20 64 75 72 69 6e 67  -prepared during
22430 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
22440 5d 20 64 75 65 20 74 6f 20 61 20 0a 2a 2a 20 73  ] due to a .** s
22450 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 20 20 48  chema change.  H
22460 65 6e 63 65 2c 20 74 68 65 20 61 70 70 6c 69 63  ence, the applic
22470 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 65 6e 73  ation should ens
22480 75 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  ure that the.** 
22490 63 6f 72 72 65 63 74 20 61 75 74 68 6f 72 69 7a  correct authoriz
224a0 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 6d 61  er callback rema
224b0 69 6e 73 20 69 6e 20 70 6c 61 63 65 20 64 75 72  ins in place dur
224c0 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ing the [sqlite3
224d0 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _step()]..**.** 
224e0 5e 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 61  ^Note that the a
224f0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
22500 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e  ck is invoked on
22510 6c 79 20 64 75 72 69 6e 67 0a 2a 2a 20 5b 73 71  ly during.** [sq
22520 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
22530 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73   or its variants
22540 2e 20 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e  .  Authorization
22550 20 69 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f   is not.** perfo
22560 72 6d 65 64 20 64 75 72 69 6e 67 20 73 74 61 74  rmed during stat
22570 65 6d 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e  ement evaluation
22580 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   in [sqlite3_ste
22590 70 28 29 5d 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20  p()], unless.** 
225a0 61 73 20 73 74 61 74 65 64 20 69 6e 20 74 68 65  as stated in the
225b0 20 70 72 65 76 69 6f 75 73 20 70 61 72 61 67 72   previous paragr
225c0 61 70 68 2c 20 73 71 6c 69 74 65 33 5f 73 74 65  aph, sqlite3_ste
225d0 70 28 29 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73  p() invokes.** s
225e0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
225f0 32 28 29 20 74 6f 20 72 65 70 72 65 70 61 72 65  2() to reprepare
22600 20 61 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74   a statement aft
22610 65 72 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e  er a schema chan
22620 67 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  ge..*/.SQLITE_AP
22630 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 65  I int sqlite3_se
22640 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a 20 20  t_authorizer(.  
22650 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74 20  sqlite3*,.  int 
22660 28 2a 78 41 75 74 68 29 28 76 6f 69 64 2a 2c 69  (*xAuth)(void*,i
22670 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63  nt,const char*,c
22680 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74  onst char*,const
22690 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61   char*,const cha
226a0 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55 73  r*),.  void *pUs
226b0 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  erData.);../*.**
226c0 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f   CAPI3REF: Autho
226d0 72 69 7a 65 72 20 52 65 74 75 72 6e 20 43 6f 64  rizer Return Cod
226e0 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71  es.**.** The [sq
226f0 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
22700 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65  izer | authorize
22710 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  r callback funct
22720 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74  ion] must.** ret
22730 75 72 6e 20 65 69 74 68 65 72 20 5b 53 51 4c 49  urn either [SQLI
22740 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66  TE_OK] or one of
22750 20 74 68 65 73 65 20 74 77 6f 20 63 6f 6e 73 74   these two const
22760 61 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a  ants in order.**
22770 20 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69 74   to signal SQLit
22780 65 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  e whether or not
22790 20 74 68 65 20 61 63 74 69 6f 6e 20 69 73 20 70   the action is p
227a0 65 72 6d 69 74 74 65 64 2e 20 20 53 65 65 20 74  ermitted.  See t
227b0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  he.** [sqlite3_s
227c0 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20  et_authorizer | 
227d0 61 75 74 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d  authorizer docum
227e0 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64  entation] for ad
227f0 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f  ditional.** info
22800 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e  rmation..**.** N
22810 6f 74 65 20 74 68 61 74 20 53 51 4c 49 54 45 5f  ote that SQLITE_
22820 49 47 4e 4f 52 45 20 69 73 20 61 6c 73 6f 20 75  IGNORE is also u
22830 73 65 64 20 61 73 20 61 20 5b 53 51 4c 49 54 45  sed as a [SQLITE
22840 5f 52 4f 4c 4c 42 41 43 4b 20 7c 20 72 65 74 75  _ROLLBACK | retu
22850 72 6e 20 63 6f 64 65 5d 0a 2a 2a 20 66 72 6f 6d  rn code].** from
22860 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 74   the [sqlite3_vt
22870 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29  ab_on_conflict()
22880 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a  ] interface..*/.
22890 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
228a0 45 4e 59 20 20 20 31 20 20 20 2f 2a 20 41 62 6f  ENY   1   /* Abo
228b0 72 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  rt the SQL state
228c0 6d 65 6e 74 20 77 69 74 68 20 61 6e 20 65 72 72  ment with an err
228d0 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  or */.#define SQ
228e0 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32 20 20 20  LITE_IGNORE 2   
228f0 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61  /* Don't allow a
22900 63 63 65 73 73 2c 20 62 75 74 20 64 6f 6e 27 74  ccess, but don't
22910 20 67 65 6e 65 72 61 74 65 20 61 6e 20 65 72 72   generate an err
22920 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  or */../*.** CAP
22930 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65  I3REF: Authorize
22940 72 20 41 63 74 69 6f 6e 20 43 6f 64 65 73 0a 2a  r Action Codes.*
22950 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65  *.** The [sqlite
22960 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
22970 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  ()] interface re
22980 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61  gisters a callba
22990 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74  ck function.** t
229a0 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 74  hat is invoked t
229b0 6f 20 61 75 74 68 6f 72 69 7a 65 20 63 65 72 74  o authorize cert
229c0 61 69 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ain SQL statemen
229d0 74 20 61 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a  t actions.  The.
229e0 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  ** second parame
229f0 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  ter to the callb
22a00 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ack is an intege
22a10 72 20 63 6f 64 65 20 74 68 61 74 20 73 70 65 63  r code that spec
22a20 69 66 69 65 73 0a 2a 2a 20 77 68 61 74 20 61 63  ifies.** what ac
22a30 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 61 75  tion is being au
22a40 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 73 65  thorized.  These
22a50 20 61 72 65 20 74 68 65 20 69 6e 74 65 67 65 72   are the integer
22a60 20 61 63 74 69 6f 6e 20 63 6f 64 65 73 20 74 68   action codes th
22a70 61 74 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72  at.** the author
22a80 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61  izer callback ma
22a90 79 20 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a  y be passed..**.
22aa0 2a 2a 20 54 68 65 73 65 20 61 63 74 69 6f 6e 20  ** These action 
22ab0 63 6f 64 65 20 76 61 6c 75 65 73 20 73 69 67 6e  code values sign
22ac0 69 66 79 20 77 68 61 74 20 6b 69 6e 64 20 6f 66  ify what kind of
22ad0 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 74 6f   operation is to
22ae0 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65   be.** authorize
22af0 64 2e 20 20 54 68 65 20 33 72 64 20 61 6e 64 20  d.  The 3rd and 
22b00 34 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74  4th parameters t
22b10 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 61 74  o the authorizat
22b20 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20  ion.** callback 
22b30 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65  function will be
22b40 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20 4e   parameters or N
22b50 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  ULL depending on
22b60 20 77 68 69 63 68 20 6f 66 20 74 68 65 73 65 0a   which of these.
22b70 2a 2a 20 63 6f 64 65 73 20 69 73 20 75 73 65 64  ** codes is used
22b80 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70   as the second p
22b90 61 72 61 6d 65 74 65 72 2e 20 20 5e 28 54 68 65  arameter.  ^(The
22ba0 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   5th parameter t
22bb0 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69  o the.** authori
22bc0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
22bd0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
22be0 64 61 74 61 62 61 73 65 20 28 22 6d 61 69 6e 22  database ("main"
22bf0 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63  , "temp",.** etc
22c00 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62 6c 65  .) if applicable
22c10 2e 29 5e 20 20 5e 54 68 65 20 36 74 68 20 70 61  .)^  ^The 6th pa
22c20 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61  rameter to the a
22c30 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
22c40 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d  ck.** is the nam
22c50 65 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d  e of the inner-m
22c60 6f 73 74 20 74 72 69 67 67 65 72 20 6f 72 20 76  ost trigger or v
22c70 69 65 77 20 74 68 61 74 20 69 73 20 72 65 73 70  iew that is resp
22c80 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74  onsible for.** t
22c90 68 65 20 61 63 63 65 73 73 20 61 74 74 65 6d 70  he access attemp
22ca0 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69  t or NULL if thi
22cb0 73 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74  s access attempt
22cc0 20 69 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f   is directly fro
22cd0 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53  m.** top-level S
22ce0 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a  QL code..*/./***
22cf0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
22d00 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
22d10 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a  ******** 3rd ***
22d20 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a  ********* 4th **
22d30 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69  *********/.#defi
22d40 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
22d50 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20  _INDEX          
22d60 31 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  1   /* Index Nam
22d70 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  e      Table Nam
22d80 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
22d90 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
22da0 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32  TABLE          2
22db0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
22dc0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
22dd0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
22de0 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
22df0 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 33 20  EMP_INDEX     3 
22e00 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
22e10 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20       Table Name 
22e20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
22e30 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45  SQLITE_CREATE_TE
22e40 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 34 20 20  MP_TABLE     4  
22e50 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
22e60 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
22e70 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
22e80 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d  QLITE_CREATE_TEM
22e90 50 5f 54 52 49 47 47 45 52 20 20 20 35 20 20 20  P_TRIGGER   5   
22ea0 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20  /* Trigger Name 
22eb0 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
22ec0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
22ed0 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50  LITE_CREATE_TEMP
22ee0 5f 56 49 45 57 20 20 20 20 20 20 36 20 20 20 2f  _VIEW      6   /
22ef0 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20  * View Name     
22f00 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
22f10 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
22f20 49 54 45 5f 43 52 45 41 54 45 5f 54 52 49 47 47  ITE_CREATE_TRIGG
22f30 45 52 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a  ER        7   /*
22f40 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20   Trigger Name   
22f50 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
22f60 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
22f70 54 45 5f 43 52 45 41 54 45 5f 56 49 45 57 20 20  TE_CREATE_VIEW  
22f80 20 20 20 20 20 20 20 20 20 38 20 20 20 2f 2a 20           8   /* 
22f90 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20  View Name       
22fa0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
22fb0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
22fc0 45 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20  E_DELETE        
22fd0 20 20 20 20 20 20 20 20 39 20 20 20 2f 2a 20 54          9   /* T
22fe0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
22ff0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
23000 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
23010 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20 20 20 20  _DROP_INDEX     
23020 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 49 6e        10   /* In
23030 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61  dex Name      Ta
23040 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
23050 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
23060 44 52 4f 50 5f 54 41 42 4c 45 20 20 20 20 20 20  DROP_TABLE      
23070 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 61 62       11   /* Tab
23080 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
23090 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
230a0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
230b0 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20  ROP_TEMP_INDEX  
230c0 20 20 20 20 31 32 20 20 20 2f 2a 20 49 6e 64 65      12   /* Inde
230d0 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c  x Name      Tabl
230e0 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
230f0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
23100 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20  OP_TEMP_TABLE   
23110 20 20 20 31 33 20 20 20 2f 2a 20 54 61 62 6c 65     13   /* Table
23120 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
23130 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
23140 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
23150 50 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20  P_TEMP_TRIGGER  
23160 20 20 31 34 20 20 20 2f 2a 20 54 72 69 67 67 65    14   /* Trigge
23170 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20  r Name    Table 
23180 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
23190 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
231a0 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20  _TEMP_VIEW      
231b0 20 31 35 20 20 20 2f 2a 20 56 69 65 77 20 4e 61   15   /* View Na
231c0 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  me       NULL   
231d0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
231e0 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
231f0 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20 20  TRIGGER         
23200 31 36 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20  16   /* Trigger 
23210 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61  Name    Table Na
23220 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
23230 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56  ne SQLITE_DROP_V
23240 49 45 57 20 20 20 20 20 20 20 20 20 20 20 20 31  IEW            1
23250 37 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65  7   /* View Name
23260 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
23270 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
23280 65 20 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 20  e SQLITE_INSERT 
23290 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 38                18
232a0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
232b0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
232c0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
232d0 20 53 51 4c 49 54 45 5f 50 52 41 47 4d 41 20 20   SQLITE_PRAGMA  
232e0 20 20 20 20 20 20 20 20 20 20 20 20 20 31 39 20               19 
232f0 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65    /* Pragma Name
23300 20 20 20 20 20 31 73 74 20 61 72 67 20 6f 72 20       1st arg or 
23310 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20  NULL */.#define 
23320 53 51 4c 49 54 45 5f 52 45 41 44 20 20 20 20 20  SQLITE_READ     
23330 20 20 20 20 20 20 20 20 20 20 20 20 32 30 20 20              20  
23340 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
23350 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20      Column Name 
23360 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
23370 51 4c 49 54 45 5f 53 45 4c 45 43 54 20 20 20 20  QLITE_SELECT    
23380 20 20 20 20 20 20 20 20 20 20 20 32 31 20 20 20             21   
23390 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20  /* NULL         
233a0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
233b0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
233c0 4c 49 54 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e  LITE_TRANSACTION
233d0 20 20 20 20 20 20 20 20 20 20 32 32 20 20 20 2f            22   /
233e0 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20  * Operation     
233f0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
23400 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
23410 49 54 45 5f 55 50 44 41 54 45 20 20 20 20 20 20  ITE_UPDATE      
23420 20 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a           23   /*
23430 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
23440 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20   Column Name    
23450 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
23460 54 45 5f 41 54 54 41 43 48 20 20 20 20 20 20 20  TE_ATTACH       
23470 20 20 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20          24   /* 
23480 46 69 6c 65 6e 61 6d 65 20 20 20 20 20 20 20 20  Filename        
23490 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
234a0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
234b0 45 5f 44 45 54 41 43 48 20 20 20 20 20 20 20 20  E_DETACH        
234c0 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 44         25   /* D
234d0 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 4e  atabase Name   N
234e0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
234f0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
23500 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20 20 20 20  _ALTER_TABLE    
23510 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 44 61        26   /* Da
23520 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 54 61  tabase Name   Ta
23530 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
23540 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
23550 52 45 49 4e 44 45 58 20 20 20 20 20 20 20 20 20  REINDEX         
23560 20 20 20 20 20 32 37 20 20 20 2f 2a 20 49 6e 64       27   /* Ind
23570 65 78 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  ex Name      NUL
23580 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
23590 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
235a0 4e 41 4c 59 5a 45 20 20 20 20 20 20 20 20 20 20  NALYZE          
235b0 20 20 20 20 32 38 20 20 20 2f 2a 20 54 61 62 6c      28   /* Tabl
235c0 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
235d0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
235e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
235f0 45 41 54 45 5f 56 54 41 42 4c 45 20 20 20 20 20  EATE_VTABLE     
23600 20 20 20 32 39 20 20 20 2f 2a 20 54 61 62 6c 65     29   /* Table
23610 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c   Name      Modul
23620 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64  e Name     */.#d
23630 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
23640 50 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20  P_VTABLE        
23650 20 20 33 30 20 20 20 2f 2a 20 54 61 62 6c 65 20    30   /* Table 
23660 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65  Name      Module
23670 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65   Name     */.#de
23680 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e 43  fine SQLITE_FUNC
23690 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 20 20  TION            
236a0 20 33 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20   31   /* NULL   
236b0 20 20 20 20 20 20 20 20 20 46 75 6e 63 74 69 6f           Functio
236c0 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a 23 64 65 66  n Name   */.#def
236d0 69 6e 65 20 53 51 4c 49 54 45 5f 53 41 56 45 50  ine SQLITE_SAVEP
236e0 4f 49 4e 54 20 20 20 20 20 20 20 20 20 20 20 20  OINT            
236f0 33 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f  32   /* Operatio
23700 6e 20 20 20 20 20 20 20 53 61 76 65 70 6f 69 6e  n       Savepoin
23710 74 20 4e 61 6d 65 20 20 2a 2f 0a 23 64 65 66 69  t Name  */.#defi
23720 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50 59 20 20  ne SQLITE_COPY  
23730 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
23740 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72  0   /* No longer
23750 20 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20   used */../*.** 
23760 43 41 50 49 33 52 45 46 3a 20 54 72 61 63 69 6e  CAPI3REF: Tracin
23770 67 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20  g And Profiling 
23780 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  Functions.**.** 
23790 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
237a0 65 67 69 73 74 65 72 20 63 61 6c 6c 62 61 63 6b  egister callback
237b0 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20   functions that 
237c0 63 61 6e 20 62 65 20 75 73 65 64 20 66 6f 72 0a  can be used for.
237d0 2a 2a 20 74 72 61 63 69 6e 67 20 61 6e 64 20 70  ** tracing and p
237e0 72 6f 66 69 6c 69 6e 67 20 74 68 65 20 65 78 65  rofiling the exe
237f0 63 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74  cution of SQL st
23800 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  atements..**.** 
23810 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75  ^The callback fu
23820 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65  nction registere
23830 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74 72 61  d by sqlite3_tra
23840 63 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20  ce() is invoked 
23850 61 74 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74 69  at.** various ti
23860 6d 65 73 20 77 68 65 6e 20 61 6e 20 53 51 4c 20  mes when an SQL 
23870 73 74 61 74 65 6d 65 6e 74 20 69 73 20 62 65 69  statement is bei
23880 6e 67 20 72 75 6e 20 62 79 20 5b 73 71 6c 69 74  ng run by [sqlit
23890 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e  e3_step()]..** ^
238a0 54 68 65 20 73 71 6c 69 74 65 33 5f 74 72 61 63  The sqlite3_trac
238b0 65 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  e() callback is 
238c0 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 20 55  invoked with a U
238d0 54 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 6f  TF-8 rendering o
238e0 66 20 74 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61  f the.** SQL sta
238f0 74 65 6d 65 6e 74 20 74 65 78 74 20 61 73 20 74  tement text as t
23900 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66 69 72  he statement fir
23910 73 74 20 62 65 67 69 6e 73 20 65 78 65 63 75 74  st begins execut
23920 69 6e 67 2e 0a 2a 2a 20 5e 28 41 64 64 69 74 69  ing..** ^(Additi
23930 6f 6e 61 6c 20 73 71 6c 69 74 65 33 5f 74 72 61  onal sqlite3_tra
23940 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 73 20 6d  ce() callbacks m
23950 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 61 73  ight occur.** as
23960 20 65 61 63 68 20 74 72 69 67 67 65 72 65 64 20   each triggered 
23970 73 75 62 70 72 6f 67 72 61 6d 20 69 73 20 65 6e  subprogram is en
23980 74 65 72 65 64 2e 20 20 54 68 65 20 63 61 6c 6c  tered.  The call
23990 62 61 63 6b 73 20 66 6f 72 20 74 72 69 67 67 65  backs for trigge
239a0 72 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20  rs.** contain a 
239b0 55 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e  UTF-8 SQL commen
239c0 74 20 74 68 61 74 20 69 64 65 6e 74 69 66 69 65  t that identifie
239d0 73 20 74 68 65 20 74 72 69 67 67 65 72 2e 29 5e  s the trigger.)^
239e0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  .**.** The [SQLI
239f0 54 45 5f 54 52 41 43 45 5f 53 49 5a 45 5f 4c 49  TE_TRACE_SIZE_LI
23a00 4d 49 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  MIT] compile-tim
23a10 65 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20  e option can be 
23a20 75 73 65 64 20 74 6f 20 6c 69 6d 69 74 0a 2a 2a  used to limit.**
23a30 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 5b   the length of [
23a40 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 5d  bound parameter]
23a50 20 65 78 70 61 6e 73 69 6f 6e 20 69 6e 20 74 68   expansion in th
23a60 65 20 6f 75 74 70 75 74 20 6f 66 20 73 71 6c 69  e output of sqli
23a70 74 65 33 5f 74 72 61 63 65 28 29 2e 0a 2a 2a 0a  te3_trace()..**.
23a80 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b  ** ^The callback
23a90 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74   function regist
23aa0 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  ered by sqlite3_
23ab0 70 72 6f 66 69 6c 65 28 29 20 69 73 20 69 6e 76  profile() is inv
23ac0 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61 63 68 20  oked.** as each 
23ad0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 69  SQL statement fi
23ae0 6e 69 73 68 65 73 2e 20 20 5e 54 68 65 20 70 72  nishes.  ^The pr
23af0 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63  ofile callback c
23b00 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f  ontains.** the o
23b10 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e  riginal statemen
23b20 74 20 74 65 78 74 20 61 6e 64 20 61 6e 20 65 73  t text and an es
23b30 74 69 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63  timate of wall-c
23b40 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20  lock time.** of 
23b50 68 6f 77 20 6c 6f 6e 67 20 74 68 61 74 20 73 74  how long that st
23b60 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20  atement took to 
23b70 72 75 6e 2e 20 20 5e 54 68 65 20 70 72 6f 66 69  run.  ^The profi
23b80 6c 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74  le callback.** t
23b90 69 6d 65 20 69 73 20 69 6e 20 75 6e 69 74 73 20  ime is in units 
23ba0 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c 20  of nanoseconds, 
23bb0 68 6f 77 65 76 65 72 20 74 68 65 20 63 75 72 72  however the curr
23bc0 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ent implementati
23bd0 6f 6e 0a 2a 2a 20 69 73 20 6f 6e 6c 79 20 63 61  on.** is only ca
23be0 70 61 62 6c 65 20 6f 66 20 6d 69 6c 6c 69 73 65  pable of millise
23bf0 63 6f 6e 64 20 72 65 73 6f 6c 75 74 69 6f 6e 20  cond resolution 
23c00 73 6f 20 74 68 65 20 73 69 78 20 6c 65 61 73 74  so the six least
23c10 20 73 69 67 6e 69 66 69 63 61 6e 74 0a 2a 2a 20   significant.** 
23c20 64 69 67 69 74 73 20 69 6e 20 74 68 65 20 74 69  digits in the ti
23c30 6d 65 20 61 72 65 20 6d 65 61 6e 69 6e 67 6c 65  me are meaningle
23c40 73 73 2e 20 20 46 75 74 75 72 65 20 76 65 72 73  ss.  Future vers
23c50 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a  ions of SQLite.*
23c60 2a 20 6d 69 67 68 74 20 70 72 6f 76 69 64 65 20  * might provide 
23c70 67 72 65 61 74 65 72 20 72 65 73 6f 6c 75 74 69  greater resoluti
23c80 6f 6e 20 6f 6e 20 74 68 65 20 70 72 6f 66 69 6c  on on the profil
23c90 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20 20 54 68  er callback.  Th
23ca0 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 6f  e.** sqlite3_pro
23cb0 66 69 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20  file() function 
23cc0 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 65 78  is considered ex
23cd0 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69  perimental and i
23ce0 73 0a 2a 2a 20 73 75 62 6a 65 63 74 20 74 6f 20  s.** subject to 
23cf0 63 68 61 6e 67 65 20 69 6e 20 66 75 74 75 72 65  change in future
23d00 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
23d10 69 74 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ite..*/.SQLITE_A
23d20 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  PI void *sqlite3
23d30 5f 74 72 61 63 65 28 73 71 6c 69 74 65 33 2a 2c  _trace(sqlite3*,
23d40 20 76 6f 69 64 28 2a 78 54 72 61 63 65 29 28 76   void(*xTrace)(v
23d50 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  oid*,const char*
23d60 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54  ), void*);.SQLIT
23d70 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 45 58 50  E_API SQLITE_EXP
23d80 45 52 49 4d 45 4e 54 41 4c 20 76 6f 69 64 20 2a  ERIMENTAL void *
23d90 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28  sqlite3_profile(
23da0 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69  sqlite3*,.   voi
23db0 64 28 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f 69  d(*xProfile)(voi
23dc0 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73  d*,const char*,s
23dd0 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 2c 20  qlite3_uint64), 
23de0 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  void*);../*.** C
23df0 41 50 49 33 52 45 46 3a 20 51 75 65 72 79 20 50  API3REF: Query P
23e00 72 6f 67 72 65 73 73 20 43 61 6c 6c 62 61 63 6b  rogress Callback
23e10 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
23e20 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61  ite3_progress_ha
23e30 6e 64 6c 65 72 28 44 2c 4e 2c 58 2c 50 29 20 69  ndler(D,N,X,P) i
23e40 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20  nterface causes 
23e50 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  the callback.** 
23e60 66 75 6e 63 74 69 6f 6e 20 58 20 74 6f 20 62 65  function X to be
23e70 20 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 69   invoked periodi
23e80 63 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e  cally during lon
23e90 67 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20  g running calls 
23ea0 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  to.** [sqlite3_e
23eb0 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  xec()], [sqlite3
23ec0 5f 73 74 65 70 28 29 5d 20 61 6e 64 20 5b 73 71  _step()] and [sq
23ed0 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
23ee0 29 5d 20 66 6f 72 0a 2a 2a 20 64 61 74 61 62 61  )] for.** databa
23ef0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e  se connection D.
23f00 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 75 73 65    An example use
23f10 20 66 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74   for this.** int
23f20 65 72 66 61 63 65 20 69 73 20 74 6f 20 6b 65 65  erface is to kee
23f30 70 20 61 20 47 55 49 20 75 70 64 61 74 65 64 20  p a GUI updated 
23f40 64 75 72 69 6e 67 20 61 20 6c 61 72 67 65 20 71  during a large q
23f50 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  uery..**.** ^The
23f60 20 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20   parameter P is 
23f70 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 61  passed through a
23f80 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d  s the only param
23f90 65 74 65 72 20 74 6f 20 74 68 65 20 0a 2a 2a 20  eter to the .** 
23fa0 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
23fb0 6e 20 58 2e 20 20 5e 54 68 65 20 70 61 72 61 6d  n X.  ^The param
23fc0 65 74 65 72 20 4e 20 69 73 20 74 68 65 20 61 70  eter N is the ap
23fd0 70 72 6f 78 69 6d 61 74 65 20 6e 75 6d 62 65 72  proximate number
23fe0 20 6f 66 20 0a 2a 2a 20 5b 76 69 72 74 75 61 6c   of .** [virtual
23ff0 20 6d 61 63 68 69 6e 65 20 69 6e 73 74 72 75 63   machine instruc
24000 74 69 6f 6e 73 5d 20 74 68 61 74 20 61 72 65 20  tions] that are 
24010 65 76 61 6c 75 61 74 65 64 20 62 65 74 77 65 65  evaluated betwee
24020 6e 20 73 75 63 63 65 73 73 69 76 65 0a 2a 2a 20  n successive.** 
24030 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74  invocations of t
24040 68 65 20 63 61 6c 6c 62 61 63 6b 20 58 2e 20 20  he callback X.  
24050 5e 49 66 20 4e 20 69 73 20 6c 65 73 73 20 74 68  ^If N is less th
24060 61 6e 20 6f 6e 65 20 74 68 65 6e 20 74 68 65 20  an one then the 
24070 70 72 6f 67 72 65 73 73 0a 2a 2a 20 68 61 6e 64  progress.** hand
24080 6c 65 72 20 69 73 20 64 69 73 61 62 6c 65 64 2e  ler is disabled.
24090 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 61 20 73  .**.** ^Only a s
240a0 69 6e 67 6c 65 20 70 72 6f 67 72 65 73 73 20 68  ingle progress h
240b0 61 6e 64 6c 65 72 20 6d 61 79 20 62 65 20 64 65  andler may be de
240c0 66 69 6e 65 64 20 61 74 20 6f 6e 65 20 74 69 6d  fined at one tim
240d0 65 20 70 65 72 0a 2a 2a 20 5b 64 61 74 61 62 61  e per.** [databa
240e0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 3b 20  se connection]; 
240f0 73 65 74 74 69 6e 67 20 61 20 6e 65 77 20 70 72  setting a new pr
24100 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63  ogress handler c
24110 61 6e 63 65 6c 73 20 74 68 65 0a 2a 2a 20 6f 6c  ancels the.** ol
24120 64 20 6f 6e 65 2e 20 20 5e 53 65 74 74 69 6e 67  d one.  ^Setting
24130 20 70 61 72 61 6d 65 74 65 72 20 58 20 74 6f 20   parameter X to 
24140 4e 55 4c 4c 20 64 69 73 61 62 6c 65 73 20 74 68  NULL disables th
24150 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  e progress handl
24160 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 70 72 6f 67  er..** ^The prog
24170 72 65 73 73 20 68 61 6e 64 6c 65 72 20 69 73 20  ress handler is 
24180 61 6c 73 6f 20 64 69 73 61 62 6c 65 64 20 62 79  also disabled by
24190 20 73 65 74 74 69 6e 67 20 4e 20 74 6f 20 61 20   setting N to a 
241a0 76 61 6c 75 65 20 6c 65 73 73 0a 2a 2a 20 74 68  value less.** th
241b0 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  an 1..**.** ^If 
241c0 74 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c  the progress cal
241d0 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f  lback returns no
241e0 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65 72  n-zero, the oper
241f0 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65  ation is.** inte
24200 72 72 75 70 74 65 64 2e 20 20 54 68 69 73 20 66  rrupted.  This f
24210 65 61 74 75 72 65 20 63 61 6e 20 62 65 20 75 73  eature can be us
24220 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20  ed to implement 
24230 61 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62 75  a.** "Cancel" bu
24240 74 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20 70 72  tton on a GUI pr
24250 6f 67 72 65 73 73 20 64 69 61 6c 6f 67 20 62 6f  ogress dialog bo
24260 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 6f  x..**.** The pro
24270 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61  gress handler ca
24280 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20  llback must not 
24290 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74  do anything that
242a0 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20   will modify.** 
242b0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
242c0 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76  nection that inv
242d0 6f 6b 65 64 20 74 68 65 20 70 72 6f 67 72 65 73  oked the progres
242e0 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f  s handler..** No
242f0 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33  te that [sqlite3
24300 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61  _prepare_v2()] a
24310 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  nd [sqlite3_step
24320 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20  ()] both modify 
24330 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73  their.** databas
24340 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f  e connections fo
24350 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66  r the meaning of
24360 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69   "modify" in thi
24370 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a  s paragraph..**.
24380 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  */.SQLITE_API vo
24390 69 64 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72  id sqlite3_progr
243a0 65 73 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69  ess_handler(sqli
243b0 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a  te3*, int, int(*
243c0 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29  )(void*), void*)
243d0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
243e0 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77  F: Opening A New
243f0 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63   Database Connec
24400 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  tion.**.** ^Thes
24410 65 20 72 6f 75 74 69 6e 65 73 20 6f 70 65 6e 20  e routines open 
24420 61 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 61  an SQLite databa
24430 73 65 20 66 69 6c 65 20 61 73 20 73 70 65 63 69  se file as speci
24440 66 69 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20  fied by the .** 
24450 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e  filename argumen
24460 74 2e 20 5e 54 68 65 20 66 69 6c 65 6e 61 6d 65  t. ^The filename
24470 20 61 72 67 75 6d 65 6e 74 20 69 73 20 69 6e 74   argument is int
24480 65 72 70 72 65 74 65 64 20 61 73 20 55 54 46 2d  erpreted as UTF-
24490 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  8 for.** sqlite3
244a0 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69  _open() and sqli
244b0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 61 6e  te3_open_v2() an
244c0 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 74  d as UTF-16 in t
244d0 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 0a 2a  he native byte.*
244e0 2a 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c 69  * order for sqli
244f0 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20 5e 28  te3_open16(). ^(
24500 41 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  A [database conn
24510 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 69  ection] handle i
24520 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 74  s usually.** ret
24530 75 72 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c 20  urned in *ppDb, 
24540 65 76 65 6e 20 69 66 20 61 6e 20 65 72 72 6f 72  even if an error
24550 20 6f 63 63 75 72 73 2e 20 20 54 68 65 20 6f 6e   occurs.  The on
24560 6c 79 20 65 78 63 65 70 74 69 6f 6e 20 69 73 20  ly exception is 
24570 74 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69 74  that.** if SQLit
24580 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61  e is unable to a
24590 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74  llocate memory t
245a0 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c 69  o hold the [sqli
245b0 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20  te3] object,.** 
245c0 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20 77  a NULL will be w
245d0 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70 44  ritten into *ppD
245e0 62 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 70  b instead of a p
245f0 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73  ointer to the [s
24600 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63  qlite3].** objec
24610 74 2e 29 5e 20 5e 28 49 66 20 74 68 65 20 64 61  t.)^ ^(If the da
24620 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
24630 20 28 61 6e 64 2f 6f 72 20 63 72 65 61 74 65 64   (and/or created
24640 29 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2c 20  ) successfully, 
24650 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  then.** [SQLITE_
24660 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  OK] is returned.
24670 20 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20 5b    Otherwise an [
24680 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72  error code] is r
24690 65 74 75 72 6e 65 64 2e 29 5e 20 5e 54 68 65 0a  eturned.)^ ^The.
246a0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  ** [sqlite3_errm
246b0 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  sg()] or [sqlite
246c0 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 20 72 6f  3_errmsg16()] ro
246d0 75 74 69 6e 65 73 20 63 61 6e 20 62 65 20 75 73  utines can be us
246e0 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20  ed to obtain.** 
246f0 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75  an English langu
24700 61 67 65 20 64 65 73 63 72 69 70 74 69 6f 6e 20  age description 
24710 6f 66 20 74 68 65 20 65 72 72 6f 72 20 66 6f 6c  of the error fol
24720 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 75 72 65  lowing a failure
24730 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68   of any.** of th
24740 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  e sqlite3_open()
24750 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a   routines..**.**
24760 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e   ^The default en
24770 63 6f 64 69 6e 67 20 66 6f 72 20 74 68 65 20 64  coding for the d
24780 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20  atabase will be 
24790 55 54 46 2d 38 20 69 66 0a 2a 2a 20 73 71 6c 69  UTF-8 if.** sqli
247a0 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71  te3_open() or sq
247b0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
247c0 69 73 20 63 61 6c 6c 65 64 20 61 6e 64 0a 2a 2a  is called and.**
247d0 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e   UTF-16 in the n
247e0 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
247f0 20 69 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   if sqlite3_open
24800 31 36 28 29 20 69 73 20 75 73 65 64 2e 0a 2a 2a  16() is used..**
24810 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f 72 20 6e  .** Whether or n
24820 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75  ot an error occu
24830 72 73 20 77 68 65 6e 20 69 74 20 69 73 20 6f 70  rs when it is op
24840 65 6e 65 64 2c 20 72 65 73 6f 75 72 63 65 73 0a  ened, resources.
24850 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ** associated wi
24860 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  th the [database
24870 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e   connection] han
24880 64 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 72 65  dle should be re
24890 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20 70 61 73  leased by.** pas
248a0 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69  sing it to [sqli
248b0 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65  te3_close()] whe
248c0 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65  n it is no longe
248d0 72 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a  r required..**.*
248e0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 70  * The sqlite3_op
248f0 65 6e 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63  en_v2() interfac
24900 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c  e works like sql
24910 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65  ite3_open().** e
24920 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61 63  xcept that it ac
24930 63 65 70 74 73 20 74 77 6f 20 61 64 64 69 74 69  cepts two additi
24940 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65 72 73 20  onal parameters 
24950 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 63  for additional c
24960 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74  ontrol.** over t
24970 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20  he new database 
24980 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 28 54  connection.  ^(T
24990 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74  he flags paramet
249a0 65 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  er to.** sqlite3
249b0 5f 6f 70 65 6e 5f 76 32 28 29 20 63 61 6e 20 74  _open_v2() can t
249c0 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68  ake one of.** th
249d0 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65  e following thre
249e0 65 20 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f 6e  e values, option
249f0 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69  ally combined wi
24a00 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49  th the .** [SQLI
24a10 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d  TE_OPEN_NOMUTEX]
24a20 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46  , [SQLITE_OPEN_F
24a30 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49  ULLMUTEX], [SQLI
24a40 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41  TE_OPEN_SHAREDCA
24a50 43 48 45 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  CHE],.** [SQLITE
24a60 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43  _OPEN_PRIVATECAC
24a70 48 45 5d 2c 20 61 6e 64 2f 6f 72 20 5b 53 51 4c  HE], and/or [SQL
24a80 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c  ITE_OPEN_URI] fl
24a90 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c  ags:)^.**.** <dl
24aa0 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49  >.** ^(<dt>[SQLI
24ab0 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
24ac0 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  ]</dt>.** <dd>Th
24ad0 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
24ae0 65 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c  ened in read-onl
24af0 79 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20  y mode.  If the 
24b00 64 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f  database does no
24b10 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65 78 69  t.** already exi
24b20 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 20  st, an error is 
24b30 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e  returned.</dd>)^
24b40 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51  .**.** ^(<dt>[SQ
24b50 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
24b60 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ITE]</dt>.** <dd
24b70 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73  >The database is
24b80 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64   opened for read
24b90 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20  ing and writing 
24ba0 69 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20  if possible, or 
24bb0 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20  reading.** only 
24bc0 69 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 77  if the file is w
24bd0 72 69 74 65 20 70 72 6f 74 65 63 74 65 64 20 62  rite protected b
24be0 79 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20  y the operating 
24bf0 73 79 73 74 65 6d 2e 20 20 49 6e 20 65 69 74 68  system.  In eith
24c00 65 72 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 64  er.** case the d
24c10 61 74 61 62 61 73 65 20 6d 75 73 74 20 61 6c 72  atabase must alr
24c20 65 61 64 79 20 65 78 69 73 74 2c 20 6f 74 68 65  eady exist, othe
24c30 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20 69  rwise an error i
24c40 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e  s returned.</dd>
24c50 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b  )^.**.** ^(<dt>[
24c60 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
24c70 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45  WRITE] | [SQLITE
24c80 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64  _OPEN_CREATE]</d
24c90 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61  t>.** <dd>The da
24ca0 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
24cb0 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64   for reading and
24cc0 20 77 72 69 74 69 6e 67 2c 20 61 6e 64 20 69 73   writing, and is
24cd0 20 63 72 65 61 74 65 64 20 69 66 0a 2a 2a 20 69   created if.** i
24ce0 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61  t does not alrea
24cf0 64 79 20 65 78 69 73 74 2e 20 54 68 69 73 20 69  dy exist. This i
24d00 73 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 74  s the behavior t
24d10 68 61 74 20 69 73 20 61 6c 77 61 79 73 20 75 73  hat is always us
24d20 65 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  ed for.** sqlite
24d30 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c  3_open() and sql
24d40 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f  ite3_open16().</
24d50 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  dd>)^.** </dl>.*
24d60 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20  *.** If the 3rd 
24d70 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
24d80 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
24d90 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65  s not one of the
24da0 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73  .** combinations
24db0 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f 70 74   shown above opt
24dc0 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64  ionally combined
24dd0 20 77 69 74 68 20 6f 74 68 65 72 0a 2a 2a 20 5b   with other.** [
24de0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
24df0 4f 4e 4c 59 20 7c 20 53 51 4c 49 54 45 5f 4f 50  ONLY | SQLITE_OP
24e00 45 4e 5f 2a 20 62 69 74 73 5d 0a 2a 2a 20 74 68  EN_* bits].** th
24e10 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
24e20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
24e30 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53 51 4c  .** ^If the [SQL
24e40 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58  ITE_OPEN_NOMUTEX
24e50 5d 20 66 6c 61 67 20 69 73 20 73 65 74 2c 20 74  ] flag is set, t
24e60 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
24e70 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f   connection.** o
24e80 70 65 6e 73 20 69 6e 20 74 68 65 20 6d 75 6c 74  pens in the mult
24e90 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61 64  i-thread [thread
24ea0 69 6e 67 20 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e  ing mode] as lon
24eb0 67 20 61 73 20 74 68 65 20 73 69 6e 67 6c 65 2d  g as the single-
24ec0 74 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 20 68  thread.** mode h
24ed0 61 73 20 6e 6f 74 20 62 65 65 6e 20 73 65 74 20  as not been set 
24ee0 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  at compile-time 
24ef0 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 20 20  or start-time.  
24f00 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ^If the.** [SQLI
24f10 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45  TE_OPEN_FULLMUTE
24f20 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20 74  X] flag is set t
24f30 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
24f40 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e   connection open
24f50 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73 65 72 69  s.** in the seri
24f60 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e  alized [threadin
24f70 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 20 73  g mode] unless s
24f80 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 77 61 73  ingle-thread was
24f90 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73  .** previously s
24fa0 65 6c 65 63 74 65 64 20 61 74 20 63 6f 6d 70 69  elected at compi
24fb0 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74  le-time or start
24fc0 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b  -time..** ^The [
24fd0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52  SQLITE_OPEN_SHAR
24fe0 45 44 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61  EDCACHE] flag ca
24ff0 75 73 65 73 20 74 68 65 20 64 61 74 61 62 61 73  uses the databas
25000 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20  e connection to 
25010 62 65 0a 2a 2a 20 65 6c 69 67 69 62 6c 65 20 74  be.** eligible t
25020 6f 20 75 73 65 20 5b 73 68 61 72 65 64 20 63 61  o use [shared ca
25030 63 68 65 20 6d 6f 64 65 5d 2c 20 72 65 67 61 72  che mode], regar
25040 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72  dless of whether
25050 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 0a 2a   or not shared.*
25060 2a 20 63 61 63 68 65 20 69 73 20 65 6e 61 62 6c  * cache is enabl
25070 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
25080 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f  3_enable_shared_
25090 63 61 63 68 65 28 29 5d 2e 20 20 5e 54 68 65 0a  cache()].  ^The.
250a0 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
250b0 50 52 49 56 41 54 45 43 41 43 48 45 5d 20 66 6c  PRIVATECACHE] fl
250c0 61 67 20 63 61 75 73 65 73 20 74 68 65 20 64 61  ag causes the da
250d0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
250e0 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72 74  n to not.** part
250f0 69 63 69 70 61 74 65 20 69 6e 20 5b 73 68 61 72  icipate in [shar
25100 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 20 65  ed cache mode] e
25110 76 65 6e 20 69 66 20 69 74 20 69 73 20 65 6e 61  ven if it is ena
25120 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  bled..**.** ^The
25130 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
25140 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65  r to sqlite3_ope
25150 6e 5f 76 32 28 29 20 69 73 20 74 68 65 20 6e 61  n_v2() is the na
25160 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71  me of the.** [sq
25170 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
25180 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 74  t that defines t
25190 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  he operating sys
251a0 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68  tem interface th
251b0 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64 61  at.** the new da
251c0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
251d0 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 5e  n should use.  ^
251e0 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  If the fourth pa
251f0 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61 20  rameter is.** a 
25200 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65  NULL pointer the
25210 6e 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73  n the default [s
25220 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
25230 63 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a  ct is used..**.*
25240 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61  * ^If the filena
25250 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22  me is ":memory:"
25260 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65  , then a private
25270 2c 20 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d  , temporary in-m
25280 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 0a 2a  emory database.*
25290 2a 20 69 73 20 63 72 65 61 74 65 64 20 66 6f 72  * is created for
252a0 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e   the connection.
252b0 20 20 5e 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72    ^This in-memor
252c0 79 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20  y database will 
252d0 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74  vanish when.** t
252e0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
252f0 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64  ection is closed
25300 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f  .  Future versio
25310 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67  ns of SQLite mig
25320 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f  ht.** make use o
25330 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 70 65  f additional spe
25340 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74  cial filenames t
25350 68 61 74 20 62 65 67 69 6e 20 77 69 74 68 20 74  hat begin with t
25360 68 65 20 22 3a 22 20 63 68 61 72 61 63 74 65 72  he ":" character
25370 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65 63 6f 6d  ..** It is recom
25380 6d 65 6e 64 65 64 20 74 68 61 74 20 77 68 65 6e  mended that when
25390 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65   a database file
253a0 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79 20 64 6f  name actually do
253b0 65 73 20 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a  es begin with.**
253c0 20 61 20 22 3a 22 20 63 68 61 72 61 63 74 65 72   a ":" character
253d0 20 79 6f 75 20 73 68 6f 75 6c 64 20 70 72 65 66   you should pref
253e0 69 78 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  ix the filename 
253f0 77 69 74 68 20 61 20 70 61 74 68 6e 61 6d 65 20  with a pathname 
25400 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20  such as.** "./" 
25410 74 6f 20 61 76 6f 69 64 20 61 6d 62 69 67 75 69  to avoid ambigui
25420 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ty..**.** ^If th
25430 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e  e filename is an
25440 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 74   empty string, t
25450 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74  hen a private, t
25460 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64  emporary.** on-d
25470 69 73 6b 20 64 61 74 61 62 61 73 65 20 77 69 6c  isk database wil
25480 6c 20 62 65 20 63 72 65 61 74 65 64 2e 20 20 5e  l be created.  ^
25490 54 68 69 73 20 70 72 69 76 61 74 65 20 64 61 74  This private dat
254a0 61 62 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a  abase will be.**
254b0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64   automatically d
254c0 65 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e 20 61  eleted as soon a
254d0 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  s the database c
254e0 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f  onnection is clo
254f0 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49  sed..**.** [[URI
25500 20 66 69 6c 65 6e 61 6d 65 73 20 69 6e 20 73 71   filenames in sq
25510 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 5d 20 3c  lite3_open()]] <
25520 68 33 3e 55 52 49 20 46 69 6c 65 6e 61 6d 65 73  h3>URI Filenames
25530 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  </h3>.**.** ^If 
25540 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 5d 20 69  [URI filename] i
25550 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73  nterpretation is
25560 20 65 6e 61 62 6c 65 64 2c 20 61 6e 64 20 74 68   enabled, and th
25570 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d  e filename argum
25580 65 6e 74 0a 2a 2a 20 62 65 67 69 6e 73 20 77 69  ent.** begins wi
25590 74 68 20 22 66 69 6c 65 3a 22 2c 20 74 68 65 6e  th "file:", then
255a0 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73   the filename is
255b0 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
255c0 61 20 55 52 49 2e 20 5e 55 52 49 0a 2a 2a 20 66  a URI. ^URI.** f
255d0 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65  ilename interpre
255e0 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65  tation is enable
255f0 64 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45  d if the [SQLITE
25600 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20  _OPEN_URI] flag 
25610 69 73 0a 2a 2a 20 73 65 74 20 69 6e 20 74 68 65  is.** set in the
25620 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
25630 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
25640 5f 76 32 28 29 2c 20 6f 72 20 69 66 20 69 74 20  _v2(), or if it 
25650 68 61 73 0a 2a 2a 20 62 65 65 6e 20 65 6e 61 62  has.** been enab
25660 6c 65 64 20 67 6c 6f 62 61 6c 6c 79 20 75 73 69  led globally usi
25670 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43  ng the [SQLITE_C
25680 4f 4e 46 49 47 5f 55 52 49 5d 20 6f 70 74 69 6f  ONFIG_URI] optio
25690 6e 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 73  n with the.** [s
256a0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
256b0 20 6d 65 74 68 6f 64 20 6f 72 20 62 79 20 74 68   method or by th
256c0 65 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52  e [SQLITE_USE_UR
256d0 49 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  I] compile-time 
256e0 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 41 73 20 6f 66  option..** As of
256f0 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
25700 33 2e 37 2e 37 2c 20 55 52 49 20 66 69 6c 65 6e  3.7.7, URI filen
25710 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61 74 69  ame interpretati
25720 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 66 66  on is turned off
25730 0a 2a 2a 20 62 79 20 64 65 66 61 75 6c 74 2c 20  .** by default, 
25740 62 75 74 20 66 75 74 75 72 65 20 72 65 6c 65 61  but future relea
25750 73 65 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69  ses of SQLite mi
25760 67 68 74 20 65 6e 61 62 6c 65 20 55 52 49 20 66  ght enable URI f
25770 69 6c 65 6e 61 6d 65 0a 2a 2a 20 69 6e 74 65 72  ilename.** inter
25780 70 72 65 74 61 74 69 6f 6e 20 62 79 20 64 65 66  pretation by def
25790 61 75 6c 74 2e 20 20 53 65 65 20 22 5b 55 52 49  ault.  See "[URI
257a0 20 66 69 6c 65 6e 61 6d 65 73 5d 22 20 66 6f 72   filenames]" for
257b0 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69   additional.** i
257c0 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  nformation..**.*
257d0 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20  * URI filenames 
257e0 61 72 65 20 70 61 72 73 65 64 20 61 63 63 6f 72  are parsed accor
257f0 64 69 6e 67 20 74 6f 20 52 46 43 20 33 39 38 36  ding to RFC 3986
25800 2e 20 5e 49 66 20 74 68 65 20 55 52 49 20 63 6f  . ^If the URI co
25810 6e 74 61 69 6e 73 20 61 6e 0a 2a 2a 20 61 75 74  ntains an.** aut
25820 68 6f 72 69 74 79 2c 20 74 68 65 6e 20 69 74 20  hority, then it 
25830 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61  must be either a
25840 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f  n empty string o
25850 72 20 74 68 65 20 73 74 72 69 6e 67 20 0a 2a 2a  r the string .**
25860 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2e 20 5e 49   "localhost". ^I
25870 66 20 74 68 65 20 61 75 74 68 6f 72 69 74 79 20  f the authority 
25880 69 73 20 6e 6f 74 20 61 6e 20 65 6d 70 74 79 20  is not an empty 
25890 73 74 72 69 6e 67 20 6f 72 20 22 6c 6f 63 61 6c  string or "local
258a0 68 6f 73 74 22 2c 20 61 6e 20 0a 2a 2a 20 65 72  host", an .** er
258b0 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 20  ror is returned 
258c0 74 6f 20 74 68 65 20 63 61 6c 6c 65 72 2e 20 5e  to the caller. ^
258d0 54 68 65 20 66 72 61 67 6d 65 6e 74 20 63 6f 6d  The fragment com
258e0 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 2c  ponent of a URI,
258f0 20 69 66 20 0a 2a 2a 20 70 72 65 73 65 6e 74 2c   if .** present,
25900 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a   is ignored..**.
25910 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20  ** ^SQLite uses 
25920 74 68 65 20 70 61 74 68 20 63 6f 6d 70 6f 6e 65  the path compone
25930 6e 74 20 6f 66 20 74 68 65 20 55 52 49 20 61 73  nt of the URI as
25940 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
25950 20 64 69 73 6b 20 66 69 6c 65 0a 2a 2a 20 77 68   disk file.** wh
25960 69 63 68 20 63 6f 6e 74 61 69 6e 73 20 74 68 65  ich contains the
25970 20 64 61 74 61 62 61 73 65 2e 20 5e 49 66 20 74   database. ^If t
25980 68 65 20 70 61 74 68 20 62 65 67 69 6e 73 20 77  he path begins w
25990 69 74 68 20 61 20 27 2f 27 20 63 68 61 72 61 63  ith a '/' charac
259a0 74 65 72 2c 20 0a 2a 2a 20 74 68 65 6e 20 69 74  ter, .** then it
259b0 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20   is interpreted 
259c0 61 73 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70  as an absolute p
259d0 61 74 68 2e 20 5e 49 66 20 74 68 65 20 70 61 74  ath. ^If the pat
259e0 68 20 64 6f 65 73 20 6e 6f 74 20 62 65 67 69 6e  h does not begin
259f0 20 0a 2a 2a 20 77 69 74 68 20 61 20 27 2f 27 20   .** with a '/' 
25a00 28 6d 65 61 6e 69 6e 67 20 74 68 61 74 20 74 68  (meaning that th
25a10 65 20 61 75 74 68 6f 72 69 74 79 20 73 65 63 74  e authority sect
25a20 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64 20 66  ion is omitted f
25a30 72 6f 6d 20 74 68 65 20 55 52 49 29 0a 2a 2a 20  rom the URI).** 
25a40 74 68 65 6e 20 74 68 65 20 70 61 74 68 20 69 73  then the path is
25a50 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
25a60 61 20 72 65 6c 61 74 69 76 65 20 70 61 74 68 2e  a relative path.
25a70 20 0a 2a 2a 20 5e 4f 6e 20 77 69 6e 64 6f 77 73   .** ^On windows
25a80 2c 20 74 68 65 20 66 69 72 73 74 20 63 6f 6d 70  , the first comp
25a90 6f 6e 65 6e 74 20 6f 66 20 61 6e 20 61 62 73 6f  onent of an abso
25aa0 6c 75 74 65 20 70 61 74 68 20 0a 2a 2a 20 69 73  lute path .** is
25ab0 20 61 20 64 72 69 76 65 20 73 70 65 63 69 66 69   a drive specifi
25ac0 63 61 74 69 6f 6e 20 28 65 2e 67 2e 20 22 43 3a  cation (e.g. "C:
25ad0 22 29 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72 65  ")..**.** [[core
25ae0 20 55 52 49 20 71 75 65 72 79 20 70 61 72 61 6d   URI query param
25af0 65 74 65 72 73 5d 5d 0a 2a 2a 20 54 68 65 20 71  eters]].** The q
25b00 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f  uery component o
25b10 66 20 61 20 55 52 49 20 6d 61 79 20 63 6f 6e 74  f a URI may cont
25b20 61 69 6e 20 70 61 72 61 6d 65 74 65 72 73 20 74  ain parameters t
25b30 68 61 74 20 61 72 65 20 69 6e 74 65 72 70 72 65  hat are interpre
25b40 74 65 64 0a 2a 2a 20 65 69 74 68 65 72 20 62 79  ted.** either by
25b50 20 53 51 4c 69 74 65 20 69 74 73 65 6c 66 2c 20   SQLite itself, 
25b60 6f 72 20 62 79 20 61 20 5b 56 46 53 20 7c 20 63  or by a [VFS | c
25b70 75 73 74 6f 6d 20 56 46 53 20 69 6d 70 6c 65 6d  ustom VFS implem
25b80 65 6e 74 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 53 51  entation]..** SQ
25b90 4c 69 74 65 20 69 6e 74 65 72 70 72 65 74 73 20  Lite interprets 
25ba0 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68  the following th
25bb0 72 65 65 20 71 75 65 72 79 20 70 61 72 61 6d 65  ree query parame
25bc0 74 65 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ters:.**.** <ul>
25bd0 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 76 66  .**   <li> <b>vf
25be0 73 3c 2f 62 3e 3a 20 5e 54 68 65 20 22 76 66 73  s</b>: ^The "vfs
25bf0 22 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  " parameter may 
25c00 62 65 20 75 73 65 64 20 74 6f 20 73 70 65 63 69  be used to speci
25c10 66 79 20 74 68 65 20 6e 61 6d 65 20 6f 66 0a 2a  fy the name of.*
25c20 2a 20 20 20 20 20 61 20 56 46 53 20 6f 62 6a 65  *     a VFS obje
25c30 63 74 20 74 68 61 74 20 70 72 6f 76 69 64 65 73  ct that provides
25c40 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73   the operating s
25c50 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20  ystem interface 
25c60 74 68 61 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 20  that should.**  
25c70 20 20 20 62 65 20 75 73 65 64 20 74 6f 20 61 63     be used to ac
25c80 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61 73  cess the databas
25c90 65 20 66 69 6c 65 20 6f 6e 20 64 69 73 6b 2e 20  e file on disk. 
25ca0 5e 49 66 20 74 68 69 73 20 6f 70 74 69 6f 6e 20  ^If this option 
25cb0 69 73 20 73 65 74 20 74 6f 0a 2a 2a 20 20 20 20  is set to.**    
25cc0 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
25cd0 20 74 68 65 20 64 65 66 61 75 6c 74 20 56 46 53   the default VFS
25ce0 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e   object is used.
25cf0 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61 6e 20   ^Specifying an 
25d00 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20 20 20 20 56  unknown.**     V
25d10 46 53 20 69 73 20 61 6e 20 65 72 72 6f 72 2e 20  FS is an error. 
25d20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ^If sqlite3_open
25d30 5f 76 32 28 29 20 69 73 20 75 73 65 64 20 61 6e  _v2() is used an
25d40 64 20 74 68 65 20 76 66 73 20 6f 70 74 69 6f 6e  d the vfs option
25d50 20 69 73 0a 2a 2a 20 20 20 20 20 70 72 65 73 65   is.**     prese
25d60 6e 74 2c 20 74 68 65 6e 20 74 68 65 20 56 46 53  nt, then the VFS
25d70 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68   specified by th
25d80 65 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 70  e option takes p
25d90 72 65 63 65 64 65 6e 63 65 20 6f 76 65 72 0a 2a  recedence over.*
25da0 2a 20 20 20 20 20 74 68 65 20 76 61 6c 75 65 20  *     the value 
25db0 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66 6f  passed as the fo
25dc0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
25dd0 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
25de0 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69  2()..**.**   <li
25df0 3e 20 3c 62 3e 6d 6f 64 65 3c 2f 62 3e 3a 20 5e  > <b>mode</b>: ^
25e00 28 54 68 65 20 6d 6f 64 65 20 70 61 72 61 6d 65  (The mode parame
25e10 74 65 72 20 6d 61 79 20 62 65 20 73 65 74 20 74  ter may be set t
25e20 6f 20 65 69 74 68 65 72 20 22 72 6f 22 2c 20 22  o either "ro", "
25e30 72 77 22 2c 0a 2a 2a 20 20 20 20 20 22 72 77 63  rw",.**     "rwc
25e40 22 2c 20 6f 72 20 22 6d 65 6d 6f 72 79 22 2e 20  ", or "memory". 
25e50 41 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 73 65  Attempting to se
25e60 74 20 69 74 20 74 6f 20 61 6e 79 20 6f 74 68 65  t it to any othe
25e70 72 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 20 20  r value is.**   
25e80 20 20 61 6e 20 65 72 72 6f 72 29 5e 2e 20 0a 2a    an error)^. .*
25e90 2a 20 20 20 20 20 5e 49 66 20 22 72 6f 22 20 69  *     ^If "ro" i
25ea0 73 20 73 70 65 63 69 66 69 65 64 2c 20 74 68 65  s specified, the
25eb0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  n the database i
25ec0 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61  s opened for rea
25ed0 64 2d 6f 6e 6c 79 20 0a 2a 2a 20 20 20 20 20 61  d-only .**     a
25ee0 63 63 65 73 73 2c 20 6a 75 73 74 20 61 73 20 69  ccess, just as i
25ef0 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  f the [SQLITE_OP
25f00 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20 66 6c 61  EN_READONLY] fla
25f10 67 20 68 61 64 20 62 65 65 6e 20 73 65 74 20 69  g had been set i
25f20 6e 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 74 68  n the .**     th
25f30 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ird argument to 
25f40 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
25f50 29 2e 20 5e 49 66 20 74 68 65 20 6d 6f 64 65 20  ). ^If the mode 
25f60 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f  option is set to
25f70 20 0a 2a 2a 20 20 20 20 20 22 72 77 22 2c 20 74   .**     "rw", t
25f80 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
25f90 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72   is opened for r
25fa0 65 61 64 2d 77 72 69 74 65 20 28 62 75 74 20 6e  ead-write (but n
25fb0 6f 74 20 63 72 65 61 74 65 29 20 0a 2a 2a 20 20  ot create) .**  
25fc0 20 20 20 61 63 63 65 73 73 2c 20 61 73 20 69 66     access, as if
25fd0 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41   SQLITE_OPEN_REA
25fe0 44 57 52 49 54 45 20 28 62 75 74 20 6e 6f 74 20  DWRITE (but not 
25ff0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
26000 54 45 29 20 68 61 64 20 0a 2a 2a 20 20 20 20 20  TE) had .**     
26010 62 65 65 6e 20 73 65 74 2e 20 5e 56 61 6c 75 65  been set. ^Value
26020 20 22 72 77 63 22 20 69 73 20 65 71 75 69 76 61   "rwc" is equiva
26030 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20  lent to setting 
26040 62 6f 74 68 20 0a 2a 2a 20 20 20 20 20 53 51 4c  both .**     SQL
26050 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
26060 54 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 4f 50  TE and SQLITE_OP
26070 45 4e 5f 43 52 45 41 54 45 2e 20 20 5e 49 66 20  EN_CREATE.  ^If 
26080 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20  the mode option 
26090 69 73 0a 2a 2a 20 20 20 20 20 73 65 74 20 74 6f  is.**     set to
260a0 20 22 6d 65 6d 6f 72 79 22 20 74 68 65 6e 20 61   "memory" then a
260b0 20 70 75 72 65 20 5b 69 6e 2d 6d 65 6d 6f 72 79   pure [in-memory
260c0 20 64 61 74 61 62 61 73 65 5d 20 74 68 61 74 20   database] that 
260d0 6e 65 76 65 72 20 72 65 61 64 73 0a 2a 2a 20 20  never reads.**  
260e0 20 20 20 6f 72 20 77 72 69 74 65 73 20 66 72 6f     or writes fro
260f0 6d 20 64 69 73 6b 20 69 73 20 75 73 65 64 2e 20  m disk is used. 
26100 5e 49 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20  ^It is an error 
26110 74 6f 20 73 70 65 63 69 66 79 20 61 20 76 61 6c  to specify a val
26120 75 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20 74 68  ue for.**     th
26130 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 72  e mode parameter
26140 20 74 68 61 74 20 69 73 20 6c 65 73 73 20 72 65   that is less re
26150 73 74 72 69 63 74 69 76 65 20 74 68 61 6e 20 74  strictive than t
26160 68 61 74 20 73 70 65 63 69 66 69 65 64 20 62 79  hat specified by
26170 0a 2a 2a 20 20 20 20 20 74 68 65 20 66 6c 61 67  .**     the flag
26180 73 20 70 61 73 73 65 64 20 69 6e 20 74 68 65 20  s passed in the 
26190 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
261a0 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
261b0 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c  v2()..**.**   <l
261c0 69 3e 20 3c 62 3e 63 61 63 68 65 3c 2f 62 3e 3a  i> <b>cache</b>:
261d0 20 5e 54 68 65 20 63 61 63 68 65 20 70 61 72 61   ^The cache para
261e0 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73 65 74  meter may be set
261f0 20 74 6f 20 65 69 74 68 65 72 20 22 73 68 61 72   to either "shar
26200 65 64 22 20 6f 72 0a 2a 2a 20 20 20 20 20 22 70  ed" or.**     "p
26210 72 69 76 61 74 65 22 2e 20 5e 53 65 74 74 69 6e  rivate". ^Settin
26220 67 20 69 74 20 74 6f 20 22 73 68 61 72 65 64 22  g it to "shared"
26230 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74   is equivalent t
26240 6f 20 73 65 74 74 69 6e 67 20 74 68 65 0a 2a 2a  o setting the.**
26250 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e       SQLITE_OPEN
26260 5f 53 48 41 52 45 44 43 41 43 48 45 20 62 69 74  _SHAREDCACHE bit
26270 20 69 6e 20 74 68 65 20 66 6c 61 67 73 20 61 72   in the flags ar
26280 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 74 6f  gument passed to
26290 0a 2a 2a 20 20 20 20 20 73 71 6c 69 74 65 33 5f  .**     sqlite3_
262a0 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 53 65 74 74  open_v2(). ^Sett
262b0 69 6e 67 20 74 68 65 20 63 61 63 68 65 20 70 61  ing the cache pa
262c0 72 61 6d 65 74 65 72 20 74 6f 20 22 70 72 69 76  rameter to "priv
262d0 61 74 65 22 20 69 73 20 0a 2a 2a 20 20 20 20 20  ate" is .**     
262e0 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65  equivalent to se
262f0 74 74 69 6e 67 20 74 68 65 20 53 51 4c 49 54 45  tting the SQLITE
26300 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43  _OPEN_PRIVATECAC
26310 48 45 20 62 69 74 2e 0a 2a 2a 20 20 20 20 20 5e  HE bit..**     ^
26320 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  If sqlite3_open_
26330 76 32 28 29 20 69 73 20 75 73 65 64 20 61 6e 64  v2() is used and
26340 20 74 68 65 20 22 63 61 63 68 65 22 20 70 61 72   the "cache" par
26350 61 6d 65 74 65 72 20 69 73 20 70 72 65 73 65 6e  ameter is presen
26360 74 20 69 6e 0a 2a 2a 20 20 20 20 20 61 20 55 52  t in.**     a UR
26370 49 20 66 69 6c 65 6e 61 6d 65 2c 20 69 74 73 20  I filename, its 
26380 76 61 6c 75 65 20 6f 76 65 72 72 69 64 65 73 20  value overrides 
26390 61 6e 79 20 62 65 68 61 76 69 6f 72 20 72 65 71  any behavior req
263a0 75 65 73 74 65 64 20 62 79 20 73 65 74 74 69 6e  uested by settin
263b0 67 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f  g.**     SQLITE_
263c0 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48  OPEN_PRIVATECACH
263d0 45 20 6f 72 20 53 51 4c 49 54 45 5f 4f 50 45 4e  E or SQLITE_OPEN
263e0 5f 53 48 41 52 45 44 43 41 43 48 45 20 66 6c 61  _SHAREDCACHE fla
263f0 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  g..** </ul>.**.*
26400 2a 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61 6e  * ^Specifying an
26410 20 75 6e 6b 6e 6f 77 6e 20 70 61 72 61 6d 65 74   unknown paramet
26420 65 72 20 69 6e 20 74 68 65 20 71 75 65 72 79 20  er in the query 
26430 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55  component of a U
26440 52 49 20 69 73 20 6e 6f 74 20 61 6e 0a 2a 2a 20  RI is not an.** 
26450 65 72 72 6f 72 2e 20 20 46 75 74 75 72 65 20 76  error.  Future v
26460 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
26470 65 20 6d 69 67 68 74 20 75 6e 64 65 72 73 74 61  e might understa
26480 6e 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 71 75  nd additional qu
26490 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ery.** parameter
264a0 73 2e 20 20 53 65 65 20 22 5b 71 75 65 72 79 20  s.  See "[query 
264b0 70 61 72 61 6d 65 74 65 72 73 20 77 69 74 68 20  parameters with 
264c0 73 70 65 63 69 61 6c 20 6d 65 61 6e 69 6e 67 20  special meaning 
264d0 74 6f 20 53 51 4c 69 74 65 5d 22 20 66 6f 72 0a  to SQLite]" for.
264e0 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e  ** additional in
264f0 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  formation..**.**
26500 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 20   [[URI filename 
26510 65 78 61 6d 70 6c 65 73 5d 5d 20 3c 68 33 3e 55  examples]] <h3>U
26520 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d  RI filename exam
26530 70 6c 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20  ples</h3>.**.** 
26540 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31  <table border="1
26550 22 20 61 6c 69 67 6e 3d 63 65 6e 74 65 72 20 63  " align=center c
26560 65 6c 6c 70 61 64 64 69 6e 67 3d 35 3e 0a 2a 2a  ellpadding=5>.**
26570 20 3c 74 72 3e 3c 74 68 3e 20 55 52 49 20 66 69   <tr><th> URI fi
26580 6c 65 6e 61 6d 65 73 20 3c 74 68 3e 20 52 65 73  lenames <th> Res
26590 75 6c 74 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  ults.** <tr><td>
265a0 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 20 3c 74   file:data.db <t
265b0 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  d> .**          
265c0 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20 22 64  Open the file "d
265d0 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20 63  ata.db" in the c
265e0 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79  urrent directory
265f0 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  ..** <tr><td> fi
26600 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61  le:/home/fred/da
26610 74 61 2e 64 62 3c 62 72 3e 0a 2a 2a 20 20 20 20  ta.db<br>.**    
26620 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 68 6f        file:///ho
26630 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20  me/fred/data.db 
26640 3c 62 72 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20  <br> .**        
26650 20 20 66 69 6c 65 3a 2f 2f 6c 6f 63 61 6c 68 6f    file://localho
26660 73 74 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74  st/home/fred/dat
26670 61 2e 64 62 20 3c 62 72 3e 20 3c 74 64 3e 20 0a  a.db <br> <td> .
26680 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e  **          Open
26690 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
266a0 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  le "/home/fred/d
266b0 61 74 61 2e 64 62 22 2e 0a 2a 2a 20 3c 74 72 3e  ata.db"..** <tr>
266c0 3c 74 64 3e 20 66 69 6c 65 3a 2f 2f 64 61 72 6b  <td> file://dark
266d0 73 74 61 72 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  star/home/fred/d
266e0 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20  ata.db <td> .** 
266f0 20 20 20 20 20 20 20 20 20 41 6e 20 65 72 72 6f           An erro
26700 72 2e 20 22 64 61 72 6b 73 74 61 72 22 20 69 73  r. "darkstar" is
26710 20 6e 6f 74 20 61 20 72 65 63 6f 67 6e 69 7a 65   not a recognize
26720 64 20 61 75 74 68 6f 72 69 74 79 2e 0a 2a 2a 20  d authority..** 
26730 3c 74 72 3e 3c 74 64 20 73 74 79 6c 65 3d 22 77  <tr><td style="w
26740 68 69 74 65 2d 73 70 61 63 65 3a 6e 6f 77 72 61  hite-space:nowra
26750 70 22 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  p"> .**         
26760 20 66 69 6c 65 3a 2f 2f 2f 43 3a 2f 44 6f 63 75   file:///C:/Docu
26770 6d 65 6e 74 73 25 32 30 61 6e 64 25 32 30 53 65  ments%20and%20Se
26780 74 74 69 6e 67 73 2f 66 72 65 64 2f 44 65 73 6b  ttings/fred/Desk
26790 74 6f 70 2f 64 61 74 61 2e 64 62 0a 2a 2a 20 20  top/data.db.**  
267a0 20 20 20 3c 74 64 3e 20 57 69 6e 64 6f 77 73 20     <td> Windows 
267b0 6f 6e 6c 79 3a 20 4f 70 65 6e 20 74 68 65 20 66  only: Open the f
267c0 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 6f 6e  ile "data.db" on
267d0 20 66 72 65 64 27 73 20 64 65 73 6b 74 6f 70 20   fred's desktop 
267e0 6f 6e 20 64 72 69 76 65 0a 2a 2a 20 20 20 20 20  on drive.**     
267f0 20 20 20 20 20 43 3a 2e 20 4e 6f 74 65 20 74 68       C:. Note th
26800 61 74 20 74 68 65 20 25 32 30 20 65 73 63 61 70  at the %20 escap
26810 69 6e 67 20 69 6e 20 74 68 69 73 20 65 78 61 6d  ing in this exam
26820 70 6c 65 20 69 73 20 6e 6f 74 20 73 74 72 69 63  ple is not stric
26830 74 6c 79 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  tly .**         
26840 20 6e 65 63 65 73 73 61 72 79 20 2d 20 73 70 61   necessary - spa
26850 63 65 20 63 68 61 72 61 63 74 65 72 73 20 63 61  ce characters ca
26860 6e 20 62 65 20 75 73 65 64 20 6c 69 74 65 72 61  n be used litera
26870 6c 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  lly.**          
26880 69 6e 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73  in URI filenames
26890 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  ..** <tr><td> fi
268a0 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d  le:data.db?mode=
268b0 72 6f 26 63 61 63 68 65 3d 70 72 69 76 61 74 65  ro&cache=private
268c0 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20   <td> .**       
268d0 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 64 61     Open file "da
268e0 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20 63 75  ta.db" in the cu
268f0 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79 20  rrent directory 
26900 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 61 63  for read-only ac
26910 63 65 73 73 2e 0a 2a 2a 20 20 20 20 20 20 20 20  cess..**        
26920 20 20 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20    Regardless of 
26930 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73  whether or not s
26940 68 61 72 65 64 2d 63 61 63 68 65 20 6d 6f 64 65  hared-cache mode
26950 20 69 73 20 65 6e 61 62 6c 65 64 20 62 79 0a 2a   is enabled by.*
26960 2a 20 20 20 20 20 20 20 20 20 20 64 65 66 61 75  *          defau
26970 6c 74 2c 20 75 73 65 20 61 20 70 72 69 76 61 74  lt, use a privat
26980 65 20 63 61 63 68 65 2e 0a 2a 2a 20 3c 74 72 3e  e cache..** <tr>
26990 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f  <td> file:/home/
269a0 66 72 65 64 2f 64 61 74 61 2e 64 62 3f 76 66 73  fred/data.db?vfs
269b0 3d 75 6e 69 78 2d 6e 6f 6c 6f 63 6b 20 3c 74 64  =unix-nolock <td
269c0 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70  >.**          Op
269d0 65 6e 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66  en file "/home/f
269e0 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 20 55 73  red/data.db". Us
269f0 65 20 74 68 65 20 73 70 65 63 69 61 6c 20 56 46  e the special VF
26a00 53 20 22 75 6e 69 78 2d 6e 6f 6c 6f 63 6b 22 2e  S "unix-nolock".
26a10 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c  .** <tr><td> fil
26a20 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72  e:data.db?mode=r
26a30 65 61 64 6f 6e 6c 79 20 3c 74 64 3e 20 0a 2a 2a  eadonly <td> .**
26a40 20 20 20 20 20 20 20 20 20 20 41 6e 20 65 72 72            An err
26a50 6f 72 2e 20 22 72 65 61 64 6f 6e 6c 79 22 20 69  or. "readonly" i
26a60 73 20 6e 6f 74 20 61 20 76 61 6c 69 64 20 6f 70  s not a valid op
26a70 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 22 6d 6f  tion for the "mo
26a80 64 65 22 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  de" parameter..*
26a90 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 0a 2a 2a  * </table>.**.**
26aa0 20 5e 55 52 49 20 68 65 78 61 64 65 63 69 6d 61   ^URI hexadecima
26ab0 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 6e 63  l escape sequenc
26ac0 65 73 20 28 25 48 48 29 20 61 72 65 20 73 75 70  es (%HH) are sup
26ad0 70 6f 72 74 65 64 20 77 69 74 68 69 6e 20 74 68  ported within th
26ae0 65 20 70 61 74 68 20 61 6e 64 0a 2a 2a 20 71 75  e path and.** qu
26af0 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f  ery components o
26b00 66 20 61 20 55 52 49 2e 20 41 20 68 65 78 61 64  f a URI. A hexad
26b10 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65  ecimal escape se
26b20 71 75 65 6e 63 65 20 63 6f 6e 73 69 73 74 73 20  quence consists 
26b30 6f 66 20 61 0a 2a 2a 20 70 65 72 63 65 6e 74 20  of a.** percent 
26b40 73 69 67 6e 20 2d 20 22 25 22 20 2d 20 66 6f 6c  sign - "%" - fol
26b50 6c 6f 77 65 64 20 62 79 20 65 78 61 63 74 6c 79  lowed by exactly
26b60 20 74 77 6f 20 68 65 78 61 64 65 63 69 6d 61 6c   two hexadecimal
26b70 20 64 69 67 69 74 73 20 0a 2a 2a 20 73 70 65 63   digits .** spec
26b80 69 66 79 69 6e 67 20 61 6e 20 6f 63 74 65 74 20  ifying an octet 
26b90 76 61 6c 75 65 2e 20 5e 42 65 66 6f 72 65 20 74  value. ^Before t
26ba0 68 65 20 70 61 74 68 20 6f 72 20 71 75 65 72 79  he path or query
26bb0 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61   components of a
26bc0 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65  .** URI filename
26bd0 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64   are interpreted
26be0 2c 20 74 68 65 79 20 61 72 65 20 65 6e 63 6f 64  , they are encod
26bf0 65 64 20 75 73 69 6e 67 20 55 54 46 2d 38 20 61  ed using UTF-8 a
26c00 6e 64 20 61 6c 6c 20 0a 2a 2a 20 68 65 78 61 64  nd all .** hexad
26c10 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65  ecimal escape se
26c20 71 75 65 6e 63 65 73 20 72 65 70 6c 61 63 65 64  quences replaced
26c30 20 62 79 20 61 20 73 69 6e 67 6c 65 20 62 79 74   by a single byt
26c40 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  e containing the
26c50 0a 2a 2a 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  .** correspondin
26c60 67 20 6f 63 74 65 74 2e 20 49 66 20 74 68 69 73  g octet. If this
26c70 20 70 72 6f 63 65 73 73 20 67 65 6e 65 72 61 74   process generat
26c80 65 73 20 61 6e 20 69 6e 76 61 6c 69 64 20 55 54  es an invalid UT
26c90 46 2d 38 20 65 6e 63 6f 64 69 6e 67 2c 0a 2a 2a  F-8 encoding,.**
26ca0 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
26cb0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
26cc0 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e  * <b>Note to Win
26cd0 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20  dows users:</b> 
26ce0 20 54 68 65 20 65 6e 63 6f 64 69 6e 67 20 75 73   The encoding us
26cf0 65 64 20 66 6f 72 20 74 68 65 20 66 69 6c 65 6e  ed for the filen
26d00 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  ame argument.** 
26d10 6f 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  of sqlite3_open(
26d20 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70  ) and sqlite3_op
26d30 65 6e 5f 76 32 28 29 20 6d 75 73 74 20 62 65 20  en_v2() must be 
26d40 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65  UTF-8, not whate
26d50 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20  ver.** codepage 
26d60 69 73 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66  is currently def
26d70 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73  ined.  Filenames
26d80 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65   containing inte
26d90 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61  rnational.** cha
26da0 72 61 63 74 65 72 73 20 6d 75 73 74 20 62 65 20  racters must be 
26db0 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 55 54 46  converted to UTF
26dc0 2d 38 20 70 72 69 6f 72 20 74 6f 20 70 61 73 73  -8 prior to pass
26dd0 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a  ing them into.**
26de0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
26df0 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
26e00 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e  v2()..**.** <b>N
26e10 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 52  ote to Windows R
26e20 75 6e 74 69 6d 65 20 75 73 65 72 73 3a 3c 2f 62  untime users:</b
26e30 3e 20 20 54 68 65 20 74 65 6d 70 6f 72 61 72 79  >  The temporary
26e40 20 64 69 72 65 63 74 6f 72 79 20 6d 75 73 74 20   directory must 
26e50 62 65 20 73 65 74 0a 2a 2a 20 70 72 69 6f 72 20  be set.** prior 
26e60 74 6f 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69 74  to calling sqlit
26e70 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c  e3_open() or sql
26e80 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20  ite3_open_v2(). 
26e90 20 4f 74 68 65 72 77 69 73 65 2c 20 76 61 72 69   Otherwise, vari
26ea0 6f 75 73 0a 2a 2a 20 66 65 61 74 75 72 65 73 20  ous.** features 
26eb0 74 68 61 74 20 72 65 71 75 69 72 65 20 74 68 65  that require the
26ec0 20 75 73 65 20 6f 66 20 74 65 6d 70 6f 72 61 72   use of temporar
26ed0 79 20 66 69 6c 65 73 20 6d 61 79 20 66 61 69 6c  y files may fail
26ee0 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
26ef0 3a 20 5b 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f  : [sqlite3_temp_
26f00 64 69 72 65 63 74 6f 72 79 5d 0a 2a 2f 0a 53 51  directory].*/.SQ
26f10 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
26f20 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e  ite3_open(.  con
26f30 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d  st char *filenam
26f40 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  e,   /* Database
26f50 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38   filename (UTF-8
26f60 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a  ) */.  sqlite3 *
26f70 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f  *ppDb          /
26f80 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62  * OUT: SQLite db
26f90 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 53 51   handle */.);.SQ
26fa0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
26fb0 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20 20 63  ite3_open16(.  c
26fc0 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c 65 6e  onst void *filen
26fd0 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61  ame,   /* Databa
26fe0 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46  se filename (UTF
26ff0 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65  -16) */.  sqlite
27000 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20  3 **ppDb        
27010 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65    /* OUT: SQLite
27020 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b   db handle */.);
27030 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
27040 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
27050 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66  .  const char *f
27060 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61  ilename,   /* Da
27070 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
27080 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c  (UTF-8) */.  sql
27090 69 74 65 33 20 2a 2a 70 70 44 62 2c 20 20 20 20  ite3 **ppDb,    
270a0 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c       /* OUT: SQL
270b0 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f  ite db handle */
270c0 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 20 20  .  int flags,   
270d0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 6c             /* Fl
270e0 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  ags */.  const c
270f0 68 61 72 20 2a 7a 56 66 73 20 20 20 20 20 20 20  har *zVfs       
27100 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53 20   /* Name of VFS 
27110 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f  module to use */
27120 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
27130 52 45 46 3a 20 4f 62 74 61 69 6e 20 56 61 6c 75  REF: Obtain Valu
27140 65 73 20 46 6f 72 20 55 52 49 20 50 61 72 61 6d  es For URI Param
27150 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  eters.**.** Thes
27160 65 20 61 72 65 20 75 74 69 6c 69 74 79 20 72 6f  e are utility ro
27170 75 74 69 6e 65 73 2c 20 75 73 65 66 75 6c 20 74  utines, useful t
27180 6f 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  o VFS implementa
27190 74 69 6f 6e 73 2c 20 74 68 61 74 20 63 68 65 63  tions, that chec
271a0 6b 0a 2a 2a 20 74 6f 20 73 65 65 20 69 66 20 61  k.** to see if a
271b0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77   database file w
271c0 61 73 20 61 20 55 52 49 20 74 68 61 74 20 63 6f  as a URI that co
271d0 6e 74 61 69 6e 65 64 20 61 20 73 70 65 63 69 66  ntained a specif
271e0 69 63 20 71 75 65 72 79 20 0a 2a 2a 20 70 61 72  ic query .** par
271f0 61 6d 65 74 65 72 2c 20 61 6e 64 20 69 66 20 73  ameter, and if s
27200 6f 20 6f 62 74 61 69 6e 73 20 74 68 65 20 76 61  o obtains the va
27210 6c 75 65 20 6f 66 20 74 68 61 74 20 71 75 65 72  lue of that quer
27220 79 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  y parameter..**.
27230 2a 2a 20 49 66 20 46 20 69 73 20 74 68 65 20 64  ** If F is the d
27240 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
27250 20 70 6f 69 6e 74 65 72 20 70 61 73 73 65 64 20   pointer passed 
27260 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29  into the xOpen()
27270 20 6d 65 74 68 6f 64 20 6f 66 20 0a 2a 2a 20 61   method of .** a
27280 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
27290 69 6f 6e 20 77 68 65 6e 20 74 68 65 20 66 6c 61  ion when the fla
272a0 67 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  gs parameter to 
272b0 78 4f 70 65 6e 28 29 20 68 61 73 20 6f 6e 65 20  xOpen() has one 
272c0 6f 72 20 0a 2a 2a 20 6d 6f 72 65 20 6f 66 20 74  or .** more of t
272d0 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
272e0 55 52 49 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  URI] or [SQLITE_
272f0 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 20 62 69  OPEN_MAIN_DB] bi
27300 74 73 20 73 65 74 20 61 6e 64 0a 2a 2a 20 50 20  ts set and.** P 
27310 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
27320 68 65 20 71 75 65 72 79 20 70 61 72 61 6d 65 74  he query paramet
27330 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69  er, then.** sqli
27340 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65  te3_uri_paramete
27350 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20 74  r(F,P) returns t
27360 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  he value of the 
27370 50 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69  P.** parameter i
27380 66 20 69 74 20 65 78 69 73 74 73 20 6f 72 20 61  f it exists or a
27390 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66   NULL pointer if
273a0 20 50 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 65   P does not appe
273b0 61 72 20 61 73 20 61 20 0a 2a 2a 20 71 75 65 72  ar as a .** quer
273c0 79 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 46  y parameter on F
273d0 2e 20 20 49 66 20 50 20 69 73 20 61 20 71 75 65  .  If P is a que
273e0 72 79 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  ry parameter of 
273f0 46 0a 2a 2a 20 68 61 73 20 6e 6f 20 65 78 70 6c  F.** has no expl
27400 69 63 69 74 20 76 61 6c 75 65 2c 20 74 68 65 6e  icit value, then
27410 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72   sqlite3_uri_par
27420 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75  ameter(F,P) retu
27430 72 6e 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72  rns.** a pointer
27440 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 74 72   to an empty str
27450 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ing..**.** The s
27460 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65  qlite3_uri_boole
27470 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e  an(F,P,B) routin
27480 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 50  e assumes that P
27490 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 0a 2a 2a   is a boolean.**
274a0 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72   parameter and r
274b0 65 74 75 72 6e 73 20 74 72 75 65 20 28 31 29 20  eturns true (1) 
274c0 6f 72 20 66 61 6c 73 65 20 28 30 29 20 61 63 63  or false (0) acc
274d0 6f 72 64 69 6e 67 20 74 6f 20 74 68 65 20 76 61  ording to the va
274e0 6c 75 65 0a 2a 2a 20 6f 66 20 50 2e 20 20 54 68  lue.** of P.  Th
274f0 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f  e sqlite3_uri_bo
27500 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75  olean(F,P,B) rou
27510 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 72 75  tine returns tru
27520 65 20 28 31 29 20 69 66 20 74 68 65 0a 2a 2a 20  e (1) if the.** 
27530 76 61 6c 75 65 20 6f 66 20 71 75 65 72 79 20 70  value of query p
27540 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 6f 6e  arameter P is on
27550 65 20 6f 66 20 22 79 65 73 22 2c 20 22 74 72 75  e of "yes", "tru
27560 65 22 2c 20 6f 72 20 22 6f 6e 22 20 69 6e 20 61  e", or "on" in a
27570 6e 79 0a 2a 2a 20 63 61 73 65 20 6f 72 20 69 66  ny.** case or if
27580 20 74 68 65 20 76 61 6c 75 65 20 62 65 67 69 6e   the value begin
27590 73 20 77 69 74 68 20 61 20 6e 6f 6e 2d 7a 65 72  s with a non-zer
275a0 6f 20 6e 75 6d 62 65 72 2e 20 20 54 68 65 20 0a  o number.  The .
275b0 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62  ** sqlite3_uri_b
275c0 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f  oolean(F,P,B) ro
275d0 75 74 69 6e 65 73 20 72 65 74 75 72 6e 73 20 66  utines returns f
275e0 61 6c 73 65 20 28 30 29 20 69 66 20 74 68 65 20  alse (0) if the 
275f0 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 71 75 65 72  value of.** quer
27600 79 20 70 61 72 61 6d 65 74 65 72 20 50 20 69 73  y parameter P is
27610 20 6f 6e 65 20 6f 66 20 22 6e 6f 22 2c 20 22 66   one of "no", "f
27620 61 6c 73 65 22 2c 20 6f 72 20 22 6f 66 66 22 20  alse", or "off" 
27630 69 6e 20 61 6e 79 20 63 61 73 65 20 6f 72 0a 2a  in any case or.*
27640 2a 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 62  * if the value b
27650 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e 75 6d  egins with a num
27660 65 72 69 63 20 7a 65 72 6f 2e 20 20 49 66 20 50  eric zero.  If P
27670 20 69 73 20 6e 6f 74 20 61 20 71 75 65 72 79 0a   is not a query.
27680 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20  ** parameter on 
27690 46 20 6f 72 20 69 66 20 74 68 65 20 76 61 6c 75  F or if the valu
276a0 65 20 6f 66 20 50 20 69 73 20 64 6f 65 73 20 6e  e of P is does n
276b0 6f 74 20 6d 61 74 63 68 20 61 6e 79 20 6f 66 20  ot match any of 
276c0 74 68 65 0a 2a 2a 20 61 62 6f 76 65 2c 20 74 68  the.** above, th
276d0 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62  en sqlite3_uri_b
276e0 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 65  oolean(F,P,B) re
276f0 74 75 72 6e 73 20 28 42 21 3d 30 29 2e 0a 2a 2a  turns (B!=0)..**
27700 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
27710 75 72 69 5f 69 6e 74 36 34 28 46 2c 50 2c 44 29  uri_int64(F,P,D)
27720 20 72 6f 75 74 69 6e 65 20 63 6f 6e 76 65 72 74   routine convert
27730 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50  s the value of P
27740 20 69 6e 74 6f 20 61 0a 2a 2a 20 36 34 2d 62 69   into a.** 64-bi
27750 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  t signed integer
27760 20 61 6e 64 20 72 65 74 75 72 6e 73 20 74 68 61   and returns tha
27770 74 20 69 6e 74 65 67 65 72 2c 20 6f 72 20 44 20  t integer, or D 
27780 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a  if P does not.**
27790 20 65 78 69 73 74 2e 20 20 49 66 20 74 68 65 20   exist.  If the 
277a0 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20 73 6f  value of P is so
277b0 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68  mething other th
277c0 61 6e 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74  an an integer, t
277d0 68 65 6e 0a 2a 2a 20 7a 65 72 6f 20 69 73 20 72  hen.** zero is r
277e0 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a 20  eturned..** .** 
277f0 49 66 20 46 20 69 73 20 61 20 4e 55 4c 4c 20 70  If F is a NULL p
27800 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 73 71 6c  ointer, then sql
27810 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74  ite3_uri_paramet
27820 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20  er(F,P) returns 
27830 4e 55 4c 4c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69  NULL and.** sqli
27840 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28  te3_uri_boolean(
27850 46 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 20 42  F,P,B) returns B
27860 2e 20 20 49 66 20 46 20 69 73 20 6e 6f 74 20 61  .  If F is not a
27870 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e   NULL pointer an
27880 64 0a 2a 2a 20 69 73 20 6e 6f 74 20 61 20 64 61  d.** is not a da
27890 74 61 62 61 73 65 20 66 69 6c 65 20 70 61 74 68  tabase file path
278a0 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 74 68 61  name pointer tha
278b0 74 20 53 51 4c 69 74 65 20 70 61 73 73 65 64 20  t SQLite passed 
278c0 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 0a 2a  into the xOpen.*
278d0 2a 20 56 46 53 20 6d 65 74 68 6f 64 2c 20 74 68  * VFS method, th
278e0 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
278f0 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  of this routine 
27900 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64  is undefined and
27910 20 70 72 6f 62 61 62 6c 79 0a 2a 2a 20 75 6e 64   probably.** und
27920 65 73 69 72 61 62 6c 65 2e 0a 2a 2f 0a 53 51 4c  esirable..*/.SQL
27930 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68  ITE_API const ch
27940 61 72 20 2a 73 71 6c 69 74 65 33 5f 75 72 69 5f  ar *sqlite3_uri_
27950 70 61 72 61 6d 65 74 65 72 28 63 6f 6e 73 74 20  parameter(const 
27960 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 2c  char *zFilename,
27970 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61   const char *zPa
27980 72 61 6d 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  ram);.SQLITE_API
27990 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 75 72 69   int sqlite3_uri
279a0 5f 62 6f 6f 6c 65 61 6e 28 63 6f 6e 73 74 20 63  _boolean(const c
279b0 68 61 72 20 2a 7a 46 69 6c 65 2c 20 63 6f 6e 73  har *zFile, cons
279c0 74 20 63 68 61 72 20 2a 7a 50 61 72 61 6d 2c 20  t char *zParam, 
279d0 69 6e 74 20 62 44 65 66 61 75 6c 74 29 3b 0a 53  int bDefault);.S
279e0 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65  QLITE_API sqlite
279f0 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
27a00 75 72 69 5f 69 6e 74 36 34 28 63 6f 6e 73 74 20  uri_int64(const 
27a10 63 68 61 72 2a 2c 20 63 6f 6e 73 74 20 63 68 61  char*, const cha
27a20 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  r*, sqlite3_int6
27a30 34 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  4);.../*.** CAPI
27a40 33 52 45 46 3a 20 45 72 72 6f 72 20 43 6f 64 65  3REF: Error Code
27a50 73 20 41 6e 64 20 4d 65 73 73 61 67 65 73 0a 2a  s And Messages.*
27a60 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
27a70 33 5f 65 72 72 63 6f 64 65 28 29 20 69 6e 74 65  3_errcode() inte
27a80 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
27a90 65 20 6e 75 6d 65 72 69 63 20 5b 72 65 73 75 6c  e numeric [resul
27aa0 74 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65  t code] or.** [e
27ab0 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
27ac0 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 6d 6f 73  ode] for the mos
27ad0 74 20 72 65 63 65 6e 74 20 66 61 69 6c 65 64 20  t recent failed 
27ae0 73 71 6c 69 74 65 33 5f 2a 20 41 50 49 20 63 61  sqlite3_* API ca
27af0 6c 6c 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64  ll.** associated
27b00 20 77 69 74 68 20 61 20 5b 64 61 74 61 62 61 73   with a [databas
27b10 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 49  e connection]. I
27b20 66 20 61 20 70 72 69 6f 72 20 41 50 49 20 63 61  f a prior API ca
27b30 6c 6c 20 66 61 69 6c 65 64 0a 2a 2a 20 62 75 74  ll failed.** but
27b40 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
27b50 20 41 50 49 20 63 61 6c 6c 20 73 75 63 63 65 65   API call succee
27b60 64 65 64 2c 20 74 68 65 20 72 65 74 75 72 6e 20  ded, the return 
27b70 76 61 6c 75 65 20 66 72 6f 6d 0a 2a 2a 20 73 71  value from.** sq
27b80 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20  lite3_errcode() 
27b90 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 5e  is undefined.  ^
27ba0 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65  The sqlite3_exte
27bb0 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29 0a 2a  nded_errcode().*
27bc0 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74  * interface is t
27bd0 68 65 20 73 61 6d 65 20 65 78 63 65 70 74 20 74  he same except t
27be0 68 61 74 20 69 74 20 61 6c 77 61 79 73 20 72 65  hat it always re
27bf0 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 65  turns the .** [e
27c00 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
27c10 6f 64 65 5d 20 65 76 65 6e 20 77 68 65 6e 20 65  ode] even when e
27c20 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
27c30 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64 69 73 61  odes are.** disa
27c40 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  bled..**.** ^The
27c50 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28   sqlite3_errmsg(
27c60 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 65 72  ) and sqlite3_er
27c70 72 6d 73 67 31 36 28 29 20 72 65 74 75 72 6e 20  rmsg16() return 
27c80 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65  English-language
27c90 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 20 64 65  .** text that de
27ca0 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f  scribes the erro
27cb0 72 2c 20 61 73 20 65 69 74 68 65 72 20 55 54 46  r, as either UTF
27cc0 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 72 65 73  -8 or UTF-16 res
27cd0 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28  pectively..** ^(
27ce0 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74  Memory to hold t
27cf0 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
27d00 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67   string is manag
27d10 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a  ed internally..*
27d20 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
27d30 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  n does not need 
27d40 74 6f 20 77 6f 72 72 79 20 61 62 6f 75 74 20 66  to worry about f
27d50 72 65 65 69 6e 67 20 74 68 65 20 72 65 73 75 6c  reeing the resul
27d60 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74  t..** However, t
27d70 68 65 20 65 72 72 6f 72 20 73 74 72 69 6e 67 20  he error string 
27d80 6d 69 67 68 74 20 62 65 20 6f 76 65 72 77 72 69  might be overwri
27d90 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61  tten or dealloca
27da0 74 65 64 20 62 79 0a 2a 2a 20 73 75 62 73 65 71  ted by.** subseq
27db0 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74  uent calls to ot
27dc0 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72  her SQLite inter
27dd0 66 61 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e 29  face functions.)
27de0 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ^.**.** ^The sql
27df0 69 74 65 33 5f 65 72 72 73 74 72 28 29 20 69 6e  ite3_errstr() in
27e00 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
27e10 74 68 65 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67  the English-lang
27e20 75 61 67 65 20 74 65 78 74 0a 2a 2a 20 74 68 61  uage text.** tha
27e30 74 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20  t describes the 
27e40 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 2c 20 61  [result code], a
27e50 73 20 55 54 46 2d 38 2e 0a 2a 2a 20 5e 28 4d 65  s UTF-8..** ^(Me
27e60 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65  mory to hold the
27e70 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73   error message s
27e80 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64  tring is managed
27e90 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 61   internally.** a
27ea0 6e 64 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 66  nd must not be f
27eb0 72 65 65 64 20 62 79 20 74 68 65 20 61 70 70 6c  reed by the appl
27ec0 69 63 61 74 69 6f 6e 29 5e 2e 0a 2a 2a 0a 2a 2a  ication)^..**.**
27ed0 20 57 68 65 6e 20 74 68 65 20 73 65 72 69 61 6c   When the serial
27ee0 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20  ized [threading 
27ef0 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75 73 65 2c  mode] is in use,
27f00 20 69 74 20 6d 69 67 68 74 20 62 65 20 74 68 65   it might be the
27f10 0a 2a 2a 20 63 61 73 65 20 74 68 61 74 20 61 20  .** case that a 
27f20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 6f 63 63  second error occ
27f30 75 72 73 20 6f 6e 20 61 20 73 65 70 61 72 61 74  urs on a separat
27f40 65 20 74 68 72 65 61 64 20 69 6e 20 62 65 74 77  e thread in betw
27f50 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69 6d 65 20  een.** the time 
27f60 6f 66 20 74 68 65 20 66 69 72 73 74 20 65 72 72  of the first err
27f70 6f 72 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 20  or and the call 
27f80 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66 61  to these interfa
27f90 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 61  ces..** When tha
27fa0 74 20 68 61 70 70 65 6e 73 2c 20 74 68 65 20 73  t happens, the s
27fb0 65 63 6f 6e 64 20 65 72 72 6f 72 20 77 69 6c 6c  econd error will
27fc0 20 62 65 20 72 65 70 6f 72 74 65 64 20 73 69 6e   be reported sin
27fd0 63 65 20 74 68 65 73 65 0a 2a 2a 20 69 6e 74 65  ce these.** inte
27fe0 72 66 61 63 65 73 20 61 6c 77 61 79 73 20 72 65  rfaces always re
27ff0 70 6f 72 74 20 74 68 65 20 6d 6f 73 74 20 72 65  port the most re
28000 63 65 6e 74 20 72 65 73 75 6c 74 2e 20 20 54 6f  cent result.  To
28010 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69 73 2c 20   avoid.** this, 
28020 65 61 63 68 20 74 68 72 65 61 64 20 63 61 6e 20  each thread can 
28030 6f 62 74 61 69 6e 20 65 78 63 6c 75 73 69 76 65  obtain exclusive
28040 20 75 73 65 20 6f 66 20 74 68 65 20 5b 64 61 74   use of the [dat
28050 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
28060 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b 69  ] D.** by invoki
28070 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  ng [sqlite3_mute
28080 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c 69 74 65  x_enter]([sqlite
28090 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20  3_db_mutex](D)) 
280a0 62 65 66 6f 72 65 20 62 65 67 69 6e 6e 69 6e 67  before beginning
280b0 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20 61 6e 64  .** to use D and
280c0 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74   invoking [sqlit
280d0 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 5d 28  e3_mutex_leave](
280e0 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65  [sqlite3_db_mute
280f0 78 5d 28 44 29 29 20 61 66 74 65 72 0a 2a 2a 20  x](D)) after.** 
28100 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 74 68 65  all calls to the
28110 20 69 6e 74 65 72 66 61 63 65 73 20 6c 69 73 74   interfaces list
28120 65 64 20 68 65 72 65 20 61 72 65 20 63 6f 6d 70  ed here are comp
28130 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  leted..**.** If 
28140 61 6e 20 69 6e 74 65 72 66 61 63 65 20 66 61 69  an interface fai
28150 6c 73 20 77 69 74 68 20 53 51 4c 49 54 45 5f 4d  ls with SQLITE_M
28160 49 53 55 53 45 2c 20 74 68 61 74 20 6d 65 61 6e  ISUSE, that mean
28170 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 0a  s the interface.
28180 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64 20 69  ** was invoked i
28190 6e 63 6f 72 72 65 63 74 6c 79 20 62 79 20 74 68  ncorrectly by th
281a0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20  e application.  
281b0 49 6e 20 74 68 61 74 20 63 61 73 65 2c 20 74 68  In that case, th
281c0 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 20  e.** error code 
281d0 61 6e 64 20 6d 65 73 73 61 67 65 20 6d 61 79 20  and message may 
281e0 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65 20 73 65  or may not be se
281f0 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  t..*/.SQLITE_API
28200 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 72 72   int sqlite3_err
28210 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62  code(sqlite3 *db
28220 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
28230 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64  t sqlite3_extend
28240 65 64 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74  ed_errcode(sqlit
28250 65 33 20 2a 64 62 29 3b 0a 53 51 4c 49 54 45 5f  e3 *db);.SQLITE_
28260 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  API const char *
28270 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 73  sqlite3_errmsg(s
28280 71 6c 69 74 65 33 2a 29 3b 0a 53 51 4c 49 54 45  qlite3*);.SQLITE
28290 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20  _API const void 
282a0 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31  *sqlite3_errmsg1
282b0 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a 53 51 4c  6(sqlite3*);.SQL
282c0 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68  ITE_API const ch
282d0 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 73  ar *sqlite3_errs
282e0 74 72 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  tr(int);../*.** 
282f0 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 53 74  CAPI3REF: SQL St
28300 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a  atement Object.*
28310 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 65  * KEYWORDS: {pre
28320 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 7d  pared statement}
28330 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   {prepared state
28340 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20  ments}.**.** An 
28350 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
28360 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e   object represen
28370 74 73 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20  ts a single SQL 
28380 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 54 68  statement..** Th
28390 69 73 20 6f 62 6a 65 63 74 20 69 73 20 76 61 72  is object is var
283a0 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e 20 61 73 20  iously known as 
283b0 61 20 22 70 72 65 70 61 72 65 64 20 73 74 61 74  a "prepared stat
283c0 65 6d 65 6e 74 22 20 6f 72 20 61 0a 2a 2a 20 22  ement" or a.** "
283d0 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73 74 61  compiled SQL sta
283e0 74 65 6d 65 6e 74 22 20 6f 72 20 73 69 6d 70 6c  tement" or simpl
283f0 79 20 61 73 20 61 20 22 73 74 61 74 65 6d 65 6e  y as a "statemen
28400 74 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69  t"..**.** The li
28410 66 65 20 6f 66 20 61 20 73 74 61 74 65 6d 65 6e  fe of a statemen
28420 74 20 6f 62 6a 65 63 74 20 67 6f 65 73 20 73 6f  t object goes so
28430 6d 65 74 68 69 6e 67 20 6c 69 6b 65 20 74 68 69  mething like thi
28440 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a  s:.**.** <ol>.**
28450 20 3c 6c 69 3e 20 43 72 65 61 74 65 20 74 68 65   <li> Create the
28460 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73   object using [s
28470 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
28480 32 28 29 5d 20 6f 72 20 61 20 72 65 6c 61 74 65  2()] or a relate
28490 64 0a 2a 2a 20 20 20 20 20 20 66 75 6e 63 74 69  d.**      functi
284a0 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64  on..** <li> Bind
284b0 20 76 61 6c 75 65 73 20 74 6f 20 5b 68 6f 73 74   values to [host
284c0 20 70 61 72 61 6d 65 74 65 72 73 5d 20 75 73 69   parameters] usi
284d0 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  ng the sqlite3_b
284e0 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 20 20 20  ind_*().**      
284f0 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 3c  interfaces..** <
28500 6c 69 3e 20 52 75 6e 20 74 68 65 20 53 51 4c 20  li> Run the SQL 
28510 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  by calling [sqli
28520 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65 20  te3_step()] one 
28530 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a  or more times..*
28540 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20 74 68 65  * <li> Reset the
28550 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67   statement using
28560 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
28570 29 5d 20 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a  )] then go back.
28580 2a 2a 20 20 20 20 20 20 74 6f 20 73 74 65 70 20  **      to step 
28590 32 2e 20 20 44 6f 20 74 68 69 73 20 7a 65 72 6f  2.  Do this zero
285a0 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a   or more times..
285b0 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20  ** <li> Destroy 
285c0 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67  the object using
285d0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
285e0 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a  ze()]..** </ol>.
285f0 2a 2a 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 64  **.** Refer to d
28600 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 6f 6e 20  ocumentation on 
28610 69 6e 64 69 76 69 64 75 61 6c 20 6d 65 74 68 6f  individual metho
28620 64 73 20 61 62 6f 76 65 20 66 6f 72 20 61 64 64  ds above for add
28630 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72  itional.** infor
28640 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64  mation..*/.typed
28650 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
28660 33 5f 73 74 6d 74 20 73 71 6c 69 74 65 33 5f 73  3_stmt sqlite3_s
28670 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  tmt;../*.** CAPI
28680 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65 20 4c  3REF: Run-time L
28690 69 6d 69 74 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  imits.**.** ^(Th
286a0 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c  is interface all
286b0 6f 77 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20  ows the size of 
286c0 76 61 72 69 6f 75 73 20 63 6f 6e 73 74 72 75 63  various construc
286d0 74 73 20 74 6f 20 62 65 20 6c 69 6d 69 74 65 64  ts to be limited
286e0 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65 63 74  .** on a connect
286f0 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63 74 69 6f  ion by connectio
28700 6e 20 62 61 73 69 73 2e 20 20 54 68 65 20 66 69  n basis.  The fi
28710 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
28720 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73   the.** [databas
28730 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 68  e connection] wh
28740 6f 73 65 20 6c 69 6d 69 74 20 69 73 20 74 6f 20  ose limit is to 
28750 62 65 20 73 65 74 20 6f 72 20 71 75 65 72 69 65  be set or querie
28760 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e  d.  The.** secon
28770 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6f  d parameter is o
28780 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69 6d 69 74  ne of the [limit
28790 20 63 61 74 65 67 6f 72 69 65 73 5d 20 74 68 61   categories] tha
287a0 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a 20 63 6c  t define a.** cl
287b0 61 73 73 20 6f 66 20 63 6f 6e 73 74 72 75 63 74  ass of construct
287c0 73 20 74 6f 20 62 65 20 73 69 7a 65 20 6c 69 6d  s to be size lim
287d0 69 74 65 64 2e 20 20 54 68 65 20 74 68 69 72 64  ited.  The third
287e0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
287f0 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69 74 20 66  e.** new limit f
28800 6f 72 20 74 68 61 74 20 63 6f 6e 73 74 72 75 63  or that construc
28810 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  t.)^.**.** ^If t
28820 68 65 20 6e 65 77 20 6c 69 6d 69 74 20 69 73 20  he new limit is 
28830 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62 65  a negative numbe
28840 72 2c 20 74 68 65 20 6c 69 6d 69 74 20 69 73 20  r, the limit is 
28850 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 5e 28  unchanged..** ^(
28860 46 6f 72 20 65 61 63 68 20 6c 69 6d 69 74 20 63  For each limit c
28870 61 74 65 67 6f 72 79 20 53 51 4c 49 54 45 5f 4c  ategory SQLITE_L
28880 49 4d 49 54 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e  IMIT_<i>NAME</i>
28890 20 74 68 65 72 65 20 69 73 20 61 20 0a 2a 2a 20   there is a .** 
288a0 5b 6c 69 6d 69 74 73 20 7c 20 68 61 72 64 20 75  [limits | hard u
288b0 70 70 65 72 20 62 6f 75 6e 64 5d 0a 2a 2a 20 73  pper bound].** s
288c0 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69  et at compile-ti
288d0 6d 65 20 62 79 20 61 20 43 20 70 72 65 70 72 6f  me by a C prepro
288e0 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 63 61 6c  cessor macro cal
288f0 6c 65 64 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c  led.** [limits |
28900 20 53 51 4c 49 54 45 5f 4d 41 58 5f 3c 69 3e 4e   SQLITE_MAX_<i>N
28910 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a 20 28 54 68  AME</i>]..** (Th
28920 65 20 22 5f 4c 49 4d 49 54 5f 22 20 69 6e 20 74  e "_LIMIT_" in t
28930 68 65 20 6e 61 6d 65 20 69 73 20 63 68 61 6e 67  he name is chang
28940 65 64 20 74 6f 20 22 5f 4d 41 58 5f 22 2e 29 29  ed to "_MAX_".))
28950 5e 0a 2a 2a 20 5e 41 74 74 65 6d 70 74 73 20 74  ^.** ^Attempts t
28960 6f 20 69 6e 63 72 65 61 73 65 20 61 20 6c 69 6d  o increase a lim
28970 69 74 20 61 62 6f 76 65 20 69 74 73 20 68 61 72  it above its har
28980 64 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61 72  d upper bound ar
28990 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79 20 74 72  e.** silently tr
289a0 75 6e 63 61 74 65 64 20 74 6f 20 74 68 65 20 68  uncated to the h
289b0 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 2e  ard upper bound.
289c0 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 61 72 64 6c 65  .**.** ^Regardle
289d0 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72  ss of whether or
289e0 20 6e 6f 74 20 74 68 65 20 6c 69 6d 69 74 20 77   not the limit w
289f0 61 73 20 63 68 61 6e 67 65 64 2c 20 74 68 65 20  as changed, the 
28a00 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d  .** [sqlite3_lim
28a10 69 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  it()] interface 
28a20 72 65 74 75 72 6e 73 20 74 68 65 20 70 72 69 6f  returns the prio
28a30 72 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 6c  r value of the l
28a40 69 6d 69 74 2e 0a 2a 2a 20 5e 48 65 6e 63 65 2c  imit..** ^Hence,
28a50 20 74 6f 20 66 69 6e 64 20 74 68 65 20 63 75 72   to find the cur
28a60 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 20 61 20  rent value of a 
28a70 6c 69 6d 69 74 20 77 69 74 68 6f 75 74 20 63 68  limit without ch
28a80 61 6e 67 69 6e 67 20 69 74 2c 0a 2a 2a 20 73 69  anging it,.** si
28a90 6d 70 6c 79 20 69 6e 76 6f 6b 65 20 74 68 69 73  mply invoke this
28aa0 20 69 6e 74 65 72 66 61 63 65 20 77 69 74 68 20   interface with 
28ab0 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
28ac0 74 65 72 20 73 65 74 20 74 6f 20 2d 31 2e 0a 2a  ter set to -1..*
28ad0 2a 0a 2a 2a 20 52 75 6e 2d 74 69 6d 65 20 6c 69  *.** Run-time li
28ae0 6d 69 74 73 20 61 72 65 20 69 6e 74 65 6e 64 65  mits are intende
28af0 64 20 66 6f 72 20 75 73 65 20 69 6e 20 61 70 70  d for use in app
28b00 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6d  lications that m
28b10 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68 20 74 68  anage.** both th
28b20 65 69 72 20 6f 77 6e 20 69 6e 74 65 72 6e 61 6c  eir own internal
28b30 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 61 6c   database and al
28b40 73 6f 20 64 61 74 61 62 61 73 65 73 20 74 68 61  so databases tha
28b50 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c 6c 65 64  t are controlled
28b60 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73 74 65 64  .** by untrusted
28b70 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65   external source
28b80 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 61  s.  An example a
28b90 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67 68 74  pplication might
28ba0 20 62 65 20 61 0a 2a 2a 20 77 65 62 20 62 72 6f   be a.** web bro
28bb0 77 73 65 72 20 74 68 61 74 20 68 61 73 20 69 74  wser that has it
28bc0 73 20 6f 77 6e 20 64 61 74 61 62 61 73 65 73 20  s own databases 
28bd0 66 6f 72 20 73 74 6f 72 69 6e 67 20 68 69 73 74  for storing hist
28be0 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 65 70 61 72  ory and.** separ
28bf0 61 74 65 20 64 61 74 61 62 61 73 65 73 20 63 6f  ate databases co
28c00 6e 74 72 6f 6c 6c 65 64 20 62 79 20 4a 61 76 61  ntrolled by Java
28c10 53 63 72 69 70 74 20 61 70 70 6c 69 63 61 74 69  Script applicati
28c20 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a  ons downloaded.*
28c30 2a 20 6f 66 66 20 74 68 65 20 49 6e 74 65 72 6e  * off the Intern
28c40 65 74 2e 20 20 54 68 65 20 69 6e 74 65 72 6e 61  et.  The interna
28c50 6c 20 64 61 74 61 62 61 73 65 73 20 63 61 6e 20  l databases can 
28c60 62 65 20 67 69 76 65 6e 20 74 68 65 0a 2a 2a 20  be given the.** 
28c70 6c 61 72 67 65 2c 20 64 65 66 61 75 6c 74 20 6c  large, default l
28c80 69 6d 69 74 73 2e 20 20 44 61 74 61 62 61 73 65  imits.  Database
28c90 73 20 6d 61 6e 61 67 65 64 20 62 79 20 65 78 74  s managed by ext
28ca0 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 20 63 61  ernal sources ca
28cb0 6e 0a 2a 2a 20 62 65 20 67 69 76 65 6e 20 6d 75  n.** be given mu
28cc0 63 68 20 73 6d 61 6c 6c 65 72 20 6c 69 6d 69 74  ch smaller limit
28cd0 73 20 64 65 73 69 67 6e 65 64 20 74 6f 20 70 72  s designed to pr
28ce0 65 76 65 6e 74 20 61 20 64 65 6e 69 61 6c 20 6f  event a denial o
28cf0 66 20 73 65 72 76 69 63 65 0a 2a 2a 20 61 74 74  f service.** att
28d00 61 63 6b 2e 20 20 44 65 76 65 6c 6f 70 65 72 73  ack.  Developers
28d10 20 6d 69 67 68 74 20 61 6c 73 6f 20 77 61 6e 74   might also want
28d20 20 74 6f 20 75 73 65 20 74 68 65 20 5b 73 71 6c   to use the [sql
28d30 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
28d40 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66  zer()].** interf
28d50 61 63 65 20 74 6f 20 66 75 72 74 68 65 72 20 63  ace to further c
28d60 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 73 74 65 64  ontrol untrusted
28d70 20 53 51 4c 2e 20 20 54 68 65 20 73 69 7a 65 20   SQL.  The size 
28d80 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  of the database.
28d90 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 61 6e  ** created by an
28da0 20 75 6e 74 72 75 73 74 65 64 20 73 63 72 69 70   untrusted scrip
28db0 74 20 63 61 6e 20 62 65 20 63 6f 6e 74 61 69 6e  t can be contain
28dc0 65 64 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  ed using the.** 
28dd0 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d  [max_page_count]
28de0 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a   [PRAGMA]..**.**
28df0 20 4e 65 77 20 72 75 6e 2d 74 69 6d 65 20 6c 69   New run-time li
28e00 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 20 6d  mit categories m
28e10 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
28e20 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a  uture releases..
28e30 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
28e40 74 20 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28  t sqlite3_limit(
28e50 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 69 64  sqlite3*, int id
28e60 2c 20 69 6e 74 20 6e 65 77 56 61 6c 29 3b 0a 0a  , int newVal);..
28e70 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
28e80 52 75 6e 2d 54 69 6d 65 20 4c 69 6d 69 74 20 43  Run-Time Limit C
28e90 61 74 65 67 6f 72 69 65 73 0a 2a 2a 20 4b 45 59  ategories.** KEY
28ea0 57 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63 61  WORDS: {limit ca
28eb0 74 65 67 6f 72 79 7d 20 7b 2a 6c 69 6d 69 74 20  tegory} {*limit 
28ec0 63 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a  categories}.**.*
28ed0 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
28ee0 73 20 64 65 66 69 6e 65 20 76 61 72 69 6f 75 73  s define various
28ef0 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6c 69 6d   performance lim
28f00 69 74 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20  its.** that can 
28f10 62 65 20 6c 6f 77 65 72 65 64 20 61 74 20 72 75  be lowered at ru
28f20 6e 2d 74 69 6d 65 20 75 73 69 6e 67 20 5b 73 71  n-time using [sq
28f30 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a  lite3_limit()]..
28f40 2a 2a 20 54 68 65 20 73 79 6e 6f 70 73 69 73 20  ** The synopsis 
28f50 6f 66 20 74 68 65 20 6d 65 61 6e 69 6e 67 73 20  of the meanings 
28f60 6f 66 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c  of the various l
28f70 69 6d 69 74 73 20 69 73 20 73 68 6f 77 6e 20 62  imits is shown b
28f80 65 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69 74 69 6f  elow..** Additio
28f90 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  nal information 
28fa0 69 73 20 61 76 61 69 6c 61 62 6c 65 20 61 74 20  is available at 
28fb0 5b 6c 69 6d 69 74 73 20 7c 20 4c 69 6d 69 74 73  [limits | Limits
28fc0 20 69 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a 0a   in SQLite]..**.
28fd0 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c  ** <dl>.** [[SQL
28fe0 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48  ITE_LIMIT_LENGTH
28ff0 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
29000 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f 64 74  LIMIT_LENGTH</dt
29010 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
29020 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 61 6e 79  imum size of any
29030 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20   string or BLOB 
29040 6f 72 20 74 61 62 6c 65 20 72 6f 77 2c 20 69 6e  or table row, in
29050 20 62 79 74 65 73 2e 3c 64 64 3e 29 5e 0a 2a 2a   bytes.<dd>)^.**
29060 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
29070 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 5d 5d 20  IT_SQL_LENGTH]] 
29080 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
29090 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64  IT_SQL_LENGTH</d
290a0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
290b0 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
290c0 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
290d0 2c 20 69 6e 20 62 79 74 65 73 2e 3c 2f 64 64 3e  , in bytes.</dd>
290e0 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
290f0 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 5d 5d  E_LIMIT_COLUMN]]
29100 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
29110 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a  MIT_COLUMN</dt>.
29120 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
29130 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  um number of col
29140 75 6d 6e 73 20 69 6e 20 61 20 74 61 62 6c 65 20  umns in a table 
29150 64 65 66 69 6e 69 74 69 6f 6e 20 6f 72 20 69 6e  definition or in
29160 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 73   the.** result s
29170 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d  et of a [SELECT]
29180 20 6f 72 20 74 68 65 20 6d 61 78 69 6d 75 6d 20   or the maximum 
29190 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
291a0 73 20 69 6e 20 61 6e 20 69 6e 64 65 78 0a 2a 2a  s in an index.**
291b0 20 6f 72 20 69 6e 20 61 6e 20 4f 52 44 45 52 20   or in an ORDER 
291c0 42 59 20 6f 72 20 47 52 4f 55 50 20 42 59 20 63  BY or GROUP BY c
291d0 6c 61 75 73 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  lause.</dd>)^.**
291e0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
291f0 49 54 5f 45 58 50 52 5f 44 45 50 54 48 5d 5d 20  IT_EXPR_DEPTH]] 
29200 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
29210 49 54 5f 45 58 50 52 5f 44 45 50 54 48 3c 2f 64  IT_EXPR_DEPTH</d
29220 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
29230 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 74  ximum depth of t
29240 68 65 20 70 61 72 73 65 20 74 72 65 65 20 6f 6e  he parse tree on
29250 20 61 6e 79 20 65 78 70 72 65 73 73 69 6f 6e 2e   any expression.
29260 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
29270 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d  SQLITE_LIMIT_COM
29280 50 4f 55 4e 44 5f 53 45 4c 45 43 54 5d 5d 20 5e  POUND_SELECT]] ^
29290 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
292a0 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43  T_COMPOUND_SELEC
292b0 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  T</dt>.** <dd>Th
292c0 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
292d0 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 61 20 63   of terms in a c
292e0 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54 20 73  ompound SELECT s
292f0 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29 5e  tatement.</dd>)^
29300 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
29310 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 5d 5d 20  LIMIT_VDBE_OP]] 
29320 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
29330 49 54 5f 56 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a  IT_VDBE_OP</dt>.
29340 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
29350 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 69 6e 73  um number of ins
29360 74 72 75 63 74 69 6f 6e 73 20 69 6e 20 61 20 76  tructions in a v
29370 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 70  irtual machine p
29380 72 6f 67 72 61 6d 0a 2a 2a 20 75 73 65 64 20 74  rogram.** used t
29390 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 6e 20 53  o implement an S
293a0 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 54  QL statement.  T
293b0 68 69 73 20 6c 69 6d 69 74 20 69 73 20 6e 6f 74  his limit is not
293c0 20 63 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 65 6e   currently.** en
293d0 66 6f 72 63 65 64 2c 20 74 68 6f 75 67 68 20 74  forced, though t
293e0 68 61 74 20 6d 69 67 68 74 20 62 65 20 61 64 64  hat might be add
293f0 65 64 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72  ed in some futur
29400 65 20 72 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20  e release of.** 
29410 53 51 4c 69 74 65 2e 3c 2f 64 64 3e 29 5e 0a 2a  SQLite.</dd>)^.*
29420 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
29430 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47  MIT_FUNCTION_ARG
29440 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
29450 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41  LIMIT_FUNCTION_A
29460 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  RG</dt>.** <dd>T
29470 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
29480 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 6f  r of arguments o
29490 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64  n a function.</d
294a0 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
294b0 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48  ITE_LIMIT_ATTACH
294c0 45 44 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  ED]] ^(<dt>SQLIT
294d0 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44  E_LIMIT_ATTACHED
294e0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
294f0 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
29500 6f 66 20 5b 41 54 54 41 43 48 20 7c 20 61 74 74  of [ATTACH | att
29510 61 63 68 65 64 20 64 61 74 61 62 61 73 65 73 5d  ached databases]
29520 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  .)^</dd>.**.** [
29530 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49  [SQLITE_LIMIT_LI
29540 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54  KE_PATTERN_LENGT
29550 48 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c  H]].** ^(<dt>SQL
29560 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50  ITE_LIMIT_LIKE_P
29570 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64  ATTERN_LENGTH</d
29580 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
29590 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
295a0 74 68 65 20 70 61 74 74 65 72 6e 20 61 72 67 75  the pattern argu
295b0 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 4c 49 4b  ment to the [LIK
295c0 45 5d 20 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 5d 20  E] or.** [GLOB] 
295d0 6f 70 65 72 61 74 6f 72 73 2e 3c 2f 64 64 3e 29  operators.</dd>)
295e0 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
295f0 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f  _LIMIT_VARIABLE_
29600 4e 55 4d 42 45 52 5d 5d 0a 2a 2a 20 5e 28 3c 64  NUMBER]].** ^(<d
29610 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  t>SQLITE_LIMIT_V
29620 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f  ARIABLE_NUMBER</
29630 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
29640 61 78 69 6d 75 6d 20 69 6e 64 65 78 20 6e 75 6d  aximum index num
29650 62 65 72 20 6f 66 20 61 6e 79 20 5b 70 61 72 61  ber of any [para
29660 6d 65 74 65 72 5d 20 69 6e 20 61 6e 20 53 51 4c  meter] in an SQL
29670 20 73 74 61 74 65 6d 65 6e 74 2e 29 5e 0a 2a 2a   statement.)^.**
29680 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
29690 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48  IT_TRIGGER_DEPTH
296a0 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
296b0 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45  LIMIT_TRIGGER_DE
296c0 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  PTH</dt>.** <dd>
296d0 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74  The maximum dept
296e0 68 20 6f 66 20 72 65 63 75 72 73 69 6f 6e 20 66  h of recursion f
296f0 6f 72 20 74 72 69 67 67 65 72 73 2e 3c 2f 64 64  or triggers.</dd
29700 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a  >)^.** </dl>.*/.
29710 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
29720 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20 20 20 20  IMIT_LENGTH     
29730 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
29740 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
29750 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48  LIMIT_SQL_LENGTH
29760 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
29770 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
29780 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20 20 20  _LIMIT_COLUMN   
29790 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
297a0 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
297b0 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50  E_LIMIT_EXPR_DEP
297c0 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TH              
297d0 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    3.#define SQLI
297e0 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e  TE_LIMIT_COMPOUN
297f0 44 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 20  D_SELECT        
29800 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c     4.#define SQL
29810 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f  ITE_LIMIT_VDBE_O
29820 50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  P               
29830 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51      5.#define SQ
29840 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54  LITE_LIMIT_FUNCT
29850 49 4f 4e 5f 41 52 47 20 20 20 20 20 20 20 20 20  ION_ARG         
29860 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53       6.#define S
29870 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41  QLITE_LIMIT_ATTA
29880 43 48 45 44 20 20 20 20 20 20 20 20 20 20 20 20  CHED            
29890 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20        7.#define 
298a0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b  SQLITE_LIMIT_LIK
298b0 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48  E_PATTERN_LENGTH
298c0 20 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65         8.#define
298d0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41   SQLITE_LIMIT_VA
298e0 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20 20 20  RIABLE_NUMBER   
298f0 20 20 20 20 20 20 20 20 39 0a 23 64 65 66 69 6e          9.#defin
29900 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54  e SQLITE_LIMIT_T
29910 52 49 47 47 45 52 5f 44 45 50 54 48 20 20 20 20  RIGGER_DEPTH    
29920 20 20 20 20 20 20 20 20 31 30 0a 0a 2f 2a 0a 2a          10../*.*
29930 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70  * CAPI3REF: Comp
29940 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20 53 74 61  iling An SQL Sta
29950 74 65 6d 65 6e 74 0a 2a 2a 20 4b 45 59 57 4f 52  tement.** KEYWOR
29960 44 53 3a 20 7b 53 51 4c 20 73 74 61 74 65 6d 65  DS: {SQL stateme
29970 6e 74 20 63 6f 6d 70 69 6c 65 72 7d 0a 2a 2a 0a  nt compiler}.**.
29980 2a 2a 20 54 6f 20 65 78 65 63 75 74 65 20 61 6e  ** To execute an
29990 20 53 51 4c 20 71 75 65 72 79 2c 20 69 74 20 6d   SQL query, it m
299a0 75 73 74 20 66 69 72 73 74 20 62 65 20 63 6f 6d  ust first be com
299b0 70 69 6c 65 64 20 69 6e 74 6f 20 61 20 62 79 74  piled into a byt
299c0 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f 67 72 61  e-code.** progra
299d0 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66 20 74  m using one of t
299e0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  hese routines..*
299f0 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  *.** The first a
29a00 72 67 75 6d 65 6e 74 2c 20 22 64 62 22 2c 20 69  rgument, "db", i
29a10 73 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  s a [database co
29a20 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 74 61 69 6e  nnection] obtain
29a30 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 70 72 69  ed from a.** pri
29a40 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20 63 61  or successful ca
29a50 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f  ll to [sqlite3_o
29a60 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  pen()], [sqlite3
29a70 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 6f 72 0a 2a  _open_v2()] or.*
29a80 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  * [sqlite3_open1
29a90 36 28 29 5d 2e 20 20 54 68 65 20 64 61 74 61 62  6()].  The datab
29aa0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d  ase connection m
29ab0 75 73 74 20 6e 6f 74 20 68 61 76 65 20 62 65 65  ust not have bee
29ac0 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20  n closed..**.** 
29ad0 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
29ae0 65 6e 74 2c 20 22 7a 53 71 6c 22 2c 20 69 73 20  ent, "zSql", is 
29af0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  the statement to
29b00 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c 20 65 6e   be compiled, en
29b10 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65 69 74 68  coded.** as eith
29b20 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d  er UTF-8 or UTF-
29b30 31 36 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  16.  The sqlite3
29b40 5f 70 72 65 70 61 72 65 28 29 20 61 6e 64 20 73  _prepare() and s
29b50 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
29b60 32 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  2().** interface
29b70 73 20 75 73 65 20 55 54 46 2d 38 2c 20 61 6e 64  s use UTF-8, and
29b80 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
29b90 31 36 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  16() and sqlite3
29ba0 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 0a  _prepare16_v2().
29bb0 2a 2a 20 75 73 65 20 55 54 46 2d 31 36 2e 0a 2a  ** use UTF-16..*
29bc0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e 42 79  *.** ^If the nBy
29bd0 74 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6c  te argument is l
29be0 65 73 73 20 74 68 61 6e 20 7a 65 72 6f 2c 20 74  ess than zero, t
29bf0 68 65 6e 20 7a 53 71 6c 20 69 73 20 72 65 61 64  hen zSql is read
29c00 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69   up to the.** fi
29c10 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  rst zero termina
29c20 74 6f 72 2e 20 5e 49 66 20 6e 42 79 74 65 20 69  tor. ^If nByte i
29c30 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20  s non-negative, 
29c40 74 68 65 6e 20 69 74 20 69 73 20 74 68 65 20 6d  then it is the m
29c50 61 78 69 6d 75 6d 0a 2a 2a 20 6e 75 6d 62 65 72  aximum.** number
29c60 20 6f 66 20 20 62 79 74 65 73 20 72 65 61 64 20   of  bytes read 
29c70 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 5e 57 68 65  from zSql.  ^Whe
29c80 6e 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e  n nByte is non-n
29c90 65 67 61 74 69 76 65 2c 20 74 68 65 0a 2a 2a 20  egative, the.** 
29ca0 7a 53 71 6c 20 73 74 72 69 6e 67 20 65 6e 64 73  zSql string ends
29cb0 20 61 74 20 65 69 74 68 65 72 20 74 68 65 20 66   at either the f
29cc0 69 72 73 74 20 27 5c 30 30 30 27 20 6f 72 20 27  irst '\000' or '
29cd0 5c 75 30 30 30 30 27 20 63 68 61 72 61 63 74 65  \u0000' characte
29ce0 72 20 6f 72 0a 2a 2a 20 74 68 65 20 6e 42 79 74  r or.** the nByt
29cf0 65 2d 74 68 20 62 79 74 65 2c 20 77 68 69 63 68  e-th byte, which
29d00 65 76 65 72 20 63 6f 6d 65 73 20 66 69 72 73 74  ever comes first
29d10 2e 20 49 66 20 74 68 65 20 63 61 6c 6c 65 72 20  . If the caller 
29d20 6b 6e 6f 77 73 0a 2a 2a 20 74 68 61 74 20 74 68  knows.** that th
29d30 65 20 73 75 70 70 6c 69 65 64 20 73 74 72 69 6e  e supplied strin
29d40 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d 69 6e 61  g is nul-termina
29d50 74 65 64 2c 20 74 68 65 6e 20 74 68 65 72 65 20  ted, then there 
29d60 69 73 20 61 20 73 6d 61 6c 6c 0a 2a 2a 20 70 65  is a small.** pe
29d70 72 66 6f 72 6d 61 6e 63 65 20 61 64 76 61 6e 74  rformance advant
29d80 61 67 65 20 74 6f 20 62 65 20 67 61 69 6e 65 64  age to be gained
29d90 20 62 79 20 70 61 73 73 69 6e 67 20 61 6e 20 6e   by passing an n
29da0 42 79 74 65 20 70 61 72 61 6d 65 74 65 72 20 74  Byte parameter t
29db0 68 61 74 0a 2a 2a 20 69 73 20 65 71 75 61 6c 20  hat.** is equal 
29dc0 74 6f 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  to the number of
29dd0 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 69 6e   bytes in the in
29de0 70 75 74 20 73 74 72 69 6e 67 20 3c 69 3e 69 6e  put string <i>in
29df0 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74  cluding</i>.** t
29e00 68 65 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 6f  he nul-terminato
29e10 72 20 62 79 74 65 73 20 61 73 20 74 68 69 73 20  r bytes as this 
29e20 73 61 76 65 73 20 53 51 4c 69 74 65 20 66 72 6f  saves SQLite fro
29e30 6d 20 68 61 76 69 6e 67 20 74 6f 0a 2a 2a 20 6d  m having to.** m
29e40 61 6b 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68  ake a copy of th
29e50 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 2e 0a  e input string..
29e60 2a 2a 0a 2a 2a 20 5e 49 66 20 70 7a 54 61 69 6c  **.** ^If pzTail
29e70 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65   is not NULL the
29e80 6e 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61 64  n *pzTail is mad
29e90 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68  e to point to th
29ea0 65 20 66 69 72 73 74 20 62 79 74 65 0a 2a 2a 20  e first byte.** 
29eb0 70 61 73 74 20 74 68 65 20 65 6e 64 20 6f 66 20  past the end of 
29ec0 74 68 65 20 66 69 72 73 74 20 53 51 4c 20 73 74  the first SQL st
29ed0 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e  atement in zSql.
29ee0 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73    These routines
29ef0 20 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65   only.** compile
29f00 20 74 68 65 20 66 69 72 73 74 20 73 74 61 74 65   the first state
29f10 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2c 20 73 6f  ment in zSql, so
29f20 20 2a 70 7a 54 61 69 6c 20 69 73 20 6c 65 66 74   *pzTail is left
29f30 20 70 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20   pointing to.** 
29f40 77 68 61 74 20 72 65 6d 61 69 6e 73 20 75 6e 63  what remains unc
29f50 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  ompiled..**.** ^
29f60 2a 70 70 53 74 6d 74 20 69 73 20 6c 65 66 74 20  *ppStmt is left 
29f70 70 6f 69 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f  pointing to a co
29f80 6d 70 69 6c 65 64 20 5b 70 72 65 70 61 72 65 64  mpiled [prepared
29f90 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
29fa0 20 63 61 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75   can be.** execu
29fb0 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ted using [sqlit
29fc0 65 33 5f 73 74 65 70 28 29 5d 2e 20 20 5e 49 66  e3_step()].  ^If
29fd0 20 74 68 65 72 65 20 69 73 20 61 6e 20 65 72 72   there is an err
29fe0 6f 72 2c 20 2a 70 70 53 74 6d 74 20 69 73 20 73  or, *ppStmt is s
29ff0 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20  et.** to NULL.  
2a000 5e 49 66 20 74 68 65 20 69 6e 70 75 74 20 74 65  ^If the input te
2a010 78 74 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53  xt contains no S
2a020 51 4c 20 28 69 66 20 74 68 65 20 69 6e 70 75 74  QL (if the input
2a030 20 69 73 20 61 6e 20 65 6d 70 74 79 0a 2a 2a 20   is an empty.** 
2a040 73 74 72 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d  string or a comm
2a050 65 6e 74 29 20 74 68 65 6e 20 2a 70 70 53 74 6d  ent) then *ppStm
2a060 74 20 69 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c  t is set to NULL
2a070 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 69 6e 67  ..** The calling
2a080 20 70 72 6f 63 65 64 75 72 65 20 69 73 20 72 65   procedure is re
2a090 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64 65  sponsible for de
2a0a0 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6d 70 69  leting the compi
2a0b0 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  led.** SQL state
2a0c0 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  ment using [sqli
2a0d0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
2a0e0 61 66 74 65 72 20 69 74 20 68 61 73 20 66 69 6e  after it has fin
2a0f0 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 0a 2a  ished with it..*
2a100 2a 20 70 70 53 74 6d 74 20 6d 61 79 20 6e 6f 74  * ppStmt may not
2a110 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   be NULL..**.** 
2a120 5e 4f 6e 20 73 75 63 63 65 73 73 2c 20 74 68 65  ^On success, the
2a130 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
2a140 28 29 20 66 61 6d 69 6c 79 20 6f 66 20 72 6f 75  () family of rou
2a150 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51  tines return [SQ
2a160 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68  LITE_OK];.** oth
2a170 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72  erwise an [error
2a180 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e   code] is return
2a190 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ed..**.** The sq
2a1a0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
2a1b0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70  () and sqlite3_p
2a1c0 72 65 70 61 72 65 31 36 5f 76 32 28 29 20 69 6e  repare16_v2() in
2a1d0 74 65 72 66 61 63 65 73 20 61 72 65 0a 2a 2a 20  terfaces are.** 
2a1e0 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20  recommended for 
2a1f0 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d 73  all new programs
2a200 2e 20 54 68 65 20 74 77 6f 20 6f 6c 64 65 72 20  . The two older 
2a210 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 72  interfaces are r
2a220 65 74 61 69 6e 65 64 0a 2a 2a 20 66 6f 72 20 62  etained.** for b
2a230 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69  ackwards compati
2a240 62 69 6c 69 74 79 2c 20 62 75 74 20 74 68 65 69  bility, but thei
2a250 72 20 75 73 65 20 69 73 20 64 69 73 63 6f 75 72  r use is discour
2a260 61 67 65 64 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65  aged..** ^In the
2a270 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 73   "v2" interfaces
2a280 2c 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73  , the prepared s
2a290 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74  tatement.** that
2a2a0 20 69 73 20 72 65 74 75 72 6e 65 64 20 28 74 68   is returned (th
2a2b0 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d  e [sqlite3_stmt]
2a2c0 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e   object) contain
2a2d0 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a  s a copy of the.
2a2e0 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20  ** original SQL 
2a2f0 74 65 78 74 2e 20 54 68 69 73 20 63 61 75 73 65  text. This cause
2a300 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  s the [sqlite3_s
2a310 74 65 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65  tep()] interface
2a320 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20 64 69   to.** behave di
2a330 66 66 65 72 65 6e 74 6c 79 20 69 6e 20 74 68 72  fferently in thr
2a340 65 65 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ee ways:.**.** <
2a350 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e  ol>.** <li>.** ^
2a360 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  If the database 
2a370 73 63 68 65 6d 61 20 63 68 61 6e 67 65 73 2c 20  schema changes, 
2a380 69 6e 73 74 65 61 64 20 6f 66 20 72 65 74 75 72  instead of retur
2a390 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43 48  ning [SQLITE_SCH
2a3a0 45 4d 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c  EMA] as it.** al
2a3b0 77 61 79 73 20 75 73 65 64 20 74 6f 20 64 6f 2c  ways used to do,
2a3c0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2a3d0 5d 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63  ] will automatic
2a3e0 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20 74  ally recompile t
2a3f0 68 65 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d  he SQL.** statem
2a400 65 6e 74 20 61 6e 64 20 74 72 79 20 74 6f 20 72  ent and try to r
2a410 75 6e 20 69 74 20 61 67 61 69 6e 2e 20 41 73 20  un it again. As 
2a420 6d 61 6e 79 20 61 73 20 5b 53 51 4c 49 54 45 5f  many as [SQLITE_
2a430 4d 41 58 5f 53 43 48 45 4d 41 5f 52 45 54 52 59  MAX_SCHEMA_RETRY
2a440 5d 0a 2a 2a 20 72 65 74 72 69 65 73 20 77 69 6c  ].** retries wil
2a450 6c 20 6f 63 63 75 72 20 62 65 66 6f 72 65 20 73  l occur before s
2a460 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 67 69  qlite3_step() gi
2a470 76 65 73 20 75 70 20 61 6e 64 20 72 65 74 75 72  ves up and retur
2a480 6e 73 20 61 6e 20 65 72 72 6f 72 2e 0a 2a 2a 20  ns an error..** 
2a490 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  </li>.**.** <li>
2a4a0 0a 2a 2a 20 5e 57 68 65 6e 20 61 6e 20 65 72 72  .** ^When an err
2a4b0 6f 72 20 6f 63 63 75 72 73 2c 20 5b 73 71 6c 69  or occurs, [sqli
2a4c0 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c  te3_step()] will
2a4d0 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 74   return one of t
2a4e0 68 65 20 64 65 74 61 69 6c 65 64 0a 2a 2a 20 5b  he detailed.** [
2a4f0 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 6f 72 20  error codes] or 
2a500 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20  [extended error 
2a510 63 6f 64 65 73 5d 2e 20 20 5e 54 68 65 20 6c 65  codes].  ^The le
2a520 67 61 63 79 20 62 65 68 61 76 69 6f 72 20 77 61  gacy behavior wa
2a530 73 20 74 68 61 74 0a 2a 2a 20 5b 73 71 6c 69 74  s that.** [sqlit
2a540 65 33 5f 73 74 65 70 28 29 5d 20 77 6f 75 6c 64  e3_step()] would
2a550 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20 61 20 67   only return a g
2a560 65 6e 65 72 69 63 20 5b 53 51 4c 49 54 45 5f 45  eneric [SQLITE_E
2a570 52 52 4f 52 5d 20 72 65 73 75 6c 74 20 63 6f 64  RROR] result cod
2a580 65 0a 2a 2a 20 61 6e 64 20 74 68 65 20 61 70 70  e.** and the app
2a590 6c 69 63 61 74 69 6f 6e 20 77 6f 75 6c 64 20 68  lication would h
2a5a0 61 76 65 20 74 6f 20 6d 61 6b 65 20 61 20 73 65  ave to make a se
2a5b0 63 6f 6e 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71  cond call to [sq
2a5c0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 0a 2a  lite3_reset()].*
2a5d0 2a 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69  * in order to fi
2a5e0 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e  nd the underlyin
2a5f0 67 20 63 61 75 73 65 20 6f 66 20 74 68 65 20 70  g cause of the p
2a600 72 6f 62 6c 65 6d 2e 20 57 69 74 68 20 74 68 65  roblem. With the
2a610 20 22 76 32 22 20 70 72 65 70 61 72 65 0a 2a 2a   "v2" prepare.**
2a620 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65   interfaces, the
2a630 20 75 6e 64 65 72 6c 79 69 6e 67 20 72 65 61 73   underlying reas
2a640 6f 6e 20 66 6f 72 20 74 68 65 20 65 72 72 6f 72  on for the error
2a650 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d   is returned imm
2a660 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c  ediately..** </l
2a670 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a  i>.**.** <li>.**
2a680 20 5e 49 66 20 74 68 65 20 73 70 65 63 69 66 69   ^If the specifi
2a690 63 20 76 61 6c 75 65 20 62 6f 75 6e 64 20 74 6f  c value bound to
2a6a0 20 5b 70 61 72 61 6d 65 74 65 72 20 7c 20 68 6f   [parameter | ho
2a6b0 73 74 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e  st parameter] in
2a6c0 20 74 68 65 20 0a 2a 2a 20 57 48 45 52 45 20 63   the .** WHERE c
2a6d0 6c 61 75 73 65 20 6d 69 67 68 74 20 69 6e 66 6c  lause might infl
2a6e0 75 65 6e 63 65 20 74 68 65 20 63 68 6f 69 63 65  uence the choice
2a6f0 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20 66   of query plan f
2a700 6f 72 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 0a  or a statement,.
2a710 2a 2a 20 74 68 65 6e 20 74 68 65 20 73 74 61 74  ** then the stat
2a720 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 61 75  ement will be au
2a730 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f  tomatically reco
2a740 6d 70 69 6c 65 64 2c 20 61 73 20 69 66 20 74 68  mpiled, as if th
2a750 65 72 65 20 68 61 64 20 62 65 65 6e 20 0a 2a 2a  ere had been .**
2a760 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65   a schema change
2a770 2c 20 6f 6e 20 74 68 65 20 66 69 72 73 74 20 20  , on the first  
2a780 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2a790 20 63 61 6c 6c 20 66 6f 6c 6c 6f 77 69 6e 67 20   call following 
2a7a0 61 6e 79 20 63 68 61 6e 67 65 0a 2a 2a 20 74 6f  any change.** to
2a7b0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69   the [sqlite3_bi
2a7c0 6e 64 5f 74 65 78 74 20 7c 20 62 69 6e 64 69 6e  nd_text | bindin
2a7d0 67 73 5d 20 6f 66 20 74 68 61 74 20 5b 70 61 72  gs] of that [par
2a7e0 61 6d 65 74 65 72 5d 2e 20 0a 2a 2a 20 5e 54 68  ameter]. .** ^Th
2a7f0 65 20 73 70 65 63 69 66 69 63 20 76 61 6c 75 65  e specific value
2a800 20 6f 66 20 57 48 45 52 45 2d 63 6c 61 75 73 65   of WHERE-clause
2a810 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 6d 69 67   [parameter] mig
2a820 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65  ht influence the
2a830 20 0a 2a 2a 20 63 68 6f 69 63 65 20 6f 66 20 71   .** choice of q
2a840 75 65 72 79 20 70 6c 61 6e 20 69 66 20 74 68 65  uery plan if the
2a850 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
2a860 65 20 6c 65 66 74 2d 68 61 6e 64 20 73 69 64 65  e left-hand side
2a870 20 6f 66 20 61 20 5b 4c 49 4b 45 5d 0a 2a 2a 20   of a [LIKE].** 
2a880 6f 72 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74  or [GLOB] operat
2a890 6f 72 20 6f 72 20 69 66 20 74 68 65 20 70 61 72  or or if the par
2a8a0 61 6d 65 74 65 72 20 69 73 20 63 6f 6d 70 61 72  ameter is compar
2a8b0 65 64 20 74 6f 20 61 6e 20 69 6e 64 65 78 65 64  ed to an indexed
2a8c0 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 6e 64 20 74   column.** and t
2a8d0 68 65 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  he [SQLITE_ENABL
2a8e0 45 5f 53 54 41 54 33 5d 20 63 6f 6d 70 69 6c 65  E_STAT3] compile
2a8f0 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20  -time option is 
2a900 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 74 68 65 20  enabled..** the 
2a910 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f  .** </li>.** </o
2a920 6c 3e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  l>.*/.SQLITE_API
2a930 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65   int sqlite3_pre
2a940 70 61 72 65 28 0a 20 20 73 71 6c 69 74 65 33 20  pare(.  sqlite3 
2a950 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
2a960 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64  /* Database hand
2a970 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  le */.  const ch
2a980 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20  ar *zSql,       
2a990 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  /* SQL statement
2a9a0 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20  , UTF-8 encoded 
2a9b0 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20  */.  int nByte, 
2a9c0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
2a9d0 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  Maximum length o
2a9e0 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e  f zSql in bytes.
2a9f0 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74   */.  sqlite3_st
2aa00 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a  mt **ppStmt,  /*
2aa10 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20   OUT: Statement 
2aa20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
2aa30 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20  t char **pzTail 
2aa40 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e      /* OUT: Poin
2aa50 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f  ter to unused po
2aa60 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f  rtion of zSql */
2aa70 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .);.SQLITE_API i
2aa80 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nt sqlite3_prepa
2aa90 72 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33  re_v2(.  sqlite3
2aaa0 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
2aab0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
2aac0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
2aad0 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  har *zSql,      
2aae0 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
2aaf0 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64  t, UTF-8 encoded
2ab00 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c   */.  int nByte,
2ab10 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
2ab20 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   Maximum length 
2ab30 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73  of zSql in bytes
2ab40 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73  . */.  sqlite3_s
2ab50 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f  tmt **ppStmt,  /
2ab60 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74  * OUT: Statement
2ab70 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
2ab80 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c  st char **pzTail
2ab90 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69       /* OUT: Poi
2aba0 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70  nter to unused p
2abb0 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a  ortion of zSql *
2abc0 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  /.);.SQLITE_API 
2abd0 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70  int sqlite3_prep
2abe0 61 72 65 31 36 28 0a 20 20 73 71 6c 69 74 65 33  are16(.  sqlite3
2abf0 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
2ac00 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
2ac10 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  dle */.  const v
2ac20 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  oid *zSql,      
2ac30 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
2ac40 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65  t, UTF-16 encode
2ac50 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
2ac60 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
2ac70 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
2ac80 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
2ac90 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  s. */.  sqlite3_
2aca0 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
2acb0 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
2acc0 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
2acd0 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69  nst void **pzTai
2ace0 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
2acf0 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
2ad00 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
2ad10 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  */.);.SQLITE_API
2ad20 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65   int sqlite3_pre
2ad30 70 61 72 65 31 36 5f 76 32 28 0a 20 20 73 71 6c  pare16_v2(.  sql
2ad40 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
2ad50 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
2ad60 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
2ad70 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20  st void *zSql,  
2ad80 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74       /* SQL stat
2ad90 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e  ement, UTF-16 en
2ada0 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e  coded */.  int n
2adb0 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20  Byte,           
2adc0 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65     /* Maximum le
2add0 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20  ngth of zSql in 
2ade0 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69  bytes. */.  sqli
2adf0 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d  te3_stmt **ppStm
2ae00 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74  t,  /* OUT: Stat
2ae10 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a  ement handle */.
2ae20 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70    const void **p
2ae30 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54  zTail     /* OUT
2ae40 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75  : Pointer to unu
2ae50 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a  sed portion of z
2ae60 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  Sql */.);../*.**
2ae70 20 43 41 50 49 33 52 45 46 3a 20 52 65 74 72 69   CAPI3REF: Retri
2ae80 65 76 69 6e 67 20 53 74 61 74 65 6d 65 6e 74 20  eving Statement 
2ae90 53 51 4c 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  SQL.**.** ^This 
2aea0 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65  interface can be
2aeb0 20 75 73 65 64 20 74 6f 20 72 65 74 72 69 65 76   used to retriev
2aec0 65 20 61 20 73 61 76 65 64 20 63 6f 70 79 20 6f  e a saved copy o
2aed0 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 0a 2a  f the original.*
2aee0 2a 20 53 51 4c 20 74 65 78 74 20 75 73 65 64 20  * SQL text used 
2aef0 74 6f 20 63 72 65 61 74 65 20 61 20 5b 70 72 65  to create a [pre
2af00 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2af10 20 69 66 20 74 68 61 74 20 73 74 61 74 65 6d 65   if that stateme
2af20 6e 74 20 77 61 73 0a 2a 2a 20 63 6f 6d 70 69 6c  nt was.** compil
2af30 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 20  ed using either 
2af40 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2af50 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  _v2()] or [sqlit
2af60 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
2af70 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  )]..*/.SQLITE_AP
2af80 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  I const char *sq
2af90 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c 69 74 65  lite3_sql(sqlite
2afa0 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
2afb0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2afc0 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e   Determine If An
2afd0 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 57   SQL Statement W
2afe0 72 69 74 65 73 20 54 68 65 20 44 61 74 61 62 61  rites The Databa
2aff0 73 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  se.**.** ^The sq
2b000 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f  lite3_stmt_reado
2b010 6e 6c 79 28 58 29 20 69 6e 74 65 72 66 61 63 65  nly(X) interface
2b020 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 6e   returns true (n
2b030 6f 6e 2d 7a 65 72 6f 29 20 69 66 0a 2a 2a 20 61  on-zero) if.** a
2b040 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 5b  nd only if the [
2b050 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2b060 6e 74 5d 20 58 20 6d 61 6b 65 73 20 6e 6f 20 64  nt] X makes no d
2b070 69 72 65 63 74 20 63 68 61 6e 67 65 73 20 74 6f  irect changes to
2b080 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  .** the content 
2b090 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
2b0a0 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65  file..**.** Note
2b0b0 20 74 68 61 74 20 5b 61 70 70 6c 69 63 61 74 69   that [applicati
2b0c0 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
2b0d0 75 6e 63 74 69 6f 6e 73 5d 20 6f 72 0a 2a 2a 20  unctions] or.** 
2b0e0 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 5d  [virtual tables]
2b0f0 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20 74 68   might change th
2b100 65 20 64 61 74 61 62 61 73 65 20 69 6e 64 69 72  e database indir
2b110 65 63 74 6c 79 20 61 73 20 61 20 73 69 64 65 20  ectly as a side 
2b120 65 66 66 65 63 74 2e 20 20 0a 2a 2a 20 5e 28 46  effect.  .** ^(F
2b130 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 61  or example, if a
2b140 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65  n application de
2b150 66 69 6e 65 73 20 61 20 66 75 6e 63 74 69 6f 6e  fines a function
2b160 20 22 65 76 61 6c 28 29 22 20 74 68 61 74 20 0a   "eval()" that .
2b170 2a 2a 20 63 61 6c 6c 73 20 5b 73 71 6c 69 74 65  ** calls [sqlite
2b180 33 5f 65 78 65 63 28 29 5d 2c 20 74 68 65 6e 20  3_exec()], then 
2b190 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51  the following SQ
2b1a0 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 6f 75 6c  L statement woul
2b1b0 64 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20  d.** change the 
2b1c0 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 68  database file th
2b1d0 72 6f 75 67 68 20 73 69 64 65 2d 65 66 66 65 63  rough side-effec
2b1e0 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ts:.**.** <block
2b1f0 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
2b200 20 20 53 45 4c 45 43 54 20 65 76 61 6c 28 27 44    SELECT eval('D
2b210 45 4c 45 54 45 20 46 52 4f 4d 20 74 31 27 29 20  ELETE FROM t1') 
2b220 46 52 4f 4d 20 74 32 3b 0a 2a 2a 20 3c 2f 70 72  FROM t2;.** </pr
2b230 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
2b240 2a 2a 0a 2a 2a 20 42 75 74 20 62 65 63 61 75 73  **.** But becaus
2b250 65 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73  e the [SELECT] s
2b260 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f  tatement does no
2b270 74 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74  t change the dat
2b280 61 62 61 73 65 20 66 69 6c 65 0a 2a 2a 20 64 69  abase file.** di
2b290 72 65 63 74 6c 79 2c 20 73 71 6c 69 74 65 33 5f  rectly, sqlite3_
2b2a0 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20  stmt_readonly() 
2b2b0 77 6f 75 6c 64 20 73 74 69 6c 6c 20 72 65 74 75  would still retu
2b2c0 72 6e 20 74 72 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a  rn true.)^.**.**
2b2d0 20 5e 54 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f   ^Transaction co
2b2e0 6e 74 72 6f 6c 20 73 74 61 74 65 6d 65 6e 74 73  ntrol statements
2b2f0 20 73 75 63 68 20 61 73 20 5b 42 45 47 49 4e 5d   such as [BEGIN]
2b300 2c 20 5b 43 4f 4d 4d 49 54 5d 2c 20 5b 52 4f 4c  , [COMMIT], [ROL
2b310 4c 42 41 43 4b 5d 2c 0a 2a 2a 20 5b 53 41 56 45  LBACK],.** [SAVE
2b320 50 4f 49 4e 54 5d 2c 20 61 6e 64 20 5b 52 45 4c  POINT], and [REL
2b330 45 41 53 45 5d 20 63 61 75 73 65 20 73 71 6c 69  EASE] cause sqli
2b340 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c  te3_stmt_readonl
2b350 79 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72  y() to return tr
2b360 75 65 2c 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65  ue,.** since the
2b370 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 65 6d   statements them
2b380 73 65 6c 76 65 73 20 64 6f 20 6e 6f 74 20 61 63  selves do not ac
2b390 74 75 61 6c 6c 79 20 6d 6f 64 69 66 79 20 74 68  tually modify th
2b3a0 65 20 64 61 74 61 62 61 73 65 20 62 75 74 0a 2a  e database but.*
2b3b0 2a 20 72 61 74 68 65 72 20 74 68 65 79 20 63 6f  * rather they co
2b3c0 6e 74 72 6f 6c 20 74 68 65 20 74 69 6d 69 6e 67  ntrol the timing
2b3d0 20 6f 66 20 77 68 65 6e 20 6f 74 68 65 72 20 73   of when other s
2b3e0 74 61 74 65 6d 65 6e 74 73 20 6d 6f 64 69 66 79  tatements modify
2b3f0 20 74 68 65 20 0a 2a 2a 20 64 61 74 61 62 61 73   the .** databas
2b400 65 2e 20 20 5e 54 68 65 20 5b 41 54 54 41 43 48  e.  ^The [ATTACH
2b410 5d 20 61 6e 64 20 5b 44 45 54 41 43 48 5d 20 73  ] and [DETACH] s
2b420 74 61 74 65 6d 65 6e 74 73 20 61 6c 73 6f 20 63  tatements also c
2b430 61 75 73 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ause.** sqlite3_
2b440 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20  stmt_readonly() 
2b450 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65 20 73  to return true s
2b460 69 6e 63 65 2c 20 77 68 69 6c 65 20 74 68 6f 73  ince, while thos
2b470 65 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  e statements.** 
2b480 63 68 61 6e 67 65 20 74 68 65 20 63 6f 6e 66 69  change the confi
2b490 67 75 72 61 74 69 6f 6e 20 6f 66 20 61 20 64 61  guration of a da
2b4a0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2b4b0 6e 2c 20 74 68 65 79 20 64 6f 20 6e 6f 74 20 6d  n, they do not m
2b4c0 61 6b 65 20 0a 2a 2a 20 63 68 61 6e 67 65 73 20  ake .** changes 
2b4d0 74 6f 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f  to the content o
2b4e0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  f the database f
2b4f0 69 6c 65 73 20 6f 6e 20 64 69 73 6b 2e 0a 2a 2f  iles on disk..*/
2b500 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
2b510 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61  sqlite3_stmt_rea
2b520 64 6f 6e 6c 79 28 73 71 6c 69 74 65 33 5f 73 74  donly(sqlite3_st
2b530 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
2b540 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74  ** CAPI3REF: Det
2b550 65 72 6d 69 6e 65 20 49 66 20 41 20 50 72 65 70  ermine If A Prep
2b560 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 48  ared Statement H
2b570 61 73 20 42 65 65 6e 20 52 65 73 65 74 0a 2a 2a  as Been Reset.**
2b580 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2b590 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 20 69 6e  _stmt_busy(S) in
2b5a0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
2b5b0 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20  true (non-zero) 
2b5c0 69 66 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  if the.** [prepa
2b5d0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
2b5e0 20 68 61 73 20 62 65 65 6e 20 73 74 65 70 70 65   has been steppe
2b5f0 64 20 61 74 20 6c 65 61 73 74 20 6f 6e 63 65 20  d at least once 
2b600 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74  using .** [sqlit
2b610 65 33 5f 73 74 65 70 28 53 29 5d 20 62 75 74 20  e3_step(S)] but 
2b620 68 61 73 20 6e 6f 74 20 72 75 6e 20 74 6f 20 63  has not run to c
2b630 6f 6d 70 6c 65 74 69 6f 6e 20 61 6e 64 2f 6f 72  ompletion and/or
2b640 20 68 61 73 20 6e 6f 74 20 0a 2a 2a 20 62 65 65   has not .** bee
2b650 6e 20 72 65 73 65 74 20 75 73 69 6e 67 20 5b 73  n reset using [s
2b660 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d  qlite3_reset(S)]
2b670 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
2b680 73 74 6d 74 5f 62 75 73 79 28 53 29 0a 2a 2a 20  stmt_busy(S).** 
2b690 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
2b6a0 73 20 66 61 6c 73 65 20 69 66 20 53 20 69 73 20  s false if S is 
2b6b0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20  a NULL pointer. 
2b6c0 20 49 66 20 53 20 69 73 20 6e 6f 74 20 61 20 0a   If S is not a .
2b6d0 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20  ** NULL pointer 
2b6e0 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 6f 69  and is not a poi
2b6f0 6e 74 65 72 20 74 6f 20 61 20 76 61 6c 69 64 20  nter to a valid 
2b700 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2b710 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2c 20  ent].** object, 
2b720 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
2b730 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61  r is undefined a
2b740 6e 64 20 70 72 6f 62 61 62 6c 79 20 75 6e 64 65  nd probably unde
2b750 73 69 72 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54  sirable..**.** T
2b760 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61  his interface ca
2b770 6e 20 62 65 20 75 73 65 64 20 69 6e 20 63 6f 6d  n be used in com
2b780 62 69 6e 61 74 69 6f 6e 20 5b 73 71 6c 69 74 65  bination [sqlite
2b790 33 5f 6e 65 78 74 5f 73 74 6d 74 28 29 5d 0a 2a  3_next_stmt()].*
2b7a0 2a 20 74 6f 20 6c 6f 63 61 74 65 20 61 6c 6c 20  * to locate all 
2b7b0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2b7c0 6e 74 73 20 61 73 73 6f 63 69 61 74 65 64 20 77  nts associated w
2b7d0 69 74 68 20 61 20 64 61 74 61 62 61 73 65 20 0a  ith a database .
2b7e0 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  ** connection th
2b7f0 61 74 20 61 72 65 20 69 6e 20 6e 65 65 64 20 6f  at are in need o
2b800 66 20 62 65 69 6e 67 20 72 65 73 65 74 2e 20 20  f being reset.  
2b810 54 68 69 73 20 63 61 6e 20 62 65 20 75 73 65 64  This can be used
2b820 2c 0a 2a 2a 20 66 6f 72 20 65 78 61 6d 70 6c 65  ,.** for example
2b830 2c 20 69 6e 20 64 69 61 67 6e 6f 73 74 69 63 20  , in diagnostic 
2b840 72 6f 75 74 69 6e 65 73 20 74 6f 20 73 65 61 72  routines to sear
2b850 63 68 20 66 6f 72 20 70 72 65 70 61 72 65 64 20  ch for prepared 
2b860 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 74  .** statements t
2b870 68 61 74 20 61 72 65 20 68 6f 6c 64 69 6e 67 20  hat are holding 
2b880 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 6f 70  a transaction op
2b890 65 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  en..*/.SQLITE_AP
2b8a0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74  I int sqlite3_st
2b8b0 6d 74 5f 62 75 73 79 28 73 71 6c 69 74 65 33 5f  mt_busy(sqlite3_
2b8c0 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  stmt*);../*.** C
2b8d0 41 50 49 33 52 45 46 3a 20 44 79 6e 61 6d 69 63  API3REF: Dynamic
2b8e0 61 6c 6c 79 20 54 79 70 65 64 20 56 61 6c 75 65  ally Typed Value
2b8f0 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f   Object.** KEYWO
2b900 52 44 53 3a 20 7b 70 72 6f 74 65 63 74 65 64 20  RDS: {protected 
2b910 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 20 7b  sqlite3_value} {
2b920 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
2b930 74 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a  te3_value}.**.**
2b940 20 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65   SQLite uses the
2b950 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
2b960 62 6a 65 63 74 20 74 6f 20 72 65 70 72 65 73 65  bject to represe
2b970 6e 74 20 61 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a  nt all values.**
2b980 20 74 68 61 74 20 63 61 6e 20 62 65 20 73 74 6f   that can be sto
2b990 72 65 64 20 69 6e 20 61 20 64 61 74 61 62 61 73  red in a databas
2b9a0 65 20 74 61 62 6c 65 2e 20 53 51 4c 69 74 65 20  e table. SQLite 
2b9b0 75 73 65 73 20 64 79 6e 61 6d 69 63 20 74 79 70  uses dynamic typ
2b9c0 69 6e 67 0a 2a 2a 20 66 6f 72 20 74 68 65 20 76  ing.** for the v
2b9d0 61 6c 75 65 73 20 69 74 20 73 74 6f 72 65 73 2e  alues it stores.
2b9e0 20 20 5e 56 61 6c 75 65 73 20 73 74 6f 72 65 64    ^Values stored
2b9f0 20 69 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75   in sqlite3_valu
2ba00 65 20 6f 62 6a 65 63 74 73 0a 2a 2a 20 63 61 6e  e objects.** can
2ba10 20 62 65 20 69 6e 74 65 67 65 72 73 2c 20 66 6c   be integers, fl
2ba20 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c  oating point val
2ba30 75 65 73 2c 20 73 74 72 69 6e 67 73 2c 20 42 4c  ues, strings, BL
2ba40 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a  OBs, or NULL..**
2ba50 0a 2a 2a 20 41 6e 20 73 71 6c 69 74 65 33 5f 76  .** An sqlite3_v
2ba60 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61 79 20  alue object may 
2ba70 62 65 20 65 69 74 68 65 72 20 22 70 72 6f 74 65  be either "prote
2ba80 63 74 65 64 22 20 6f 72 20 22 75 6e 70 72 6f 74  cted" or "unprot
2ba90 65 63 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20  ected"..** Some 
2baa0 69 6e 74 65 72 66 61 63 65 73 20 72 65 71 75 69  interfaces requi
2bab0 72 65 20 61 20 70 72 6f 74 65 63 74 65 64 20 73  re a protected s
2bac0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20 20 4f  qlite3_value.  O
2bad0 74 68 65 72 20 69 6e 74 65 72 66 61 63 65 73 0a  ther interfaces.
2bae0 2a 2a 20 77 69 6c 6c 20 61 63 63 65 70 74 20 65  ** will accept e
2baf0 69 74 68 65 72 20 61 20 70 72 6f 74 65 63 74 65  ither a protecte
2bb00 64 20 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63  d or an unprotec
2bb10 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
2bb20 65 2e 0a 2a 2a 20 45 76 65 72 79 20 69 6e 74 65  e..** Every inte
2bb30 72 66 61 63 65 20 74 68 61 74 20 61 63 63 65 70  rface that accep
2bb40 74 73 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ts sqlite3_value
2bb50 20 61 72 67 75 6d 65 6e 74 73 20 73 70 65 63 69   arguments speci
2bb60 66 69 65 73 0a 2a 2a 20 77 68 65 74 68 65 72 20  fies.** whether 
2bb70 6f 72 20 6e 6f 74 20 69 74 20 72 65 71 75 69 72  or not it requir
2bb80 65 73 20 61 20 70 72 6f 74 65 63 74 65 64 20 73  es a protected s
2bb90 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a  qlite3_value..**
2bba0 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73 20 22 70  .** The terms "p
2bbb0 72 6f 74 65 63 74 65 64 22 20 61 6e 64 20 22 75  rotected" and "u
2bbc0 6e 70 72 6f 74 65 63 74 65 64 22 20 72 65 66 65  nprotected" refe
2bbd0 72 20 74 6f 20 77 68 65 74 68 65 72 20 6f 72 20  r to whether or 
2bbe0 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78 20 69  not.** a mutex i
2bbf0 73 20 68 65 6c 64 2e 20 20 41 6e 20 69 6e 74 65  s held.  An inte
2bc00 72 6e 61 6c 20 6d 75 74 65 78 20 69 73 20 68 65  rnal mutex is he
2bc10 6c 64 20 66 6f 72 20 61 20 70 72 6f 74 65 63 74  ld for a protect
2bc20 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  ed.** sqlite3_va
2bc30 6c 75 65 20 6f 62 6a 65 63 74 20 62 75 74 20 6e  lue object but n
2bc40 6f 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20  o mutex is held 
2bc50 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74  for an unprotect
2bc60 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  ed.** sqlite3_va
2bc70 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20 49 66 20  lue object.  If 
2bc80 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
2bc90 65 64 20 74 6f 20 62 65 20 73 69 6e 67 6c 65 2d  ed to be single-
2bca0 74 68 72 65 61 64 65 64 0a 2a 2a 20 28 77 69 74  threaded.** (wit
2bcb0 68 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  h [SQLITE_THREAD
2bcc0 53 41 46 45 3d 30 5d 20 61 6e 64 20 77 69 74 68  SAFE=0] and with
2bcd0 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64   [sqlite3_thread
2bce0 73 61 66 65 28 29 5d 20 72 65 74 75 72 6e 69 6e  safe()] returnin
2bcf0 67 20 30 29 0a 2a 2a 20 6f 72 20 69 66 20 53 51  g 0).** or if SQ
2bd00 4c 69 74 65 20 69 73 20 72 75 6e 20 69 6e 20 6f  Lite is run in o
2bd10 6e 65 20 6f 66 20 72 65 64 75 63 65 64 20 6d 75  ne of reduced mu
2bd20 74 65 78 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53  tex modes .** [S
2bd30 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
2bd40 47 4c 45 54 48 52 45 41 44 5d 20 6f 72 20 5b 53  GLETHREAD] or [S
2bd50 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
2bd60 54 49 54 48 52 45 41 44 5d 0a 2a 2a 20 74 68 65  TITHREAD].** the
2bd70 6e 20 74 68 65 72 65 20 69 73 20 6e 6f 20 64 69  n there is no di
2bd80 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65  stinction betwee
2bd90 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20  n protected and 
2bda0 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  unprotected.** s
2bdb0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
2bdc0 65 63 74 73 20 61 6e 64 20 74 68 65 79 20 63 61  ects and they ca
2bdd0 6e 20 62 65 20 75 73 65 64 20 69 6e 74 65 72 63  n be used interc
2bde0 68 61 6e 67 65 61 62 6c 79 2e 20 20 48 6f 77 65  hangeably.  Howe
2bdf0 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78 69  ver,.** for maxi
2be00 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74 61 62 69  mum code portabi
2be10 6c 69 74 79 20 69 74 20 69 73 20 72 65 63 6f 6d  lity it is recom
2be20 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c  mended that appl
2be30 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c  ications.** stil
2be40 6c 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69  l make the disti
2be50 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70  nction between p
2be60 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70  rotected and unp
2be70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69  rotected.** sqli
2be80 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
2be90 73 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74 20  s even when not 
2bea0 73 74 72 69 63 74 6c 79 20 72 65 71 75 69 72 65  strictly require
2beb0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  d..**.** ^The sq
2bec0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
2bed0 63 74 73 20 74 68 61 74 20 61 72 65 20 70 61 73  cts that are pas
2bee0 73 65 64 20 61 73 20 70 61 72 61 6d 65 74 65 72  sed as parameter
2bef0 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d  s into the.** im
2bf00 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
2bf10 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  [application-def
2bf20 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
2bf30 6e 73 5d 20 61 72 65 20 70 72 6f 74 65 63 74 65  ns] are protecte
2bf40 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  d..** ^The sqlit
2bf50 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20  e3_value object 
2bf60 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b  returned by.** [
2bf70 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76  sqlite3_column_v
2bf80 61 6c 75 65 28 29 5d 20 69 73 20 75 6e 70 72 6f  alue()] is unpro
2bf90 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f  tected..** Unpro
2bfa0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2bfb0 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d 61 79  alue objects may
2bfc0 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69   only be used wi
2bfd0 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  th.** [sqlite3_r
2bfe0 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20 61  esult_value()] a
2bff0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  nd [sqlite3_bind
2c000 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54 68  _value()]..** Th
2c010 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
2c020 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f  _blob | sqlite3_
2c030 76 61 6c 75 65 5f 74 79 70 65 28 29 5d 20 66 61  value_type()] fa
2c040 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72  mily of.** inter
2c050 66 61 63 65 73 20 72 65 71 75 69 72 65 20 70 72  faces require pr
2c060 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2c070 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a  value objects..*
2c080 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
2c090 20 4d 65 6d 20 73 71 6c 69 74 65 33 5f 76 61 6c   Mem sqlite3_val
2c0a0 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  ue;../*.** CAPI3
2c0b0 52 45 46 3a 20 53 51 4c 20 46 75 6e 63 74 69 6f  REF: SQL Functio
2c0c0 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74  n Context Object
2c0d0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65  .**.** The conte
2c0e0 78 74 20 69 6e 20 77 68 69 63 68 20 61 6e 20 53  xt in which an S
2c0f0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78 65 63  QL function exec
2c100 75 74 65 73 20 69 73 20 73 74 6f 72 65 64 20 69  utes is stored i
2c110 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  n an.** sqlite3_
2c120 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e 20  context object. 
2c130 20 5e 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61   ^A pointer to a
2c140 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  n sqlite3_contex
2c150 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 73 20 61  t object.** is a
2c160 6c 77 61 79 73 20 66 69 72 73 74 20 70 61 72 61  lways first para
2c170 6d 65 74 65 72 20 74 6f 20 5b 61 70 70 6c 69 63  meter to [applic
2c180 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
2c190 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a  L functions]..**
2c1a0 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
2c1b0 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
2c1c0 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  ction implementa
2c1d0 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73 73 20 74  tion will pass t
2c1e0 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74  his.** pointer t
2c1f0 68 72 6f 75 67 68 20 69 6e 74 6f 20 63 61 6c 6c  hrough into call
2c200 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  s to [sqlite3_re
2c210 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71 6c 69 74  sult_int | sqlit
2c220 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a  e3_result()],.**
2c230 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67   [sqlite3_aggreg
2c240 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 5d 2c 20  ate_context()], 
2c250 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61  [sqlite3_user_da
2c260 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  ta()],.** [sqlit
2c270 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61  e3_context_db_ha
2c280 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65  ndle()], [sqlite
2c290 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 5d  3_get_auxdata()]
2c2a0 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73 71 6c  ,.** and/or [sql
2c2b0 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
2c2c0 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ()]..*/.typedef 
2c2d0 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 63  struct sqlite3_c
2c2e0 6f 6e 74 65 78 74 20 73 71 6c 69 74 65 33 5f 63  ontext sqlite3_c
2c2f0 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ontext;../*.** C
2c300 41 50 49 33 52 45 46 3a 20 42 69 6e 64 69 6e 67  API3REF: Binding
2c310 20 56 61 6c 75 65 73 20 54 6f 20 50 72 65 70 61   Values To Prepa
2c320 72 65 64 20 53 74 61 74 65 6d 65 6e 74 73 0a 2a  red Statements.*
2c330 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 68 6f 73  * KEYWORDS: {hos
2c340 74 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 68 6f  t parameter} {ho
2c350 73 74 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b  st parameters} {
2c360 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e  host parameter n
2c370 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ame}.** KEYWORDS
2c380 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72  : {SQL parameter
2c390 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72  } {SQL parameter
2c3a0 73 7d 20 7b 70 61 72 61 6d 65 74 65 72 20 62 69  s} {parameter bi
2c3b0 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a 20 5e 28 49  nding}.**.** ^(I
2c3c0 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  n the SQL statem
2c3d0 65 6e 74 20 74 65 78 74 20 69 6e 70 75 74 20 74  ent text input t
2c3e0 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  o [sqlite3_prepa
2c3f0 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 69 74 73  re_v2()] and its
2c400 20 76 61 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69   variants,.** li
2c410 74 65 72 61 6c 73 20 6d 61 79 20 62 65 20 72 65  terals may be re
2c420 70 6c 61 63 65 64 20 62 79 20 61 20 5b 70 61 72  placed by a [par
2c430 61 6d 65 74 65 72 5d 20 74 68 61 74 20 6d 61 74  ameter] that mat
2c440 63 68 65 73 20 6f 6e 65 20 6f 66 20 66 6f 6c 6c  ches one of foll
2c450 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d 70 6c 61 74  owing.** templat
2c460 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  es:.**.** <ul>.*
2c470 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69  * <li>  ?.** <li
2c480 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20  >  ?NNN.** <li> 
2c490 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40   :VVV.** <li>  @
2c4a0 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56 56  VVV.** <li>  $VV
2c4b0 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  V.** </ul>.**.**
2c4c0 20 49 6e 20 74 68 65 20 74 65 6d 70 6c 61 74 65   In the template
2c4d0 73 20 61 62 6f 76 65 2c 20 4e 4e 4e 20 72 65 70  s above, NNN rep
2c4e0 72 65 73 65 6e 74 73 20 61 6e 20 69 6e 74 65 67  resents an integ
2c4f0 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20 61  er literal,.** a
2c500 6e 64 20 56 56 56 20 72 65 70 72 65 73 65 6e 74  nd VVV represent
2c510 73 20 61 6e 20 61 6c 70 68 61 6e 75 6d 65 72 69  s an alphanumeri
2c520 63 20 69 64 65 6e 74 69 66 69 65 72 2e 29 5e 20  c identifier.)^ 
2c530 20 5e 54 68 65 20 76 61 6c 75 65 73 20 6f 66 20   ^The values of 
2c540 74 68 65 73 65 0a 2a 2a 20 70 61 72 61 6d 65 74  these.** paramet
2c550 65 72 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65 64  ers (also called
2c560 20 22 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72   "host parameter
2c570 20 6e 61 6d 65 73 22 20 6f 72 20 22 53 51 4c 20   names" or "SQL 
2c580 70 61 72 61 6d 65 74 65 72 73 22 29 0a 2a 2a 20  parameters").** 
2c590 63 61 6e 20 62 65 20 73 65 74 20 75 73 69 6e 67  can be set using
2c5a0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   the sqlite3_bin
2c5b0 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 64  d_*() routines d
2c5c0 65 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a  efined here..**.
2c5d0 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  ** ^The first ar
2c5e0 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71  gument to the sq
2c5f0 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72  lite3_bind_*() r
2c600 6f 75 74 69 6e 65 73 20 69 73 20 61 6c 77 61 79  outines is alway
2c610 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74  s.** a pointer t
2c620 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  o the [sqlite3_s
2c630 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65 74 75  tmt] object retu
2c640 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71  rned from.** [sq
2c650 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
2c660 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61  ()] or its varia
2c670 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  nts..**.** ^The 
2c680 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
2c690 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20  is the index of 
2c6a0 74 68 65 20 53 51 4c 20 70 61 72 61 6d 65 74 65  the SQL paramete
2c6b0 72 20 74 6f 20 62 65 20 73 65 74 2e 0a 2a 2a 20  r to be set..** 
2c6c0 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 53 51  ^The leftmost SQ
2c6d0 4c 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20  L parameter has 
2c6e0 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2e 20 20  an index of 1.  
2c6f0 5e 57 68 65 6e 20 74 68 65 20 73 61 6d 65 20 6e  ^When the same n
2c700 61 6d 65 64 0a 2a 2a 20 53 51 4c 20 70 61 72 61  amed.** SQL para
2c710 6d 65 74 65 72 20 69 73 20 75 73 65 64 20 6d 6f  meter is used mo
2c720 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 73 65  re than once, se
2c730 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75  cond and subsequ
2c740 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65 6e 63  ent.** occurrenc
2c750 65 73 20 68 61 76 65 20 74 68 65 20 73 61 6d 65  es have the same
2c760 20 69 6e 64 65 78 20 61 73 20 74 68 65 20 66 69   index as the fi
2c770 72 73 74 20 6f 63 63 75 72 72 65 6e 63 65 2e 0a  rst occurrence..
2c780 2a 2a 20 5e 54 68 65 20 69 6e 64 65 78 20 66 6f  ** ^The index fo
2c790 72 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65  r named paramete
2c7a0 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f 6b 65 64  rs can be looked
2c7b0 20 75 70 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a   up using the.**
2c7c0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
2c7d0 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29  arameter_index()
2c7e0 5d 20 41 50 49 20 69 66 20 64 65 73 69 72 65 64  ] API if desired
2c7f0 2e 20 20 5e 54 68 65 20 69 6e 64 65 78 0a 2a 2a  .  ^The index.**
2c800 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61 72 61   for "?NNN" para
2c810 6d 65 74 65 72 73 20 69 73 20 74 68 65 20 76 61  meters is the va
2c820 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e  lue of NNN..** ^
2c830 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d 75  The NNN value mu
2c840 73 74 20 62 65 20 62 65 74 77 65 65 6e 20 31 20  st be between 1 
2c850 61 6e 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33  and the [sqlite3
2c860 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 70 61 72  _limit()].** par
2c870 61 6d 65 74 65 72 20 5b 53 51 4c 49 54 45 5f 4c  ameter [SQLITE_L
2c880 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55  IMIT_VARIABLE_NU
2c890 4d 42 45 52 5d 20 28 64 65 66 61 75 6c 74 20 76  MBER] (default v
2c8a0 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a  alue: 999)..**.*
2c8b0 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61 72 67  * ^The third arg
2c8c0 75 6d 65 6e 74 20 69 73 20 74 68 65 20 76 61 6c  ument is the val
2c8d0 75 65 20 74 6f 20 62 69 6e 64 20 74 6f 20 74 68  ue to bind to th
2c8e0 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20  e parameter..** 
2c8f0 5e 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61  ^If the third pa
2c900 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
2c910 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 20 6f  e3_bind_text() o
2c920 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  r sqlite3_bind_t
2c930 65 78 74 31 36 28 29 0a 2a 2a 20 6f 72 20 73 71  ext16().** or sq
2c940 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28  lite3_bind_blob(
2c950 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  ) is a NULL poin
2c960 74 65 72 20 74 68 65 6e 20 74 68 65 20 66 6f 75  ter then the fou
2c970 72 74 68 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  rth parameter.**
2c980 20 69 73 20 69 67 6e 6f 72 65 64 20 61 6e 64 20   is ignored and 
2c990 74 68 65 20 65 6e 64 20 72 65 73 75 6c 74 20 69  the end result i
2c9a0 73 20 74 68 65 20 73 61 6d 65 20 61 73 20 73 71  s the same as sq
2c9b0 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28  lite3_bind_null(
2c9c0 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68  )..**.** ^(In th
2c9d0 6f 73 65 20 72 6f 75 74 69 6e 65 73 20 74 68 61  ose routines tha
2c9e0 74 20 68 61 76 65 20 61 20 66 6f 75 72 74 68 20  t have a fourth 
2c9f0 61 72 67 75 6d 65 6e 74 2c 20 69 74 73 20 76 61  argument, its va
2ca00 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75  lue is the.** nu
2ca10 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
2ca20 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 20   the parameter. 
2ca30 20 54 6f 20 62 65 20 63 6c 65 61 72 3a 20 74 68   To be clear: th
2ca40 65 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a  e value is the.*
2ca50 2a 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62  * number of <u>b
2ca60 79 74 65 73 3c 2f 75 3e 20 69 6e 20 74 68 65 20  ytes</u> in the 
2ca70 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e  value, not the n
2ca80 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74  umber of charact
2ca90 65 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74 68  ers.)^.** ^If th
2caa0 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
2cab0 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  er to sqlite3_bi
2cac0 6e 64 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c  nd_text() or sql
2cad0 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36  ite3_bind_text16
2cae0 28 29 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76  ().** is negativ
2caf0 65 2c 20 74 68 65 6e 20 74 68 65 20 6c 65 6e 67  e, then the leng
2cb00 74 68 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67  th of the string
2cb10 20 69 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65   is.** the numbe
2cb20 72 20 6f 66 20 62 79 74 65 73 20 75 70 20 74 6f  r of bytes up to
2cb30 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20   the first zero 
2cb40 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 20 49  terminator..** I
2cb50 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
2cb60 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
2cb70 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73  3_bind_blob() is
2cb80 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 0a   negative, then.
2cb90 2a 2a 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  ** the behavior 
2cba0 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
2cbb0 20 49 66 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69   If a non-negati
2cbc0 76 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  ve fourth parame
2cbd0 74 65 72 20 69 73 20 70 72 6f 76 69 64 65 64 20  ter is provided 
2cbe0 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  to sqlite3_bind_
2cbf0 74 65 78 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c  text().** or sql
2cc00 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36  ite3_bind_text16
2cc10 28 29 20 74 68 65 6e 20 74 68 61 74 20 70 61 72  () then that par
2cc20 61 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20 74  ameter must be t
2cc30 68 65 20 62 79 74 65 20 6f 66 66 73 65 74 0a 2a  he byte offset.*
2cc40 2a 20 77 68 65 72 65 20 74 68 65 20 4e 55 4c 20  * where the NUL 
2cc50 74 65 72 6d 69 6e 61 74 6f 72 20 77 6f 75 6c 64  terminator would
2cc60 20 6f 63 63 75 72 20 61 73 73 75 6d 69 6e 67 20   occur assuming 
2cc70 74 68 65 20 73 74 72 69 6e 67 20 77 65 72 65 20  the string were 
2cc80 4e 55 4c 0a 2a 2a 20 74 65 72 6d 69 6e 61 74 65  NUL.** terminate
2cc90 64 2e 20 20 49 66 20 61 6e 79 20 4e 55 4c 20 63  d.  If any NUL c
2cca0 68 61 72 61 63 74 65 72 73 20 6f 63 63 75 72 20  haracters occur 
2ccb0 61 74 20 62 79 74 65 20 6f 66 66 73 65 74 73 20  at byte offsets 
2ccc0 6c 65 73 73 20 74 68 61 6e 20 0a 2a 2a 20 74 68  less than .** th
2ccd0 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 66  e value of the f
2cce0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
2ccf0 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 69  then the resulti
2cd00 6e 67 20 73 74 72 69 6e 67 20 76 61 6c 75 65 20  ng string value 
2cd10 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20  will.** contain 
2cd20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 2e 20 20  embedded NULs.  
2cd30 54 68 65 20 72 65 73 75 6c 74 20 6f 66 20 65 78  The result of ex
2cd40 70 72 65 73 73 69 6f 6e 73 20 69 6e 76 6f 6c 76  pressions involv
2cd50 69 6e 67 20 73 74 72 69 6e 67 73 0a 2a 2a 20 77  ing strings.** w
2cd60 69 74 68 20 65 6d 62 65 64 64 65 64 20 4e 55 4c  ith embedded NUL
2cd70 73 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  s is undefined..
2cd80 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74 68  **.** ^The fifth
2cd90 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
2cda0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29  ite3_bind_blob()
2cdb0 2c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  , sqlite3_bind_t
2cdc0 65 78 74 28 29 2c 20 61 6e 64 0a 2a 2a 20 73 71  ext(), and.** sq
2cdd0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
2cde0 36 28 29 20 69 73 20 61 20 64 65 73 74 72 75 63  6() is a destruc
2cdf0 74 6f 72 20 75 73 65 64 20 74 6f 20 64 69 73 70  tor used to disp
2ce00 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20  ose of the BLOB 
2ce10 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66 74  or.** string aft
2ce20 65 72 20 53 51 4c 69 74 65 20 68 61 73 20 66 69  er SQLite has fi
2ce30 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 20  nished with it. 
2ce40 20 5e 54 68 65 20 64 65 73 74 72 75 63 74 6f 72   ^The destructor
2ce50 20 69 73 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 6f   is called.** to
2ce60 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20   dispose of the 
2ce70 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 20 65  BLOB or string e
2ce80 76 65 6e 20 69 66 20 74 68 65 20 63 61 6c 6c 20  ven if the call 
2ce90 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  to sqlite3_bind_
2cea0 62 6c 6f 62 28 29 2c 0a 2a 2a 20 73 71 6c 69 74  blob(),.** sqlit
2ceb0 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 2c 20  e3_bind_text(), 
2cec0 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  or sqlite3_bind_
2ced0 74 65 78 74 31 36 28 29 20 66 61 69 6c 73 2e 20  text16() fails. 
2cee0 20 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 66   .** ^If the fif
2cef0 74 68 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a  th argument is.*
2cf00 2a 20 74 68 65 20 73 70 65 63 69 61 6c 20 76 61  * the special va
2cf10 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53 54 41 54  lue [SQLITE_STAT
2cf20 49 43 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  IC], then SQLite
2cf30 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68   assumes that th
2cf40 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  e.** information
2cf50 20 69 73 20 69 6e 20 73 74 61 74 69 63 2c 20 75   is in static, u
2cf60 6e 6d 61 6e 61 67 65 64 20 73 70 61 63 65 20 61  nmanaged space a
2cf70 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64  nd does not need
2cf80 20 74 6f 20 62 65 20 66 72 65 65 64 2e 0a 2a 2a   to be freed..**
2cf90 20 5e 49 66 20 74 68 65 20 66 69 66 74 68 20 61   ^If the fifth a
2cfa0 72 67 75 6d 65 6e 74 20 68 61 73 20 74 68 65 20  rgument has the 
2cfb0 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54 52  value [SQLITE_TR
2cfc0 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a  ANSIENT], then.*
2cfd0 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 69  * SQLite makes i
2cfe0 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63  ts own private c
2cff0 6f 70 79 20 6f 66 20 74 68 65 20 64 61 74 61 20  opy of the data 
2d000 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65 66  immediately, bef
2d010 6f 72 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74  ore.** the sqlit
2d020 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74  e3_bind_*() rout
2d030 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a  ine returns..**.
2d040 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2d050 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 20  bind_zeroblob() 
2d060 72 6f 75 74 69 6e 65 20 62 69 6e 64 73 20 61 20  routine binds a 
2d070 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 68 20 4e  BLOB of length N
2d080 20 74 68 61 74 0a 2a 2a 20 69 73 20 66 69 6c 6c   that.** is fill
2d090 65 64 20 77 69 74 68 20 7a 65 72 6f 65 73 2e 20  ed with zeroes. 
2d0a0 20 5e 41 20 7a 65 72 6f 62 6c 6f 62 20 75 73 65   ^A zeroblob use
2d0b0 73 20 61 20 66 69 78 65 64 20 61 6d 6f 75 6e 74  s a fixed amount
2d0c0 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a   of memory.** (j
2d0d0 75 73 74 20 61 6e 20 69 6e 74 65 67 65 72 20 74  ust an integer t
2d0e0 6f 20 68 6f 6c 64 20 69 74 73 20 73 69 7a 65 29  o hold its size)
2d0f0 20 77 68 69 6c 65 20 69 74 20 69 73 20 62 65 69   while it is bei
2d100 6e 67 20 70 72 6f 63 65 73 73 65 64 2e 0a 2a 2a  ng processed..**
2d110 20 5a 65 72 6f 62 6c 6f 62 73 20 61 72 65 20 69   Zeroblobs are i
2d120 6e 74 65 6e 64 65 64 20 74 6f 20 73 65 72 76 65  ntended to serve
2d130 20 61 73 20 70 6c 61 63 65 68 6f 6c 64 65 72 73   as placeholders
2d140 20 66 6f 72 20 42 4c 4f 42 73 20 77 68 6f 73 65   for BLOBs whose
2d150 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69 73 20 6c  .** content is l
2d160 61 74 65 72 20 77 72 69 74 74 65 6e 20 75 73 69  ater written usi
2d170 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ng.** [sqlite3_b
2d180 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65  lob_open | incre
2d190 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d  mental BLOB I/O]
2d1a0 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 5e 41   routines..** ^A
2d1b0 20 6e 65 67 61 74 69 76 65 20 76 61 6c 75 65 20   negative value 
2d1c0 66 6f 72 20 74 68 65 20 7a 65 72 6f 62 6c 6f 62  for the zeroblob
2d1d0 20 72 65 73 75 6c 74 73 20 69 6e 20 61 20 7a 65   results in a ze
2d1e0 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 2e 0a  ro-length BLOB..
2d1f0 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79 20 6f 66  **.** ^If any of
2d200 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   the sqlite3_bin
2d210 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 61  d_*() routines a
2d220 72 65 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61  re called with a
2d230 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a   NULL pointer.**
2d240 20 66 6f 72 20 74 68 65 20 5b 70 72 65 70 61 72   for the [prepar
2d250 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 72  ed statement] or
2d260 20 77 69 74 68 20 61 20 70 72 65 70 61 72 65 64   with a prepared
2d270 20 73 74 61 74 65 6d 65 6e 74 20 66 6f 72 20 77   statement for w
2d280 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  hich.** [sqlite3
2d290 5f 73 74 65 70 28 29 5d 20 68 61 73 20 62 65 65  _step()] has bee
2d2a0 6e 20 63 61 6c 6c 65 64 20 6d 6f 72 65 20 72 65  n called more re
2d2b0 63 65 6e 74 6c 79 20 74 68 61 6e 20 5b 73 71 6c  cently than [sql
2d2c0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 0a 2a  ite3_reset()],.*
2d2d0 2a 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 20  * then the call 
2d2e0 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c  will return [SQL
2d2f0 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 49 66  ITE_MISUSE].  If
2d300 20 61 6e 79 20 73 71 6c 69 74 65 33 5f 62 69 6e   any sqlite3_bin
2d310 64 5f 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  d_().** routine 
2d320 69 73 20 70 61 73 73 65 64 20 61 20 5b 70 72 65  is passed a [pre
2d330 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2d340 20 74 68 61 74 20 68 61 73 20 62 65 65 6e 20 66   that has been f
2d350 69 6e 61 6c 69 7a 65 64 2c 20 74 68 65 0a 2a 2a  inalized, the.**
2d360 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66   result is undef
2d370 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c  ined and probabl
2d380 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a  y harmful..**.**
2d390 20 5e 42 69 6e 64 69 6e 67 73 20 61 72 65 20 6e   ^Bindings are n
2d3a0 6f 74 20 63 6c 65 61 72 65 64 20 62 79 20 74 68  ot cleared by th
2d3b0 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  e [sqlite3_reset
2d3c0 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20  ()] routine..** 
2d3d0 5e 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65 74  ^Unbound paramet
2d3e0 65 72 73 20 61 72 65 20 69 6e 74 65 72 70 72 65  ers are interpre
2d3f0 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a  ted as NULL..**.
2d400 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2d410 62 69 6e 64 5f 2a 20 72 6f 75 74 69 6e 65 73 20  bind_* routines 
2d420 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f  return [SQLITE_O
2d430 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 6f 72  K] on success or
2d440 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f   an.** [error co
2d450 64 65 5d 20 69 66 20 61 6e 79 74 68 69 6e 67 20  de] if anything 
2d460 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e  goes wrong..** ^
2d470 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20 69  [SQLITE_RANGE] i
2d480 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 74 68  s returned if th
2d490 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69  e parameter.** i
2d4a0 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72  ndex is out of r
2d4b0 61 6e 67 65 2e 20 20 5e 5b 53 51 4c 49 54 45 5f  ange.  ^[SQLITE_
2d4c0 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74 75 72 6e  NOMEM] is return
2d4d0 65 64 20 69 66 20 6d 61 6c 6c 6f 63 28 29 20 66  ed if malloc() f
2d4e0 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  ails..**.** See 
2d4f0 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62  also: [sqlite3_b
2d500 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f  ind_parameter_co
2d510 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  unt()],.** [sqli
2d520 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
2d530 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 20  er_name()], and 
2d540 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
2d550 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d  rameter_index()]
2d560 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
2d570 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
2d580 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74  _blob(sqlite3_st
2d590 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
2d5a0 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f  void*, int n, vo
2d5b0 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53  id(*)(void*));.S
2d5c0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
2d5d0 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c  lite3_bind_doubl
2d5e0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
2d5f0 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 53   int, double);.S
2d600 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
2d610 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 28 73  lite3_bind_int(s
2d620 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2d630 74 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f  t, int);.SQLITE_
2d640 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
2d650 62 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69 74  bind_int64(sqlit
2d660 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73  e3_stmt*, int, s
2d670 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 53  qlite3_int64);.S
2d680 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
2d690 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28  lite3_bind_null(
2d6a0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2d6b0 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  nt);.SQLITE_API 
2d6c0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
2d6d0 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74  _text(sqlite3_st
2d6e0 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
2d6f0 63 68 61 72 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f  char*, int n, vo
2d700 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53  id(*)(void*));.S
2d710 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
2d720 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
2d730 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
2d740 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64   int, const void
2d750 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28  *, int, void(*)(
2d760 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f  void*));.SQLITE_
2d770 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
2d780 62 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69 74  bind_value(sqlit
2d790 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63  e3_stmt*, int, c
2d7a0 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  onst sqlite3_val
2d7b0 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  ue*);.SQLITE_API
2d7c0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e   int sqlite3_bin
2d7d0 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74  d_zeroblob(sqlit
2d7e0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69  e3_stmt*, int, i
2d7f0 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  nt n);../*.** CA
2d800 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f  PI3REF: Number O
2d810 66 20 53 51 4c 20 50 61 72 61 6d 65 74 65 72 73  f SQL Parameters
2d820 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75  .**.** ^This rou
2d830 74 69 6e 65 20 63 61 6e 20 62 65 20 75 73 65 64  tine can be used
2d840 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d   to find the num
2d850 62 65 72 20 6f 66 20 5b 53 51 4c 20 70 61 72 61  ber of [SQL para
2d860 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 6e 20 61 20  meters].** in a 
2d870 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2d880 65 6e 74 5d 2e 20 20 53 51 4c 20 70 61 72 61 6d  ent].  SQL param
2d890 65 74 65 72 73 20 61 72 65 20 74 6f 6b 65 6e 73  eters are tokens
2d8a0 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20   of the.** form 
2d8b0 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41  "?", "?NNN", ":A
2d8c0 41 41 22 2c 20 22 24 41 41 41 22 2c 20 6f 72 20  AA", "$AAA", or 
2d8d0 22 40 41 41 41 22 20 74 68 61 74 20 73 65 72 76  "@AAA" that serv
2d8e0 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c  e as.** placehol
2d8f0 64 65 72 73 20 66 6f 72 20 76 61 6c 75 65 73 20  ders for values 
2d900 74 68 61 74 20 61 72 65 20 5b 73 71 6c 69 74 65  that are [sqlite
2d910 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f  3_bind_blob | bo
2d920 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 70  und].** to the p
2d930 61 72 61 6d 65 74 65 72 73 20 61 74 20 61 20 6c  arameters at a l
2d940 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a  ater time..**.**
2d950 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20   ^(This routine 
2d960 61 63 74 75 61 6c 6c 79 20 72 65 74 75 72 6e 73  actually returns
2d970 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68   the index of th
2d980 65 20 6c 61 72 67 65 73 74 20 28 72 69 67 68 74  e largest (right
2d990 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 61 6d 65 74  most).** paramet
2d9a0 65 72 2e 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d  er. For all form
2d9b0 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74  s except ?NNN, t
2d9c0 68 69 73 20 77 69 6c 6c 20 63 6f 72 72 65 73 70  his will corresp
2d9d0 6f 6e 64 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 75  ond to the.** nu
2d9e0 6d 62 65 72 20 6f 66 20 75 6e 69 71 75 65 20 70  mber of unique p
2d9f0 61 72 61 6d 65 74 65 72 73 2e 20 20 49 66 20 70  arameters.  If p
2da00 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65  arameters of the
2da10 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61 72 65 20 75   ?NNN form are u
2da20 73 65 64 2c 0a 2a 2a 20 74 68 65 72 65 20 6d 61  sed,.** there ma
2da30 79 20 62 65 20 67 61 70 73 20 69 6e 20 74 68 65  y be gaps in the
2da40 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53   list.)^.**.** S
2da50 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
2da60 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69  3_bind_blob|sqli
2da70 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20  te3_bind()],.** 
2da80 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
2da90 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c  rameter_name()],
2daa0 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
2dab0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
2dac0 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c  index()]..*/.SQL
2dad0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
2dae0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
2daf0 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33  er_count(sqlite3
2db00 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  _stmt*);../*.** 
2db10 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f  CAPI3REF: Name O
2db20 66 20 41 20 48 6f 73 74 20 50 61 72 61 6d 65 74  f A Host Paramet
2db30 65 72 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  er.**.** ^The sq
2db40 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
2db50 65 74 65 72 5f 6e 61 6d 65 28 50 2c 4e 29 20 69  eter_name(P,N) i
2db60 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
2db70 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  .** the name of 
2db80 74 68 65 20 4e 2d 74 68 20 5b 53 51 4c 20 70 61  the N-th [SQL pa
2db90 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20  rameter] in the 
2dba0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2dbb0 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53 51 4c  ent] P..** ^(SQL
2dbc0 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74   parameters of t
2dbd0 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f  he form "?NNN" o
2dbe0 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41  r ":AAA" or "@AA
2dbf0 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20  A" or "$AAA".** 
2dc00 68 61 76 65 20 61 20 6e 61 6d 65 20 77 68 69 63  have a name whic
2dc10 68 20 69 73 20 74 68 65 20 73 74 72 69 6e 67 20  h is the string 
2dc20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22  "?NNN" or ":AAA"
2dc30 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24   or "@AAA" or "$
2dc40 41 41 41 22 0a 2a 2a 20 72 65 73 70 65 63 74 69  AAA".** respecti
2dc50 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65  vely..** In othe
2dc60 72 20 77 6f 72 64 73 2c 20 74 68 65 20 69 6e 69  r words, the ini
2dc70 74 69 61 6c 20 22 3a 22 20 6f 72 20 22 24 22 20  tial ":" or "$" 
2dc80 6f 72 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a 2a  or "@" or "?".**
2dc90 20 69 73 20 69 6e 63 6c 75 64 65 64 20 61 73 20   is included as 
2dca0 70 61 72 74 20 6f 66 20 74 68 65 20 6e 61 6d 65  part of the name
2dcb0 2e 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65 74 65  .)^.** ^Paramete
2dcc0 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22  rs of the form "
2dcd0 3f 22 20 77 69 74 68 6f 75 74 20 61 20 66 6f 6c  ?" without a fol
2dce0 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65 72 20 68  lowing integer h
2dcf0 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61  ave no name.** a
2dd00 6e 64 20 61 72 65 20 72 65 66 65 72 72 65 64 20  nd are referred 
2dd10 74 6f 20 61 73 20 22 6e 61 6d 65 6c 65 73 73 22  to as "nameless"
2dd20 20 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75 73 20 70   or "anonymous p
2dd30 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a  arameters"..**.*
2dd40 2a 20 5e 54 68 65 20 66 69 72 73 74 20 68 6f 73  * ^The first hos
2dd50 74 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20  t parameter has 
2dd60 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c 20 6e  an index of 1, n
2dd70 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ot 0..**.** ^If 
2dd80 74 68 65 20 76 61 6c 75 65 20 4e 20 69 73 20 6f  the value N is o
2dd90 75 74 20 6f 66 20 72 61 6e 67 65 20 6f 72 20 69  ut of range or i
2dda0 66 20 74 68 65 20 4e 2d 74 68 20 70 61 72 61 6d  f the N-th param
2ddb0 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c  eter is.** namel
2ddc0 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20 69  ess, then NULL i
2ddd0 73 20 72 65 74 75 72 6e 65 64 2e 20 20 5e 54 68  s returned.  ^Th
2dde0 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e  e returned strin
2ddf0 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73 20 69  g is.** always i
2de00 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67  n UTF-8 encoding
2de10 20 65 76 65 6e 20 69 66 20 74 68 65 20 6e 61 6d   even if the nam
2de20 65 64 20 70 61 72 61 6d 65 74 65 72 20 77 61 73  ed parameter was
2de30 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 20 73  .** originally s
2de40 70 65 63 69 66 69 65 64 20 61 73 20 55 54 46 2d  pecified as UTF-
2de50 31 36 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 70  16 in [sqlite3_p
2de60 72 65 70 61 72 65 31 36 28 29 5d 20 6f 72 0a 2a  repare16()] or.*
2de70 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
2de80 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a  re16_v2()]..**.*
2de90 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
2dea0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73  ite3_bind_blob|s
2deb0 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a  qlite3_bind()],.
2dec0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
2ded0 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74  _parameter_count
2dee0 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
2def0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
2df00 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f  ter_index()]..*/
2df10 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
2df20 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
2df30 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e  bind_parameter_n
2df40 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
2df50 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *, int);../*.** 
2df60 43 41 50 49 33 52 45 46 3a 20 49 6e 64 65 78 20  CAPI3REF: Index 
2df70 4f 66 20 41 20 50 61 72 61 6d 65 74 65 72 20 57  Of A Parameter W
2df80 69 74 68 20 41 20 47 69 76 65 6e 20 4e 61 6d 65  ith A Given Name
2df90 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74  .**.** ^Return t
2dfa0 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 53  he index of an S
2dfb0 51 4c 20 70 61 72 61 6d 65 74 65 72 20 67 69 76  QL parameter giv
2dfc0 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20 5e 54  en its name.  ^T
2dfd0 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75  he.** index valu
2dfe0 65 20 72 65 74 75 72 6e 65 64 20 69 73 20 73 75  e returned is su
2dff0 69 74 61 62 6c 65 20 66 6f 72 20 75 73 65 20 61  itable for use a
2e000 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20  s the second.** 
2e010 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
2e020 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
2e030 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e  sqlite3_bind()].
2e040 20 20 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20    ^A zero.** is 
2e050 72 65 74 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d  returned if no m
2e060 61 74 63 68 69 6e 67 20 70 61 72 61 6d 65 74 65  atching paramete
2e070 72 20 69 73 20 66 6f 75 6e 64 2e 20 20 5e 54 68  r is found.  ^Th
2e080 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e  e parameter.** n
2e090 61 6d 65 20 6d 75 73 74 20 62 65 20 67 69 76 65  ame must be give
2e0a0 6e 20 69 6e 20 55 54 46 2d 38 20 65 76 65 6e 20  n in UTF-8 even 
2e0b0 69 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  if the original 
2e0c0 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73  statement.** was
2e0d0 20 70 72 65 70 61 72 65 64 20 66 72 6f 6d 20 55   prepared from U
2e0e0 54 46 2d 31 36 20 74 65 78 74 20 75 73 69 6e 67  TF-16 text using
2e0f0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2e100 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a  e16_v2()]..**.**
2e110 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
2e120 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71  te3_bind_blob|sq
2e130 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a  lite3_bind()],.*
2e140 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
2e150 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28  parameter_count(
2e160 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
2e170 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
2e180 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a  er_index()]..*/.
2e190 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
2e1a0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2e1b0 6d 65 74 65 72 5f 69 6e 64 65 78 28 73 71 6c 69  meter_index(sqli
2e1c0 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 74  te3_stmt*, const
2e1d0 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a   char *zName);..
2e1e0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2e1f0 52 65 73 65 74 20 41 6c 6c 20 42 69 6e 64 69 6e  Reset All Bindin
2e200 67 73 20 4f 6e 20 41 20 50 72 65 70 61 72 65 64  gs On A Prepared
2e210 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a   Statement.**.**
2e220 20 5e 43 6f 6e 74 72 61 72 79 20 74 6f 20 74 68   ^Contrary to th
2e230 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d  e intuition of m
2e240 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65  any, [sqlite3_re
2e250 73 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f 74 20  set()] does not 
2e260 72 65 73 65 74 0a 2a 2a 20 74 68 65 20 5b 73 71  reset.** the [sq
2e270 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20  lite3_bind_blob 
2e280 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61  | bindings] on a
2e290 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2e2a0 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 65 20 74  ment]..** ^Use t
2e2b0 68 69 73 20 72 6f 75 74 69 6e 65 20 74 6f 20 72  his routine to r
2e2c0 65 73 65 74 20 61 6c 6c 20 68 6f 73 74 20 70 61  eset all host pa
2e2d0 72 61 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c  rameters to NULL
2e2e0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
2e2f0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 65 61  int sqlite3_clea
2e300 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74  r_bindings(sqlit
2e310 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a  e3_stmt*);../*.*
2e320 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62  * CAPI3REF: Numb
2e330 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e  er Of Columns In
2e340 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a   A Result Set.**
2e350 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20  .** ^Return the 
2e360 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
2e370 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20  s in the result 
2e380 73 65 74 20 72 65 74 75 72 6e 65 64 20 62 79 20  set returned by 
2e390 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
2e3a0 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e 54 68   statement]. ^Th
2e3b0 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  is routine retur
2e3c0 6e 73 20 30 20 69 66 20 70 53 74 6d 74 20 69 73  ns 0 if pStmt is
2e3d0 20 61 6e 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65   an SQL.** state
2e3e0 6d 65 6e 74 20 74 68 61 74 20 64 6f 65 73 20 6e  ment that does n
2e3f0 6f 74 20 72 65 74 75 72 6e 20 64 61 74 61 20 28  ot return data (
2e400 66 6f 72 20 65 78 61 6d 70 6c 65 20 61 6e 20 5b  for example an [
2e410 55 50 44 41 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a 20  UPDATE])..**.** 
2e420 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
2e430 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 29 5d  e3_data_count()]
2e440 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
2e450 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
2e460 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f  n_count(sqlite3_
2e470 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
2e480 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
2e490 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41  olumn Names In A
2e4a0 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a   Result Set.**.*
2e4b0 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
2e4c0 73 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d  s return the nam
2e4d0 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20 61 20  e assigned to a 
2e4e0 70 61 72 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d  particular colum
2e4f0 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65 73 75  n.** in the resu
2e500 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c  lt set of a [SEL
2e510 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20  ECT] statement. 
2e520 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f   ^The sqlite3_co
2e530 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69  lumn_name().** i
2e540 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
2e550 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
2e560 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
2e570 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20  UTF-8 string.** 
2e580 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
2e590 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65 74 75  mn_name16() retu
2e5a0 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
2e5b0 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
2e5c0 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72  ed.** UTF-16 str
2e5d0 69 6e 67 2e 20 20 5e 54 68 65 20 66 69 72 73 74  ing.  ^The first
2e5e0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
2e5f0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
2e600 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69  ement].** that i
2e610 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b 53  mplements the [S
2e620 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
2e630 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61  . ^The second pa
2e640 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a  rameter is the.*
2e650 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e  * column number.
2e660 20 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20    ^The leftmost 
2e670 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72  column is number
2e680 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72   0..**.** ^The r
2e690 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 70  eturned string p
2e6a0 6f 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64 20  ointer is valid 
2e6b0 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68 65  until either the
2e6c0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2e6d0 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74  ment].** is dest
2e6e0 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65  royed by [sqlite
2e6f0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72  3_finalize()] or
2e700 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65   until the state
2e710 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69  ment is automati
2e720 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61  cally.** reprepa
2e730 72 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74  red by the first
2e740 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
2e750 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20  3_step()] for a 
2e760 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a  particular run.*
2e770 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 6e  * or until the n
2e780 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73  ext call to.** s
2e790 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
2e7a0 6d 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  me() or sqlite3_
2e7b0 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20  column_name16() 
2e7c0 6f 6e 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 75  on the same colu
2e7d0 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71  mn..**.** ^If sq
2e7e0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66  lite3_malloc() f
2e7f0 61 69 6c 73 20 64 75 72 69 6e 67 20 74 68 65 20  ails during the 
2e800 70 72 6f 63 65 73 73 69 6e 67 20 6f 66 20 65 69  processing of ei
2e810 74 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20  ther routine.** 
2e820 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 64 75 72  (for example dur
2e830 69 6e 67 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e  ing a conversion
2e840 20 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55   from UTF-8 to U
2e850 54 46 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a  TF-16) then a.**
2e860 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73   NULL pointer is
2e870 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
2e880 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 61 20   ^The name of a 
2e890 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73  result column is
2e8a0 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
2e8b0 65 20 22 41 53 22 20 63 6c 61 75 73 65 20 66 6f  e "AS" clause fo
2e8c0 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e  r.** that column
2e8d0 2c 20 69 66 20 74 68 65 72 65 20 69 73 20 61 6e  , if there is an
2e8e0 20 41 53 20 63 6c 61 75 73 65 2e 20 20 49 66 20   AS clause.  If 
2e8f0 74 68 65 72 65 20 69 73 20 6e 6f 20 41 53 20 63  there is no AS c
2e900 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68  lause.** then th
2e910 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f  e name of the co
2e920 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65 63 69 66  lumn is unspecif
2e930 69 65 64 20 61 6e 64 20 6d 61 79 20 63 68 61 6e  ied and may chan
2e940 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72  ge from.** one r
2e950 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65  elease of SQLite
2e960 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f   to the next..*/
2e970 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
2e980 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
2e990 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69  column_name(sqli
2e9a0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e  te3_stmt*, int N
2e9b0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  );.SQLITE_API co
2e9c0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
2e9d0 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28  3_column_name16(
2e9e0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2e9f0 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  nt N);../*.** CA
2ea00 50 49 33 52 45 46 3a 20 53 6f 75 72 63 65 20 4f  PI3REF: Source O
2ea10 66 20 44 61 74 61 20 49 6e 20 41 20 51 75 65 72  f Data In A Quer
2ea20 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e  y Result.**.** ^
2ea30 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 70  These routines p
2ea40 72 6f 76 69 64 65 20 61 20 6d 65 61 6e 73 20 74  rovide a means t
2ea50 6f 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20  o determine the 
2ea60 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c  database, table,
2ea70 20 61 6e 64 0a 2a 2a 20 74 61 62 6c 65 20 63 6f   and.** table co
2ea80 6c 75 6d 6e 20 74 68 61 74 20 69 73 20 74 68 65  lumn that is the
2ea90 20 6f 72 69 67 69 6e 20 6f 66 20 61 20 70 61 72   origin of a par
2eaa0 74 69 63 75 6c 61 72 20 72 65 73 75 6c 74 20 63  ticular result c
2eab0 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 5b 53 45 4c  olumn in.** [SEL
2eac0 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a  ECT] statement..
2ead0 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20  ** ^The name of 
2eae0 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 72 20  the database or 
2eaf0 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20  table or column 
2eb00 63 61 6e 20 62 65 20 72 65 74 75 72 6e 65 64 20  can be returned 
2eb10 61 73 0a 2a 2a 20 65 69 74 68 65 72 20 61 20 55  as.** either a U
2eb20 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 73  TF-8 or UTF-16 s
2eb30 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 5f 64 61  tring.  ^The _da
2eb40 74 61 62 61 73 65 5f 20 72 6f 75 74 69 6e 65 73  tabase_ routines
2eb50 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64   return.** the d
2eb60 61 74 61 62 61 73 65 20 6e 61 6d 65 2c 20 74 68  atabase name, th
2eb70 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e  e _table_ routin
2eb80 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 74 61  es return the ta
2eb90 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a  ble name, and.**
2eba0 20 74 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75   the origin_ rou
2ebb0 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65  tines return the
2ebc0 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a   column name..**
2ebd0 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73   ^The returned s
2ebe0 74 72 69 6e 67 20 69 73 20 76 61 6c 69 64 20 75  tring is valid u
2ebf0 6e 74 69 6c 20 74 68 65 20 5b 70 72 65 70 61 72  ntil the [prepar
2ec00 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 73  ed statement] is
2ec10 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73   destroyed.** us
2ec20 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  ing [sqlite3_fin
2ec30 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69  alize()] or unti
2ec40 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  l the statement 
2ec50 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  is automatically
2ec60 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64 20 62  .** reprepared b
2ec70 79 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c  y the first call
2ec80 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
2ec90 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72 74 69  p()] for a parti
2eca0 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20  cular run.** or 
2ecb0 75 6e 74 69 6c 20 74 68 65 20 73 61 6d 65 20 69  until the same i
2ecc0 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72 65  nformation is re
2ecd0 71 75 65 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e  quested.** again
2ece0 20 69 6e 20 61 20 64 69 66 66 65 72 65 6e 74 20   in a different 
2ecf0 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  encoding..**.** 
2ed00 5e 54 68 65 20 6e 61 6d 65 73 20 72 65 74 75 72  ^The names retur
2ed10 6e 65 64 20 61 72 65 20 74 68 65 20 6f 72 69 67  ned are the orig
2ed20 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20  inal un-aliased 
2ed30 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20  names of the.** 
2ed40 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c  database, table,
2ed50 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a   and column..**.
2ed60 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  ** ^The first ar
2ed70 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 73 65 20  gument to these 
2ed80 69 6e 74 65 72 66 61 63 65 73 20 69 73 20 61 20  interfaces is a 
2ed90 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2eda0 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 65 73 65 20  ent]..** ^These 
2edb0 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e  functions return
2edc0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f   information abo
2edd0 75 74 20 74 68 65 20 4e 74 68 20 72 65 73 75 6c  ut the Nth resul
2ede0 74 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65  t column returne
2edf0 64 20 62 79 0a 2a 2a 20 74 68 65 20 73 74 61 74  d by.** the stat
2ee00 65 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e 20 69  ement, where N i
2ee10 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e  s the second fun
2ee20 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a  ction argument..
2ee30 2a 2a 20 5e 54 68 65 20 6c 65 66 74 2d 6d 6f 73  ** ^The left-mos
2ee40 74 20 63 6f 6c 75 6d 6e 20 69 73 20 63 6f 6c 75  t column is colu
2ee50 6d 6e 20 30 20 66 6f 72 20 74 68 65 73 65 20 72  mn 0 for these r
2ee60 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e  outines..**.** ^
2ee70 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  If the Nth colum
2ee80 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  n returned by th
2ee90 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  e statement is a
2eea0 6e 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 0a  n expression or.
2eeb0 2a 2a 20 73 75 62 71 75 65 72 79 20 61 6e 64 20  ** subquery and 
2eec0 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20  is not a column 
2eed0 76 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20  value, then all 
2eee0 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  of these functio
2eef0 6e 73 20 72 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c  ns return.** NUL
2ef00 4c 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69  L.  ^These routi
2ef10 6e 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 72 65  ne might also re
2ef20 74 75 72 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d  turn NULL if a m
2ef30 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
2ef40 20 65 72 72 6f 72 0a 2a 2a 20 6f 63 63 75 72 73   error.** occurs
2ef50 2e 20 20 5e 4f 74 68 65 72 77 69 73 65 2c 20 74  .  ^Otherwise, t
2ef60 68 65 79 20 72 65 74 75 72 6e 20 74 68 65 20 6e  hey return the n
2ef70 61 6d 65 20 6f 66 20 74 68 65 20 61 74 74 61 63  ame of the attac
2ef80 68 65 64 20 64 61 74 61 62 61 73 65 2c 20 74 61  hed database, ta
2ef90 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6c 75 6d  ble,.** or colum
2efa0 6e 20 74 68 61 74 20 71 75 65 72 79 20 72 65 73  n that query res
2efb0 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65  ult column was e
2efc0 78 74 72 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a  xtracted from..*
2efd0 2a 0a 2a 2a 20 5e 41 73 20 77 69 74 68 20 61 6c  *.** ^As with al
2efe0 6c 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 41  l other SQLite A
2eff0 50 49 73 2c 20 74 68 6f 73 65 20 77 68 6f 73 65  PIs, those whose
2f000 20 6e 61 6d 65 73 20 65 6e 64 20 77 69 74 68 20   names end with 
2f010 22 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55  "16" return.** U
2f020 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 73 74  TF-16 encoded st
2f030 72 69 6e 67 73 20 61 6e 64 20 74 68 65 20 6f 74  rings and the ot
2f040 68 65 72 20 66 75 6e 63 74 69 6f 6e 73 20 72 65  her functions re
2f050 74 75 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a  turn UTF-8..**.*
2f060 2a 20 5e 54 68 65 73 65 20 41 50 49 73 20 61 72  * ^These APIs ar
2f070 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65  e only available
2f080 20 69 66 20 74 68 65 20 6c 69 62 72 61 72 79 20   if the library 
2f090 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74  was compiled wit
2f0a0 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  h the.** [SQLITE
2f0b0 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d  _ENABLE_COLUMN_M
2f0c0 45 54 41 44 41 54 41 5d 20 43 2d 70 72 65 70 72  ETADATA] C-prepr
2f0d0 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 2e 0a  ocessor symbol..
2f0e0 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20  **.** If two or 
2f0f0 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c  more threads cal
2f100 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66  l one or more of
2f110 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
2f120 61 67 61 69 6e 73 74 20 74 68 65 20 73 61 6d 65  against the same
2f130 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74 61  .** prepared sta
2f140 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d  tement and colum
2f150 6e 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69  n at the same ti
2f160 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 75  me then the resu
2f170 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64 65 66  lts are.** undef
2f180 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  ined..**.** If t
2f190 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61  wo or more threa
2f1a0 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d  ds call one or m
2f1b0 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ore.** [sqlite3_
2f1c0 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f  column_database_
2f1d0 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65  name | column me
2f1e0 74 61 64 61 74 61 20 69 6e 74 65 72 66 61 63 65  tadata interface
2f1f0 73 5d 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61  s].** for the sa
2f200 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  me [prepared sta
2f210 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65 73 75  tement] and resu
2f220 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20  lt column.** at 
2f230 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68  the same time th
2f240 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  en the results a
2f250 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f  re undefined..*/
2f260 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
2f270 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
2f280 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f  column_database_
2f290 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
2f2a0 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f  t*,int);.SQLITE_
2f2b0 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  API const void *
2f2c0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
2f2d0 61 74 61 62 61 73 65 5f 6e 61 6d 65 31 36 28 73  atabase_name16(s
2f2e0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
2f2f0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  );.SQLITE_API co
2f300 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
2f310 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e  3_column_table_n
2f320 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
2f330 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41  *,int);.SQLITE_A
2f340 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  PI const void *s
2f350 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61  qlite3_column_ta
2f360 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74  ble_name16(sqlit
2f370 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53  e3_stmt*,int);.S
2f380 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
2f390 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
2f3a0 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65  lumn_origin_name
2f3b0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
2f3c0 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  nt);.SQLITE_API 
2f3d0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
2f3e0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69  te3_column_origi
2f3f0 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33  n_name16(sqlite3
2f400 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a  _stmt*,int);../*
2f410 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
2f420 63 6c 61 72 65 64 20 44 61 74 61 74 79 70 65 20  clared Datatype 
2f430 4f 66 20 41 20 51 75 65 72 79 20 52 65 73 75 6c  Of A Query Resul
2f440 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69  t.**.** ^(The fi
2f450 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
2f460 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
2f470 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74  tement]..** If t
2f480 68 69 73 20 73 74 61 74 65 6d 65 6e 74 20 69 73  his statement is
2f490 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74   a [SELECT] stat
2f4a0 65 6d 65 6e 74 20 61 6e 64 20 74 68 65 20 4e 74  ement and the Nt
2f4b0 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a  h column of the.
2f4c0 2a 2a 20 72 65 74 75 72 6e 65 64 20 72 65 73 75  ** returned resu
2f4d0 6c 74 20 73 65 74 20 6f 66 20 74 68 61 74 20 5b  lt set of that [
2f4e0 53 45 4c 45 43 54 5d 20 69 73 20 61 20 74 61 62  SELECT] is a tab
2f4f0 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61  le column (not a
2f500 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20  n.** expression 
2f510 6f 72 20 73 75 62 71 75 65 72 79 29 20 74 68 65  or subquery) the
2f520 6e 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74  n the declared t
2f530 79 70 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65  ype of the table
2f540 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 20 72 65  .** column is re
2f550 74 75 72 6e 65 64 2e 29 5e 20 20 5e 49 66 20 74  turned.)^  ^If t
2f560 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66  he Nth column of
2f570 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
2f580 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73  is an.** express
2f590 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 2c  ion or subquery,
2f5a0 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69   then a NULL poi
2f5b0 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64  nter is returned
2f5c0 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e  ..** ^The return
2f5d0 65 64 20 73 74 72 69 6e 67 20 69 73 20 61 6c 77  ed string is alw
2f5e0 61 79 73 20 55 54 46 2d 38 20 65 6e 63 6f 64 65  ays UTF-8 encode
2f5f0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65  d..**.** ^(For e
2f600 78 61 6d 70 6c 65 2c 20 67 69 76 65 6e 20 74 68  xample, given th
2f610 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d  e database schem
2f620 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20  a:.**.** CREATE 
2f630 54 41 42 4c 45 20 74 31 28 63 31 20 56 41 52 49  TABLE t1(c1 VARI
2f640 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20  ANT);.**.** and 
2f650 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74  the following st
2f660 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f  atement to be co
2f670 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45  mpiled:.**.** SE
2f680 4c 45 43 54 20 63 31 20 2b 20 31 2c 20 63 31 20  LECT c1 + 1, c1 
2f690 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74  FROM t1;.**.** t
2f6a0 68 69 73 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c  his routine woul
2f6b0 64 20 72 65 74 75 72 6e 20 74 68 65 20 73 74 72  d return the str
2f6c0 69 6e 67 20 22 56 41 52 49 41 4e 54 22 20 66 6f  ing "VARIANT" fo
2f6d0 72 20 74 68 65 20 73 65 63 6f 6e 64 20 72 65 73  r the second res
2f6e0 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69  ult.** column (i
2f6f0 3d 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c  ==1), and a NULL
2f700 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65   pointer for the
2f710 20 66 69 72 73 74 20 72 65 73 75 6c 74 20 63 6f   first result co
2f720 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e 29 5e 0a 2a  lumn (i==0).)^.*
2f730 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65  *.** ^SQLite use
2f740 73 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d 74 69  s dynamic run-ti
2f750 6d 65 20 74 79 70 69 6e 67 2e 20 20 5e 53 6f 20  me typing.  ^So 
2f760 6a 75 73 74 20 62 65 63 61 75 73 65 20 61 20 63  just because a c
2f770 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63 6c  olumn.** is decl
2f780 61 72 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20  ared to contain 
2f790 61 20 70 61 72 74 69 63 75 6c 61 72 20 74 79 70  a particular typ
2f7a0 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e 20  e does not mean 
2f7b0 74 68 61 74 20 74 68 65 0a 2a 2a 20 64 61 74 61  that the.** data
2f7c0 20 73 74 6f 72 65 64 20 69 6e 20 74 68 61 74 20   stored in that 
2f7d0 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68 65  column is of the
2f7e0 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 2e 20   declared type. 
2f7f0 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73 74   SQLite is.** st
2f800 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c 20 62 75  rongly typed, bu
2f810 74 20 74 68 65 20 74 79 70 69 6e 67 20 69 73 20  t the typing is 
2f820 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61 74  dynamic not stat
2f830 69 63 2e 20 20 5e 54 79 70 65 0a 2a 2a 20 69 73  ic.  ^Type.** is
2f840 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
2f850 20 69 6e 64 69 76 69 64 75 61 6c 20 76 61 6c 75   individual valu
2f860 65 73 2c 20 6e 6f 74 20 77 69 74 68 20 74 68 65  es, not with the
2f870 20 63 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 75   containers.** u
2f880 73 65 64 20 74 6f 20 68 6f 6c 64 20 74 68 6f 73  sed to hold thos
2f890 65 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a 53 51 4c  e values..*/.SQL
2f8a0 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68  ITE_API const ch
2f8b0 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
2f8c0 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73 71 6c 69  mn_decltype(sqli
2f8d0 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
2f8e0 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
2f8f0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
2f900 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36  olumn_decltype16
2f910 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
2f920 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
2f930 33 52 45 46 3a 20 45 76 61 6c 75 61 74 65 20 41  3REF: Evaluate A
2f940 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a  n SQL Statement.
2f950 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b 70  **.** After a [p
2f960 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2f970 74 5d 20 68 61 73 20 62 65 65 6e 20 70 72 65 70  t] has been prep
2f980 61 72 65 64 20 75 73 69 6e 67 20 65 69 74 68 65  ared using eithe
2f990 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  r.** [sqlite3_pr
2f9a0 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b  epare_v2()] or [
2f9b0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2f9c0 36 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f  6_v2()] or one o
2f9d0 66 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20  f the legacy.** 
2f9e0 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69  interfaces [sqli
2f9f0 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f  te3_prepare()] o
2fa00 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
2fa10 72 65 31 36 28 29 5d 2c 20 74 68 69 73 20 66 75  re16()], this fu
2fa20 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62  nction.** must b
2fa30 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20  e called one or 
2fa40 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 65 76  more times to ev
2fa50 61 6c 75 61 74 65 20 74 68 65 20 73 74 61 74 65  aluate the state
2fa60 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ment..**.** The 
2fa70 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20 62  details of the b
2fa80 65 68 61 76 69 6f 72 20 6f 66 20 74 68 65 20 73  ehavior of the s
2fa90 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e  qlite3_step() in
2faa0 74 65 72 66 61 63 65 20 64 65 70 65 6e 64 0a 2a  terface depend.*
2fab0 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 74 68 65  * on whether the
2fac0 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20 70   statement was p
2fad0 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 74 68  repared using th
2fae0 65 20 6e 65 77 65 72 20 22 76 32 22 20 69 6e 74  e newer "v2" int
2faf0 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69 74  erface.** [sqlit
2fb00 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
2fb10 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72   and [sqlite3_pr
2fb20 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72  epare16_v2()] or
2fb30 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 67 61 63   the older legac
2fb40 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 5b  y.** interface [
2fb50 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
2fb60 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
2fb70 70 72 65 70 61 72 65 31 36 28 29 5d 2e 20 20 54  prepare16()].  T
2fb80 68 65 20 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a  he use of the.**
2fb90 20 6e 65 77 20 22 76 32 22 20 69 6e 74 65 72 66   new "v2" interf
2fba0 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64  ace is recommend
2fbb0 65 64 20 66 6f 72 20 6e 65 77 20 61 70 70 6c 69  ed for new appli
2fbc0 63 61 74 69 6f 6e 73 20 62 75 74 20 74 68 65 20  cations but the 
2fbd0 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66  legacy.** interf
2fbe0 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75  ace will continu
2fbf0 65 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65  e to be supporte
2fc00 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65  d..**.** ^In the
2fc10 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63   legacy interfac
2fc20 65 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  e, the return va
2fc30 6c 75 65 20 77 69 6c 6c 20 62 65 20 65 69 74 68  lue will be eith
2fc40 65 72 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  er [SQLITE_BUSY]
2fc50 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  ,.** [SQLITE_DON
2fc60 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  E], [SQLITE_ROW]
2fc70 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  , [SQLITE_ERROR]
2fc80 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53  , or [SQLITE_MIS
2fc90 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74  USE]..** ^With t
2fca0 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
2fcb0 65 2c 20 61 6e 79 20 6f 66 20 74 68 65 20 6f 74  e, any of the ot
2fcc0 68 65 72 20 5b 72 65 73 75 6c 74 20 63 6f 64 65  her [result code
2fcd0 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64  s] or.** [extend
2fce0 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d  ed result codes]
2fcf0 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 6e   might be return
2fd00 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a  ed as well..**.*
2fd10 2a 20 5e 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  * ^[SQLITE_BUSY]
2fd20 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
2fd30 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20  database engine 
2fd40 77 61 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 63  was unable to ac
2fd50 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 64 61 74  quire the.** dat
2fd60 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e  abase locks it n
2fd70 65 65 64 73 20 74 6f 20 64 6f 20 69 74 73 20 6a  eeds to do its j
2fd80 6f 62 2e 20 20 5e 49 66 20 74 68 65 20 73 74 61  ob.  ^If the sta
2fd90 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f 4d  tement is a [COM
2fda0 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 72  MIT].** or occur
2fdb0 73 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 20  s outside of an 
2fdc0 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63  explicit transac
2fdd0 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63  tion, then you c
2fde0 61 6e 20 72 65 74 72 79 20 74 68 65 0a 2a 2a 20  an retry the.** 
2fdf0 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 74  statement.  If t
2fe00 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
2fe10 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 61  not a [COMMIT] a
2fe20 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e  nd occurs within
2fe30 20 61 6e 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20   an.** explicit 
2fe40 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e  transaction then
2fe50 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c   you should roll
2fe60 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63  back the transac
2fe70 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63  tion before.** c
2fe80 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a  ontinuing..**.**
2fe90 20 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20   ^[SQLITE_DONE] 
2fea0 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 73  means that the s
2feb0 74 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69 6e  tatement has fin
2fec0 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 0a  ished executing.
2fed0 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e  ** successfully.
2fee0 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29    sqlite3_step()
2fef0 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63   should not be c
2ff00 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20 74  alled again on t
2ff10 68 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d  his virtual.** m
2ff20 61 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20 66  achine without f
2ff30 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71  irst calling [sq
2ff40 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74  lite3_reset()] t
2ff50 6f 20 72 65 73 65 74 20 74 68 65 20 76 69 72 74  o reset the virt
2ff60 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62  ual.** machine b
2ff70 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69  ack to its initi
2ff80 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20  al state..**.** 
2ff90 5e 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74  ^If the SQL stat
2ffa0 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 65 63  ement being exec
2ffb0 75 74 65 64 20 72 65 74 75 72 6e 73 20 61 6e 79  uted returns any
2ffc0 20 64 61 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c   data, then [SQL
2ffd0 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72  ITE_ROW].** is r
2ffe0 65 74 75 72 6e 65 64 20 65 61 63 68 20 74 69 6d  eturned each tim
2fff0 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 20 64  e a new row of d
30000 61 74 61 20 69 73 20 72 65 61 64 79 20 66 6f 72  ata is ready for
30010 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79 20 74   processing by t
30020 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68  he.** caller. Th
30030 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65 20  e values may be 
30040 61 63 63 65 73 73 65 64 20 75 73 69 6e 67 20 74  accessed using t
30050 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73  he [column acces
30060 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a  s functions]..**
30070 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
30080 69 73 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20  is called again 
30090 74 6f 20 72 65 74 72 69 65 76 65 20 74 68 65 20  to retrieve the 
300a0 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 61 74 61  next row of data
300b0 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45  ..**.** ^[SQLITE
300c0 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68  _ERROR] means th
300d0 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72  at a run-time er
300e0 72 6f 72 20 28 73 75 63 68 20 61 73 20 61 20 63  ror (such as a c
300f0 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f  onstraint.** vio
30100 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 63 75  lation) has occu
30110 72 72 65 64 2e 20 20 73 71 6c 69 74 65 33 5f 73  rred.  sqlite3_s
30120 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74  tep() should not
30130 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e   be called again
30140 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d   on.** the VM. M
30150 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  ore information 
30160 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 62 79 20  may be found by 
30170 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
30180 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e  _errmsg()]..** ^
30190 57 69 74 68 20 74 68 65 20 6c 65 67 61 63 79 20  With the legacy 
301a0 69 6e 74 65 72 66 61 63 65 2c 20 61 20 6d 6f 72  interface, a mor
301b0 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72  e specific error
301c0 20 63 6f 64 65 20 28 66 6f 72 20 65 78 61 6d 70   code (for examp
301d0 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49  le,.** [SQLITE_I
301e0 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49  NTERRUPT], [SQLI
301f0 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c  TE_SCHEMA], [SQL
30200 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e  ITE_CORRUPT], an
30210 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63  d so forth).** c
30220 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20 62  an be obtained b
30230 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  y calling [sqlit
30240 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20 74  e3_reset()] on t
30250 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
30260 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e  statement].  ^In
30270 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
30280 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65  ace,.** the more
30290 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20   specific error 
302a0 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65 64  code is returned
302b0 20 64 69 72 65 63 74 6c 79 20 62 79 20 73 71 6c   directly by sql
302c0 69 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a  ite3_step()..**.
302d0 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  ** [SQLITE_MISUS
302e0 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  E] means that th
302f0 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  e this routine w
30300 61 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70 72  as called inappr
30310 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65  opriately..** Pe
30320 72 68 61 70 73 20 69 74 20 77 61 73 20 63 61 6c  rhaps it was cal
30330 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65 70 61 72  led on a [prepar
30340 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
30350 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64  at has.** alread
30360 79 20 62 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f  y been [sqlite3_
30370 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c  finalize | final
30380 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20  ized] or on one 
30390 74 68 61 74 20 68 61 64 0a 2a 2a 20 70 72 65 76  that had.** prev
303a0 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 20  iously returned 
303b0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f  [SQLITE_ERROR] o
303c0 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e  r [SQLITE_DONE].
303d0 20 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a    Or it could.**
303e0 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61   be the case tha
303f0 74 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  t the same datab
30400 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
30410 73 20 62 65 69 6e 67 20 75 73 65 64 20 62 79 20  s being used by 
30420 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74  two or.** more t
30430 68 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61  hreads at the sa
30440 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d  me moment in tim
30450 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c  e..**.** For all
30460 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
30470 69 74 65 20 75 70 20 74 6f 20 61 6e 64 20 69 6e  ite up to and in
30480 63 6c 75 64 69 6e 67 20 33 2e 36 2e 32 33 2e 31  cluding 3.6.23.1
30490 2c 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  , a call to.** [
304a0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
304b0 20 77 61 73 20 72 65 71 75 69 72 65 64 20 61 66   was required af
304c0 74 65 72 20 73 71 6c 69 74 65 33 5f 73 74 65 70  ter sqlite3_step
304d0 28 29 20 72 65 74 75 72 6e 65 64 20 61 6e 79 74  () returned anyt
304e0 68 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 74 68  hing.** other th
304f0 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20  an [SQLITE_ROW] 
30500 62 65 66 6f 72 65 20 61 6e 79 20 73 75 62 73 65  before any subse
30510 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e  quent invocation
30520 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73   of.** sqlite3_s
30530 74 65 70 28 29 2e 20 20 46 61 69 6c 75 72 65 20  tep().  Failure 
30540 74 6f 20 72 65 73 65 74 20 74 68 65 20 70 72 65  to reset the pre
30550 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
30560 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74  using .** [sqlit
30570 65 33 5f 72 65 73 65 74 28 29 5d 20 77 6f 75 6c  e3_reset()] woul
30580 64 20 72 65 73 75 6c 74 20 69 6e 20 61 6e 20 5b  d result in an [
30590 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 72  SQLITE_MISUSE] r
305a0 65 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20 73 71  eturn from.** sq
305b0 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 42  lite3_step().  B
305c0 75 74 20 61 66 74 65 72 20 76 65 72 73 69 6f 6e  ut after version
305d0 20 33 2e 36 2e 32 33 2e 31 2c 20 73 71 6c 69 74   3.6.23.1, sqlit
305e0 65 33 5f 73 74 65 70 28 29 20 62 65 67 61 6e 0a  e3_step() began.
305f0 2a 2a 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  ** calling [sqli
30600 74 65 33 5f 72 65 73 65 74 28 29 5d 20 61 75 74  te3_reset()] aut
30610 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 20 74 68  omatically in th
30620 69 73 20 63 69 72 63 75 6d 73 74 61 6e 63 65 20  is circumstance 
30630 72 61 74 68 65 72 0a 2a 2a 20 74 68 61 6e 20 72  rather.** than r
30640 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45  eturning [SQLITE
30650 5f 4d 49 53 55 53 45 5d 2e 20 20 54 68 69 73 20  _MISUSE].  This 
30660 69 73 20 6e 6f 74 20 63 6f 6e 73 69 64 65 72 65  is not considere
30670 64 20 61 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  d a compatibilit
30680 79 0a 2a 2a 20 62 72 65 61 6b 20 62 65 63 61 75  y.** break becau
30690 73 65 20 61 6e 79 20 61 70 70 6c 69 63 61 74 69  se any applicati
306a0 6f 6e 20 74 68 61 74 20 65 76 65 72 20 72 65 63  on that ever rec
306b0 65 69 76 65 73 20 61 6e 20 53 51 4c 49 54 45 5f  eives an SQLITE_
306c0 4d 49 53 55 53 45 20 65 72 72 6f 72 0a 2a 2a 20  MISUSE error.** 
306d0 69 73 20 62 72 6f 6b 65 6e 20 62 79 20 64 65 66  is broken by def
306e0 69 6e 69 74 69 6f 6e 2e 20 20 54 68 65 20 5b 53  inition.  The [S
306f0 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 52  QLITE_OMIT_AUTOR
30700 45 53 45 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  ESET] compile-ti
30710 6d 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61 6e  me option.** can
30720 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 73 74   be used to rest
30730 6f 72 65 20 74 68 65 20 6c 65 67 61 63 79 20 62  ore the legacy b
30740 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c  ehavior..**.** <
30750 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66 61 63  b>Goofy Interfac
30760 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e 20  e Alert:</b> In 
30770 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72  the legacy inter
30780 66 61 63 65 2c 20 74 68 65 20 73 71 6c 69 74 65  face, the sqlite
30790 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50 49 20  3_step().** API 
307a0 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 61  always returns a
307b0 20 67 65 6e 65 72 69 63 20 65 72 72 6f 72 20 63   generic error c
307c0 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52  ode, [SQLITE_ERR
307d0 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  OR], following a
307e0 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68 65  ny.** error othe
307f0 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42  r than [SQLITE_B
30800 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45  USY] and [SQLITE
30810 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d  _MISUSE].  You m
30820 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c  ust call.** [sql
30830 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
30840 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
30850 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 74  ze()] in order t
30860 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68  o find one of th
30870 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 5b 65  e.** specific [e
30880 72 72 6f 72 20 63 6f 64 65 73 5d 20 74 68 61 74  rror codes] that
30890 20 62 65 74 74 65 72 20 64 65 73 63 72 69 62 65   better describe
308a0 73 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20  s the error..** 
308b0 57 65 20 61 64 6d 69 74 20 74 68 61 74 20 74 68  We admit that th
308c0 69 73 20 69 73 20 61 20 67 6f 6f 66 79 20 64 65  is is a goofy de
308d0 73 69 67 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c  sign.  The probl
308e0 65 6d 20 68 61 73 20 62 65 65 6e 20 66 69 78 65  em has been fixe
308f0 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 22 76  d.** with the "v
30900 32 22 20 69 6e 74 65 72 66 61 63 65 2e 20 20 49  2" interface.  I
30910 66 20 79 6f 75 20 70 72 65 70 61 72 65 20 61 6c  f you prepare al
30920 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c 20 73 74  l of your SQL st
30930 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e  atements.** usin
30940 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65  g either [sqlite
30950 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
30960 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
30970 61 72 65 31 36 5f 76 32 28 29 5d 20 69 6e 73 74  are16_v2()] inst
30980 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65  ead.** of the le
30990 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 70 72  gacy [sqlite3_pr
309a0 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71  epare()] and [sq
309b0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
309c0 29 5d 20 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a  )] interfaces,.*
309d0 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f 72 65 20  * then the more 
309e0 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20  specific [error 
309f0 63 6f 64 65 73 5d 20 61 72 65 20 72 65 74 75 72  codes] are retur
30a00 6e 65 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20  ned directly.** 
30a10 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  by sqlite3_step(
30a20 29 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74  ).  The use of t
30a30 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
30a40 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  e is recommended
30a50 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
30a60 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 65 70  int sqlite3_step
30a70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
30a80 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
30a90 3a 20 4e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  : Number of colu
30aa0 6d 6e 73 20 69 6e 20 61 20 72 65 73 75 6c 74 20  mns in a result 
30ab0 73 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  set.**.** ^The s
30ac0 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
30ad0 74 28 50 29 20 69 6e 74 65 72 66 61 63 65 20 72  t(P) interface r
30ae0 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
30af0 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
30b00 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 72  the.** current r
30b10 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  ow of the result
30b20 20 73 65 74 20 6f 66 20 5b 70 72 65 70 61 72 65   set of [prepare
30b30 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a  d statement] P..
30b40 2a 2a 20 5e 49 66 20 70 72 65 70 61 72 65 64 20  ** ^If prepared 
30b50 73 74 61 74 65 6d 65 6e 74 20 50 20 64 6f 65 73  statement P does
30b60 20 6e 6f 74 20 68 61 76 65 20 72 65 73 75 6c 74   not have result
30b70 73 20 72 65 61 64 79 20 74 6f 20 72 65 74 75 72  s ready to retur
30b80 6e 0a 2a 2a 20 28 76 69 61 20 63 61 6c 6c 73 20  n.** (via calls 
30b90 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
30ba0 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20 73 71 6c  column_int | sql
30bb0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 28 29 5d  ite3_column_*()]
30bc0 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65   of.** interface
30bd0 73 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  s) then sqlite3_
30be0 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 65  data_count(P) re
30bf0 74 75 72 6e 73 20 30 2e 0a 2a 2a 20 5e 54 68 65  turns 0..** ^The
30c00 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
30c10 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20 61  unt(P) routine a
30c20 6c 73 6f 20 72 65 74 75 72 6e 73 20 30 20 69 66  lso returns 0 if
30c30 20 50 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69   P is a NULL poi
30c40 6e 74 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  nter..** ^The sq
30c50 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
30c60 28 50 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  (P) routine retu
30c70 72 6e 73 20 30 20 69 66 20 74 68 65 20 70 72 65  rns 0 if the pre
30c80 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 0a 2a 2a  vious call to.**
30c90 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 5d 28   [sqlite3_step](
30ca0 50 29 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c  P) returned [SQL
30cb0 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 5e 54 68 65  ITE_DONE].  ^The
30cc0 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
30cd0 75 6e 74 28 50 29 0a 2a 2a 20 77 69 6c 6c 20 72  unt(P).** will r
30ce0 65 74 75 72 6e 20 6e 6f 6e 2d 7a 65 72 6f 20 69  eturn non-zero i
30cf0 66 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20  f previous call 
30d00 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
30d10 5d 28 50 29 20 72 65 74 75 72 6e 65 64 0a 2a 2a  ](P) returned.**
30d20 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 65   [SQLITE_ROW], e
30d30 78 63 65 70 74 20 69 6e 20 74 68 65 20 63 61 73  xcept in the cas
30d40 65 20 6f 66 20 74 68 65 20 5b 50 52 41 47 4d 41  e of the [PRAGMA
30d50 20 69 6e 63 72 65 6d 65 6e 74 61 6c 5f 76 61 63   incremental_vac
30d60 75 75 6d 5d 0a 2a 2a 20 77 68 65 72 65 20 69 74  uum].** where it
30d70 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20   always returns 
30d80 7a 65 72 6f 20 73 69 6e 63 65 20 65 61 63 68 20  zero since each 
30d90 73 74 65 70 20 6f 66 20 74 68 61 74 20 6d 75 6c  step of that mul
30da0 74 69 2d 73 74 65 70 0a 2a 2a 20 70 72 61 67 6d  ti-step.** pragm
30db0 61 20 72 65 74 75 72 6e 73 20 30 20 63 6f 6c 75  a returns 0 colu
30dc0 6d 6e 73 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a  mns of data..**.
30dd0 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
30de0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75  lite3_column_cou
30df0 6e 74 28 29 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f  nt()].*/.SQLITE_
30e00 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
30e10 64 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69 74  data_count(sqlit
30e20 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
30e30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
30e40 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44 61  : Fundamental Da
30e50 74 61 74 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f  tatypes.** KEYWO
30e60 52 44 53 3a 20 53 51 4c 49 54 45 5f 54 45 58 54  RDS: SQLITE_TEXT
30e70 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72 79 20 76  .**.** ^(Every v
30e80 61 6c 75 65 20 69 6e 20 53 51 4c 69 74 65 20 68  alue in SQLite h
30e90 61 73 20 6f 6e 65 20 6f 66 20 66 69 76 65 20 66  as one of five f
30ea0 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74 61 74  undamental datat
30eb0 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ypes:.**.** <ul>
30ec0 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20  .** <li> 64-bit 
30ed0 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a  signed integer.*
30ee0 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49 45  * <li> 64-bit IE
30ef0 45 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  EE floating poin
30f00 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e  t number.** <li>
30f10 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20   string.** <li> 
30f20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c  BLOB.** <li> NUL
30f30 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a  L.** </ul>)^.**.
30f40 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
30f50 74 73 20 61 72 65 20 63 6f 64 65 73 20 66 6f 72  ts are codes for
30f60 20 65 61 63 68 20 6f 66 20 74 68 6f 73 65 20 74   each of those t
30f70 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65  ypes..**.** Note
30f80 20 74 68 61 74 20 74 68 65 20 53 51 4c 49 54 45   that the SQLITE
30f90 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e 74 20 77  _TEXT constant w
30fa0 61 73 20 61 6c 73 6f 20 75 73 65 64 20 69 6e 20  as also used in 
30fb0 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32  SQLite version 2
30fc0 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65  .** for a comple
30fd0 74 65 6c 79 20 64 69 66 66 65 72 65 6e 74 20 6d  tely different m
30fe0 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61 72  eaning.  Softwar
30ff0 65 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61  e that links aga
31000 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51 4c  inst both.** SQL
31010 69 74 65 20 76 65 72 73 69 6f 6e 20 32 20 61 6e  ite version 2 an
31020 64 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  d SQLite version
31030 20 33 20 73 68 6f 75 6c 64 20 75 73 65 20 53 51   3 should use SQ
31040 4c 49 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74 0a  LITE3_TEXT, not.
31050 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a  ** SQLITE_TEXT..
31060 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
31070 45 5f 49 4e 54 45 47 45 52 20 20 31 0a 23 64 65  E_INTEGER  1.#de
31080 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41  fine SQLITE_FLOA
31090 54 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53  T    2.#define S
310a0 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20 20 34  QLITE_BLOB     4
310b0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
310c0 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69 66 64 65  NULL     5.#ifde
310d0 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 20  f SQLITE_TEXT.# 
310e0 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58  undef SQLITE_TEX
310f0 54 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65  T.#else.# define
31100 20 53 51 4c 49 54 45 5f 54 45 58 54 20 20 20 20   SQLITE_TEXT    
31110 20 33 0a 23 65 6e 64 69 66 0a 23 64 65 66 69 6e   3.#endif.#defin
31120 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 20 20  e SQLITE3_TEXT  
31130 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49     3../*.** CAPI
31140 33 52 45 46 3a 20 52 65 73 75 6c 74 20 56 61 6c  3REF: Result Val
31150 75 65 73 20 46 72 6f 6d 20 41 20 51 75 65 72 79  ues From A Query
31160 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63  .** KEYWORDS: {c
31170 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e  olumn access fun
31180 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68  ctions}.**.** Th
31190 65 73 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72  ese routines for
311a0 6d 20 74 68 65 20 22 72 65 73 75 6c 74 20 73 65  m the "result se
311b0 74 22 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  t" interface..**
311c0 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
311d0 6e 65 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72  nes return infor
311e0 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 61 20 73  mation about a s
311f0 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20  ingle column of 
31200 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 72  the current.** r
31210 65 73 75 6c 74 20 72 6f 77 20 6f 66 20 61 20 71  esult row of a q
31220 75 65 72 79 2e 20 20 5e 49 6e 20 65 76 65 72 79  uery.  ^In every
31230 20 63 61 73 65 20 74 68 65 20 66 69 72 73 74 20   case the first 
31240 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f  argument is a po
31250 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  inter.** to the 
31260 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
31270 65 6e 74 5d 20 74 68 61 74 20 69 73 20 62 65 69  ent] that is bei
31280 6e 67 20 65 76 61 6c 75 61 74 65 64 20 28 74 68  ng evaluated (th
31290 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  e [sqlite3_stmt*
312a0 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 72 65  ].** that was re
312b0 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  turned from [sql
312c0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
312d0 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73  )] or one of its
312e0 20 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20 61 6e   variants).** an
312f0 64 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  d the second arg
31300 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64  ument is the ind
31310 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e  ex of the column
31320 20 66 6f 72 20 77 68 69 63 68 20 69 6e 66 6f 72   for which infor
31330 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64  mation.** should
31340 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 5e 54   be returned. ^T
31350 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75  he leftmost colu
31360 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  mn of the result
31370 20 73 65 74 20 68 61 73 20 74 68 65 20 69 6e 64   set has the ind
31380 65 78 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 6e 75  ex 0..** ^The nu
31390 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
313a0 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 63 61  in the result ca
313b0 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20  n be determined 
313c0 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
313d0 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29  3_column_count()
313e0 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  ]..**.** If the 
313f0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f  SQL statement do
31400 65 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79  es not currently
31410 20 70 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c 69   point to a vali
31420 64 20 72 6f 77 2c 20 6f 72 20 69 66 20 74 68 65  d row, or if the
31430 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78  .** column index
31440 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
31450 2c 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  , the result is 
31460 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68  undefined..** Th
31470 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 61 79  ese routines may
31480 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20   only be called 
31490 77 68 65 6e 20 74 68 65 20 6d 6f 73 74 20 72 65  when the most re
314a0 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  cent call to.** 
314b0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
314c0 20 68 61 73 20 72 65 74 75 72 6e 65 64 20 5b 53   has returned [S
314d0 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e  QLITE_ROW] and n
314e0 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74  either.** [sqlit
314f0 65 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72 20  e3_reset()] nor 
31500 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
31510 65 28 29 5d 20 68 61 76 65 20 62 65 65 6e 20 63  e()] have been c
31520 61 6c 6c 65 64 20 73 75 62 73 65 71 75 65 6e 74  alled subsequent
31530 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66  ly..** If any of
31540 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
31550 61 72 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72  are called after
31560 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
31570 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
31580 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72  3_finalize()] or
31590 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f   after [sqlite3_
315a0 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75  step()] has retu
315b0 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e  rned.** somethin
315c0 67 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  g other than [SQ
315d0 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72  LITE_ROW], the r
315e0 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66  esults are undef
315f0 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c  ined..** If [sql
31600 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20  ite3_step()] or 
31610 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
31620 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69  ] or [sqlite3_fi
31630 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65  nalize()].** are
31640 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64   called from a d
31650 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 20  ifferent thread 
31660 77 68 69 6c 65 20 61 6e 79 20 6f 66 20 74 68 65  while any of the
31670 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61  se routines.** a
31680 72 65 20 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e  re pending, then
31690 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
316a0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
316b0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63  * ^The sqlite3_c
316c0 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75  olumn_type() rou
316d0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
316e0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  .** [SQLITE_INTE
316f0 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 20 63  GER | datatype c
31700 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 69 6e 69  ode] for the ini
31710 74 69 61 6c 20 64 61 74 61 20 74 79 70 65 0a 2a  tial data type.*
31720 2a 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  * of the result 
31730 63 6f 6c 75 6d 6e 2e 20 20 5e 54 68 65 20 72 65  column.  ^The re
31740 74 75 72 6e 65 64 20 76 61 6c 75 65 20 69 73 20  turned value is 
31750 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49  one of [SQLITE_I
31760 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c  NTEGER],.** [SQL
31770 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c  ITE_FLOAT], [SQL
31780 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c 49  ITE_TEXT], [SQLI
31790 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51  TE_BLOB], or [SQ
317a0 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65  LITE_NULL].  The
317b0 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e   value.** return
317c0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
317d0 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 6f  lumn_type() is o
317e0 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69  nly meaningful i
317f0 66 20 6e 6f 20 74 79 70 65 0a 2a 2a 20 63 6f 6e  f no type.** con
31800 76 65 72 73 69 6f 6e 73 20 68 61 76 65 20 6f 63  versions have oc
31810 63 75 72 72 65 64 20 61 73 20 64 65 73 63 72 69  curred as descri
31820 62 65 64 20 62 65 6c 6f 77 2e 20 20 41 66 74 65  bed below.  Afte
31830 72 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73  r a type convers
31840 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76 61 6c 75  ion,.** the valu
31850 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  e returned by sq
31860 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
31870 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64  e() is undefined
31880 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20 76 65 72  .  Future.** ver
31890 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20  sions of SQLite 
318a0 6d 61 79 20 63 68 61 6e 67 65 20 74 68 65 20 62  may change the b
318b0 65 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 74  ehavior of sqlit
318c0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29  e3_column_type()
318d0 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20  .** following a 
318e0 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e  type conversion.
318f0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  .**.** ^If the r
31900 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20  esult is a BLOB 
31910 6f 72 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20  or UTF-8 string 
31920 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33  then the sqlite3
31930 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a  _column_bytes().
31940 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  ** routine retur
31950 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
31960 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 42   bytes in that B
31970 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a  LOB or string..*
31980 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
31990 20 69 73 20 61 20 55 54 46 2d 31 36 20 73 74 72   is a UTF-16 str
319a0 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  ing, then sqlite
319b0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
319c0 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65   converts.** the
319d0 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 38   string to UTF-8
319e0 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e   and then return
319f0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
31a00 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68  bytes..** ^If th
31a10 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75  e result is a nu
31a20 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e  meric value then
31a30 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
31a40 62 79 74 65 73 28 29 20 75 73 65 73 0a 2a 2a 20  bytes() uses.** 
31a50 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  [sqlite3_snprint
31a60 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20  f()] to convert 
31a70 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20  that value to a 
31a80 55 54 46 2d 38 20 73 74 72 69 6e 67 20 61 6e 64  UTF-8 string and
31a90 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20   returns.** the 
31aa0 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
31ab0 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a  in that string..
31ac0 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
31ad0 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20  t is NULL, then 
31ae0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
31af0 79 74 65 73 28 29 20 72 65 74 75 72 6e 73 20 7a  ytes() returns z
31b00 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ero..**.** ^If t
31b10 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 42  he result is a B
31b20 4c 4f 42 20 6f 72 20 55 54 46 2d 31 36 20 73 74  LOB or UTF-16 st
31b30 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71  ring then the sq
31b40 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
31b50 65 73 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e  es16().** routin
31b60 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  e returns the nu
31b70 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
31b80 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74   that BLOB or st
31b90 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ring..** ^If the
31ba0 20 72 65 73 75 6c 74 20 69 73 20 61 20 55 54 46   result is a UTF
31bb0 2d 38 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20  -8 string, then 
31bc0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
31bd0 79 74 65 73 31 36 28 29 20 63 6f 6e 76 65 72 74  ytes16() convert
31be0 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20  s.** the string 
31bf0 74 6f 20 55 54 46 2d 31 36 20 61 6e 64 20 74 68  to UTF-16 and th
31c00 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  en returns the n
31c10 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a  umber of bytes..
31c20 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
31c30 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76  t is a numeric v
31c40 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65  alue then sqlite
31c50 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
31c60 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69  () uses.** [sqli
31c70 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20  te3_snprintf()] 
31c80 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20  to convert that 
31c90 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 31  value to a UTF-1
31ca0 36 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74  6 string and ret
31cb0 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  urns.** the numb
31cc0 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
31cd0 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e  hat string..** ^
31ce0 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
31cf0 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69   NULL, then sqli
31d00 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
31d10 31 36 28 29 20 72 65 74 75 72 6e 73 20 7a 65 72  16() returns zer
31d20 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 76 61  o..**.** ^The va
31d30 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79  lues returned by
31d40 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
31d50 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 20 0a 2a  _bytes()] and .*
31d60 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
31d70 6e 5f 62 79 74 65 73 31 36 28 29 5d 20 64 6f 20  n_bytes16()] do 
31d80 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74 68 65 20  not include the 
31d90 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 73  zero terminators
31da0 20 61 74 20 74 68 65 20 65 6e 64 0a 2a 2a 20 6f   at the end.** o
31db0 66 20 74 68 65 20 73 74 72 69 6e 67 2e 20 20 5e  f the string.  ^
31dc0 46 6f 72 20 63 6c 61 72 69 74 79 3a 20 74 68 65  For clarity: the
31dd0 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64   values returned
31de0 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   by.** [sqlite3_
31df0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20  column_bytes()] 
31e00 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  and [sqlite3_col
31e10 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20 61  umn_bytes16()] a
31e20 72 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  re the number of
31e30 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20 74 68 65  .** bytes in the
31e40 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74 68 65   string, not the
31e50 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61   number of chara
31e60 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74  cters..**.** ^St
31e70 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62  rings returned b
31e80 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
31e90 5f 74 65 78 74 28 29 20 61 6e 64 20 73 71 6c 69  _text() and sqli
31ea0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
31eb0 36 28 29 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d 70  6(),.** even emp
31ec0 74 79 20 73 74 72 69 6e 67 73 2c 20 61 72 65 20  ty strings, are 
31ed0 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d  always zero-term
31ee0 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 72 65  inated.  ^The re
31ef0 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 66 72  turn.** value fr
31f00 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  om sqlite3_colum
31f10 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 20 61 20 7a  n_blob() for a z
31f20 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 20  ero-length BLOB 
31f30 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
31f40 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f 62  r..**.** ^The ob
31f50 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79  ject returned by
31f60 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
31f70 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 61 6e 0a  _value()] is an.
31f80 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  ** [unprotected 
31f90 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
31fa0 62 6a 65 63 74 2e 20 20 41 6e 20 75 6e 70 72 6f  bject.  An unpro
31fb0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
31fc0 61 6c 75 65 20 6f 62 6a 65 63 74 0a 2a 2a 20 6d  alue object.** m
31fd0 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20  ay only be used 
31fe0 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 62 69  with [sqlite3_bi
31ff0 6e 64 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20  nd_value()] and 
32000 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
32010 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20  value()]..** If 
32020 74 68 65 20 5b 75 6e 70 72 6f 74 65 63 74 65 64  the [unprotected
32030 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
32040 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20  object returned 
32050 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  by.** [sqlite3_c
32060 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69  olumn_value()] i
32070 73 20 75 73 65 64 20 69 6e 20 61 6e 79 20 6f 74  s used in any ot
32080 68 65 72 20 77 61 79 2c 20 69 6e 63 6c 75 64 69  her way, includi
32090 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72  ng calls.** to r
320a0 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71  outines like [sq
320b0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28  lite3_value_int(
320c0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  )], [sqlite3_val
320d0 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f  ue_text()],.** o
320e0 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  r [sqlite3_value
320f0 5f 62 79 74 65 73 28 29 5d 2c 20 74 68 65 6e 20  _bytes()], then 
32100 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20  the behavior is 
32110 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
32120 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
32130 61 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65  attempt to conve
32140 72 74 20 74 68 65 20 76 61 6c 75 65 20 77 68 65  rt the value whe
32150 72 65 20 61 70 70 72 6f 70 72 69 61 74 65 2e 20  re appropriate. 
32160 20 5e 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65   ^For.** example
32170 2c 20 69 66 20 74 68 65 20 69 6e 74 65 72 6e 61  , if the interna
32180 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e  l representation
32190 20 69 73 20 46 4c 4f 41 54 20 61 6e 64 20 61 20   is FLOAT and a 
321a0 74 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69  text result.** i
321b0 73 20 72 65 71 75 65 73 74 65 64 2c 20 5b 73 71  s requested, [sq
321c0 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
321d0 5d 20 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e  ] is used intern
321e0 61 6c 6c 79 20 74 6f 20 70 65 72 66 6f 72 6d 20  ally to perform 
321f0 74 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f  the.** conversio
32200 6e 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e  n automatically.
32210 20 20 5e 28 54 68 65 20 66 6f 6c 6c 6f 77 69 6e    ^(The followin
32220 67 20 74 61 62 6c 65 20 64 65 74 61 69 6c 73 20  g table details 
32230 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 0a  the conversions.
32240 2a 2a 20 74 68 61 74 20 61 72 65 20 61 70 70 6c  ** that are appl
32250 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ied:.**.** <bloc
32260 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c  kquote>.** <tabl
32270 65 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a  e border="1">.**
32280 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e   <tr><th> Intern
32290 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20  al<br>Type <th> 
322a0 52 65 71 75 65 73 74 65 64 3c 62 72 3e 54 79 70  Requested<br>Typ
322b0 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73 69  e <th>  Conversi
322c0 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64  on.**.** <tr><td
322d0 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20  >  NULL    <td> 
322e0 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 52  INTEGER   <td> R
322f0 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74  esult is 0.** <t
32300 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20  r><td>  NULL    
32310 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c  <td>  FLOAT    <
32320 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 2e  td> Result is 0.
32330 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e  0.** <tr><td>  N
32340 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 54 45  ULL    <td>   TE
32350 58 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c  XT    <td> Resul
32360 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  t is NULL pointe
32370 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e  r.** <tr><td>  N
32380 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 42 4c  ULL    <td>   BL
32390 4f 42 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c  OB    <td> Resul
323a0 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  t is NULL pointe
323b0 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e  r.** <tr><td> IN
323c0 54 45 47 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f  TEGER  <td>  FLO
323d0 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65  AT    <td> Conve
323e0 72 74 20 66 72 6f 6d 20 69 6e 74 65 67 65 72 20  rt from integer 
323f0 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e  to float.** <tr>
32400 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74  <td> INTEGER  <t
32410 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64  d>   TEXT    <td
32420 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e  > ASCII renderin
32430 67 20 6f 66 20 74 68 65 20 69 6e 74 65 67 65 72  g of the integer
32440 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54  .** <tr><td> INT
32450 45 47 45 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f  EGER  <td>   BLO
32460 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61  B    <td> Same a
32470 73 20 49 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a  s INTEGER->TEXT.
32480 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f  ** <tr><td>  FLO
32490 41 54 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45  AT   <td> INTEGE
324a0 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74  R   <td> Convert
324b0 20 66 72 6f 6d 20 66 6c 6f 61 74 20 74 6f 20 69   from float to i
324c0 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74  nteger.** <tr><t
324d0 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e  d>  FLOAT   <td>
324e0 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20     TEXT    <td> 
324f0 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20  ASCII rendering 
32500 6f 66 20 74 68 65 20 66 6c 6f 61 74 0a 2a 2a 20  of the float.** 
32510 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20  <tr><td>  FLOAT 
32520 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20    <td>   BLOB   
32530 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 46 4c   <td> Same as FL
32540 4f 41 54 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72  OAT->TEXT.** <tr
32550 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c  ><td>  TEXT    <
32560 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74  td> INTEGER   <t
32570 64 3e 20 55 73 65 20 61 74 6f 69 28 29 0a 2a 2a  d> Use atoi().**
32580 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20   <tr><td>  TEXT 
32590 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20     <td>  FLOAT  
325a0 20 20 3c 74 64 3e 20 55 73 65 20 61 74 6f 66 28    <td> Use atof(
325b0 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54  ).** <tr><td>  T
325c0 45 58 54 20 20 20 20 3c 74 64 3e 20 20 20 42 4c  EXT    <td>   BL
325d0 4f 42 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68  OB    <td> No ch
325e0 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  ange.** <tr><td>
325f0 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49    BLOB    <td> I
32600 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 43 6f  NTEGER   <td> Co
32610 6e 76 65 72 74 20 74 6f 20 54 45 58 54 20 74 68  nvert to TEXT th
32620 65 6e 20 75 73 65 20 61 74 6f 69 28 29 0a 2a 2a  en use atoi().**
32630 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20   <tr><td>  BLOB 
32640 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20     <td>  FLOAT  
32650 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 74    <td> Convert t
32660 6f 20 54 45 58 54 20 74 68 65 6e 20 75 73 65 20  o TEXT then use 
32670 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74  atof().** <tr><t
32680 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  d>  BLOB    <td>
32690 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20     TEXT    <td> 
326a0 41 64 64 20 61 20 7a 65 72 6f 20 74 65 72 6d 69  Add a zero termi
326b0 6e 61 74 6f 72 20 69 66 20 6e 65 65 64 65 64 0a  nator if needed.
326c0 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c  ** </table>.** <
326d0 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a  /blockquote>)^.*
326e0 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 61  *.** The table a
326f0 62 6f 76 65 20 6d 61 6b 65 73 20 72 65 66 65 72  bove makes refer
32700 65 6e 63 65 20 74 6f 20 73 74 61 6e 64 61 72 64  ence to standard
32710 20 43 20 6c 69 62 72 61 72 79 20 66 75 6e 63 74   C library funct
32720 69 6f 6e 73 20 61 74 6f 69 28 29 0a 2a 2a 20 61  ions atoi().** a
32730 6e 64 20 61 74 6f 66 28 29 2e 20 20 53 51 4c 69  nd atof().  SQLi
32740 74 65 20 64 6f 65 73 20 6e 6f 74 20 72 65 61 6c  te does not real
32750 6c 79 20 75 73 65 20 74 68 65 73 65 20 66 75 6e  ly use these fun
32760 63 74 69 6f 6e 73 2e 20 20 49 74 20 68 61 73 20  ctions.  It has 
32770 69 74 73 0a 2a 2a 20 6f 77 6e 20 65 71 75 69 76  its.** own equiv
32780 61 6c 65 6e 74 20 69 6e 74 65 72 6e 61 6c 20 72  alent internal r
32790 6f 75 74 69 6e 65 73 2e 20 20 54 68 65 20 61 74  outines.  The at
327a0 6f 69 28 29 20 61 6e 64 20 61 74 6f 66 28 29 20  oi() and atof() 
327b0 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 75 73 65  names are.** use
327c0 64 20 69 6e 20 74 68 65 20 74 61 62 6c 65 20 66  d in the table f
327d0 6f 72 20 62 72 65 76 69 74 79 20 61 6e 64 20 62  or brevity and b
327e0 65 63 61 75 73 65 20 74 68 65 79 20 61 72 65 20  ecause they are 
327f0 66 61 6d 69 6c 69 61 72 20 74 6f 20 6d 6f 73 74  familiar to most
32800 0a 2a 2a 20 43 20 70 72 6f 67 72 61 6d 6d 65 72  .** C programmer
32810 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68  s..**.** Note th
32820 61 74 20 77 68 65 6e 20 74 79 70 65 20 63 6f 6e  at when type con
32830 76 65 72 73 69 6f 6e 73 20 6f 63 63 75 72 2c 20  versions occur, 
32840 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65  pointers returne
32850 64 20 62 79 20 70 72 69 6f 72 0a 2a 2a 20 63 61  d by prior.** ca
32860 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  lls to sqlite3_c
32870 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 71  olumn_blob(), sq
32880 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
32890 74 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73  t(), and/or.** s
328a0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
328b0 78 74 31 36 28 29 20 6d 61 79 20 62 65 20 69 6e  xt16() may be in
328c0 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 20 54 79  validated..** Ty
328d0 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 61  pe conversions a
328e0 6e 64 20 70 6f 69 6e 74 65 72 20 69 6e 76 61 6c  nd pointer inval
328f0 69 64 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6f  idations might o
32900 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 66  ccur.** in the f
32910 6f 6c 6c 6f 77 69 6e 67 20 63 61 73 65 73 3a 0a  ollowing cases:.
32920 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
32930 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63  i> The initial c
32940 6f 6e 74 65 6e 74 20 69 73 20 61 20 42 4c 4f 42  ontent is a BLOB
32950 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
32960 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 0a 2a 2a  umn_text() or.**
32970 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f        sqlite3_co
32980 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73  lumn_text16() is
32990 20 63 61 6c 6c 65 64 2e 20 20 41 20 7a 65 72 6f   called.  A zero
329a0 2d 74 65 72 6d 69 6e 61 74 6f 72 20 6d 69 67 68  -terminator migh
329b0 74 0a 2a 2a 20 20 20 20 20 20 6e 65 65 64 20 74  t.**      need t
329c0 6f 20 62 65 20 61 64 64 65 64 20 74 6f 20 74 68  o be added to th
329d0 65 20 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a  e string.</li>.*
329e0 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69  * <li> The initi
329f0 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54  al content is UT
32a00 46 2d 38 20 74 65 78 74 20 61 6e 64 20 73 71 6c  F-8 text and sql
32a10 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
32a20 73 31 36 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20  s16() or.**     
32a30 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
32a40 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c  text16() is call
32a50 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74  ed.  The content
32a60 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74   must be convert
32a70 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54  ed.**      to UT
32a80 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c  F-16.</li>.** <l
32a90 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63  i> The initial c
32aa0 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 31 36  ontent is UTF-16
32ab0 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65   text and sqlite
32ac0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
32ad0 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69   or.**      sqli
32ae0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
32af0 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68  ) is called.  Th
32b00 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62  e content must b
32b10 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20  e converted.**  
32b20 20 20 20 20 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c      to UTF-8.</l
32b30 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  i>.** </ul>.**.*
32b40 2a 20 5e 43 6f 6e 76 65 72 73 69 6f 6e 73 20 62  * ^Conversions b
32b50 65 74 77 65 65 6e 20 55 54 46 2d 31 36 62 65 20  etween UTF-16be 
32b60 61 6e 64 20 55 54 46 2d 31 36 6c 65 20 61 72 65  and UTF-16le are
32b70 20 61 6c 77 61 79 73 20 64 6f 6e 65 20 69 6e 20   always done in 
32b80 70 6c 61 63 65 20 61 6e 64 20 64 6f 0a 2a 2a 20  place and do.** 
32b90 6e 6f 74 20 69 6e 76 61 6c 69 64 61 74 65 20 61  not invalidate a
32ba0 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 2c 20   prior pointer, 
32bb0 74 68 6f 75 67 68 20 6f 66 20 63 6f 75 72 73 65  though of course
32bc0 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
32bd0 74 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 74 68  the buffer.** th
32be0 61 74 20 74 68 65 20 70 72 69 6f 72 20 70 6f 69  at the prior poi
32bf0 6e 74 65 72 20 72 65 66 65 72 65 6e 63 65 73 20  nter references 
32c00 77 69 6c 6c 20 68 61 76 65 20 62 65 65 6e 20 6d  will have been m
32c10 6f 64 69 66 69 65 64 2e 20 20 4f 74 68 65 72 20  odified.  Other 
32c20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76  kinds.** of conv
32c30 65 72 73 69 6f 6e 20 61 72 65 20 64 6f 6e 65 20  ersion are done 
32c40 69 6e 20 70 6c 61 63 65 20 77 68 65 6e 20 69 74  in place when it
32c50 20 69 73 20 70 6f 73 73 69 62 6c 65 2c 20 62 75   is possible, bu
32c60 74 20 73 6f 6d 65 74 69 6d 65 73 20 74 68 65 79  t sometimes they
32c70 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 70 6f 73 73  .** are not poss
32c80 69 62 6c 65 20 61 6e 64 20 69 6e 20 74 68 6f 73  ible and in thos
32c90 65 20 63 61 73 65 73 20 70 72 69 6f 72 20 70 6f  e cases prior po
32ca0 69 6e 74 65 72 73 20 61 72 65 20 69 6e 76 61 6c  inters are inval
32cb0 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  idated..**.** Th
32cc0 65 20 73 61 66 65 73 74 20 61 6e 64 20 65 61 73  e safest and eas
32cd0 69 65 73 74 20 74 6f 20 72 65 6d 65 6d 62 65 72  iest to remember
32ce0 20 70 6f 6c 69 63 79 20 69 73 20 74 6f 20 69 6e   policy is to in
32cf0 76 6f 6b 65 20 74 68 65 73 65 20 72 6f 75 74 69  voke these routi
32d00 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66  nes.** in one of
32d10 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 77   the following w
32d20 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ays:.**.** <ul>.
32d30 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f  **  <li>sqlite3_
32d40 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 66 6f  column_text() fo
32d50 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65  llowed by sqlite
32d60 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
32d70 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71  </li>.**  <li>sq
32d80 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
32d90 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  b() followed by 
32da0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
32db0 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20  ytes()</li>.**  
32dc0 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75  <li>sqlite3_colu
32dd0 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 6f 6c 6c  mn_text16() foll
32de0 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  owed by sqlite3_
32df0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
32e00 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  </li>.** </ul>.*
32e10 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f  *.** In other wo
32e20 72 64 73 2c 20 79 6f 75 20 73 68 6f 75 6c 64 20  rds, you should 
32e30 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c  call sqlite3_col
32e40 75 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a 20 73  umn_text(),.** s
32e50 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
32e60 6f 62 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33  ob(), or sqlite3
32e70 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
32e80 20 66 69 72 73 74 20 74 6f 20 66 6f 72 63 65 20   first to force 
32e90 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e  the result.** in
32ea0 74 6f 20 74 68 65 20 64 65 73 69 72 65 64 20 66  to the desired f
32eb0 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69 6e 76 6f  ormat, then invo
32ec0 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ke sqlite3_colum
32ed0 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20  n_bytes() or.** 
32ee0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
32ef0 79 74 65 73 31 36 28 29 20 74 6f 20 66 69 6e 64  ytes16() to find
32f00 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
32f10 20 72 65 73 75 6c 74 2e 20 20 44 6f 20 6e 6f 74   result.  Do not
32f20 20 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f   mix calls.** to
32f30 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
32f40 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65  text() or sqlite
32f50 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20  3_column_blob() 
32f60 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  with calls to.**
32f70 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
32f80 62 79 74 65 73 31 36 28 29 2c 20 61 6e 64 20 64  bytes16(), and d
32f90 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 20  o not mix calls 
32fa0 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  to sqlite3_colum
32fb0 6e 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 77 69  n_text16().** wi
32fc0 74 68 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  th calls to sqli
32fd0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
32fe0 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70  ()..**.** ^The p
32ff0 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64  ointers returned
33000 20 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c   are valid until
33010 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69   a type conversi
33020 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a 2a 2a 20  on occurs as.** 
33030 64 65 73 63 72 69 62 65 64 20 61 62 6f 76 65 2c  described above,
33040 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74   or until [sqlit
33050 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73  e3_step()] or [s
33060 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
33070 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  or.** [sqlite3_f
33080 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 63 61  inalize()] is ca
33090 6c 6c 65 64 2e 20 20 5e 54 68 65 20 6d 65 6d 6f  lled.  ^The memo
330a0 72 79 20 73 70 61 63 65 20 75 73 65 64 20 74 6f  ry space used to
330b0 20 68 6f 6c 64 20 73 74 72 69 6e 67 73 0a 2a 2a   hold strings.**
330c0 20 61 6e 64 20 42 4c 4f 42 73 20 69 73 20 66 72   and BLOBs is fr
330d0 65 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  eed automaticall
330e0 79 2e 20 20 44 6f 20 3c 62 3e 6e 6f 74 3c 2f 62  y.  Do <b>not</b
330f0 3e 20 70 61 73 73 20 74 68 65 20 70 6f 69 6e 74  > pass the point
33100 65 72 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  ers returned.** 
33110 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
33120 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65  blob()], [sqlite
33130 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d  3_column_text()]
33140 2c 20 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b  , etc. into.** [
33150 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e  sqlite3_free()].
33160 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 20 6d 65  .**.** ^(If a me
33170 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
33180 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72  error occurs dur
33190 69 6e 67 20 74 68 65 20 65 76 61 6c 75 61 74 69  ing the evaluati
331a0 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20  on of any.** of 
331b0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2c 20  these routines, 
331c0 61 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20  a default value 
331d0 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68  is returned.  Th
331e0 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 0a  e default value.
331f0 2a 2a 20 69 73 20 65 69 74 68 65 72 20 74 68 65  ** is either the
33200 20 69 6e 74 65 67 65 72 20 30 2c 20 74 68 65 20   integer 0, the 
33210 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e  floating point n
33220 75 6d 62 65 72 20 30 2e 30 2c 20 6f 72 20 61 20  umber 0.0, or a 
33230 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e  NULL.** pointer.
33240 20 20 53 75 62 73 65 71 75 65 6e 74 20 63 61 6c    Subsequent cal
33250 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65  ls to [sqlite3_e
33260 72 72 63 6f 64 65 28 29 5d 20 77 69 6c 6c 20 72  rrcode()] will r
33270 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45  eturn.** [SQLITE
33280 5f 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a 2f 0a 53 51  _NOMEM].)^.*/.SQ
33290 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76  LITE_API const v
332a0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
332b0 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33  umn_blob(sqlite3
332c0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
332d0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
332e0 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
332f0 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 73  _bytes(sqlite3_s
33300 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
33310 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
33320 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
33330 79 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f 73  ytes16(sqlite3_s
33340 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
33350 0a 53 51 4c 49 54 45 5f 41 50 49 20 64 6f 75 62  .SQLITE_API doub
33360 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  le sqlite3_colum
33370 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33  n_double(sqlite3
33380 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
33390 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
333a0 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
333b0 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  _int(sqlite3_stm
333c0 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53  t*, int iCol);.S
333d0 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65  QLITE_API sqlite
333e0 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
333f0 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 73 71 6c  column_int64(sql
33400 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
33410 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50  iCol);.SQLITE_AP
33420 49 20 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64  I const unsigned
33430 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
33440 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74  olumn_text(sqlit
33450 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
33460 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  ol);.SQLITE_API 
33470 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
33480 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
33490 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
334a0 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49   int iCol);.SQLI
334b0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
334c0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 73  e3_column_type(s
334d0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
334e0 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f  t iCol);.SQLITE_
334f0 41 50 49 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  API sqlite3_valu
33500 65 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e *sqlite3_colum
33510 6e 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f  n_value(sqlite3_
33520 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
33530 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
33540 46 3a 20 44 65 73 74 72 6f 79 20 41 20 50 72 65  F: Destroy A Pre
33550 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20  pared Statement 
33560 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  Object.**.** ^Th
33570 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  e sqlite3_finali
33580 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73  ze() function is
33590 20 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74   called to delet
335a0 65 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  e a [prepared st
335b0 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 66  atement]..** ^If
335c0 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
335d0 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 74   evaluation of t
335e0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 65 6e 63  he statement enc
335f0 6f 75 6e 74 65 72 65 64 20 6e 6f 20 65 72 72 6f  ountered no erro
33600 72 73 0a 2a 2a 20 6f 72 20 69 66 20 74 68 65 20  rs.** or if the 
33610 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 65 76  statement is nev
33620 65 72 20 62 65 65 6e 20 65 76 61 6c 75 61 74 65  er been evaluate
33630 64 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  d, then sqlite3_
33640 66 69 6e 61 6c 69 7a 65 28 29 20 72 65 74 75 72  finalize() retur
33650 6e 73 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b 2e  ns.** SQLITE_OK.
33660 20 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72    ^If the most r
33670 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e  ecent evaluation
33680 20 6f 66 20 73 74 61 74 65 6d 65 6e 74 20 53 20   of statement S 
33690 66 61 69 6c 65 64 2c 20 74 68 65 6e 0a 2a 2a 20  failed, then.** 
336a0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
336b0 28 53 29 20 72 65 74 75 72 6e 73 20 74 68 65 20  (S) returns the 
336c0 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72  appropriate [err
336d0 6f 72 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b  or code] or.** [
336e0 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63  extended error c
336f0 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ode]..**.** ^The
33700 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
33710 65 28 53 29 20 72 6f 75 74 69 6e 65 20 63 61 6e  e(S) routine can
33720 20 62 65 20 63 61 6c 6c 65 64 20 61 74 20 61 6e   be called at an
33730 79 20 70 6f 69 6e 74 20 64 75 72 69 6e 67 0a 2a  y point during.*
33740 2a 20 74 68 65 20 6c 69 66 65 20 63 79 63 6c 65  * the life cycle
33750 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73 74   of [prepared st
33760 61 74 65 6d 65 6e 74 5d 20 53 3a 0a 2a 2a 20 62  atement] S:.** b
33770 65 66 6f 72 65 20 73 74 61 74 65 6d 65 6e 74 20  efore statement 
33780 53 20 69 73 20 65 76 65 72 20 65 76 61 6c 75 61  S is ever evalua
33790 74 65 64 2c 20 61 66 74 65 72 0a 2a 2a 20 6f 6e  ted, after.** on
337a0 65 20 6f 72 20 6d 6f 72 65 20 63 61 6c 6c 73 20  e or more calls 
337b0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  to [sqlite3_rese
337c0 74 28 29 5d 2c 20 6f 72 20 61 66 74 65 72 20 61  t()], or after a
337d0 6e 79 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20 5b 73  ny call.** to [s
337e0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72  qlite3_step()] r
337f0 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65  egardless of whe
33800 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20  ther or not the 
33810 73 74 61 74 65 6d 65 6e 74 20 68 61 73 0a 2a 2a  statement has.**
33820 20 63 6f 6d 70 6c 65 74 65 64 20 65 78 65 63 75   completed execu
33830 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76  tion..**.** ^Inv
33840 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 69  oking sqlite3_fi
33850 6e 61 6c 69 7a 65 28 29 20 6f 6e 20 61 20 4e 55  nalize() on a NU
33860 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 61 20  LL pointer is a 
33870 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a  harmless no-op..
33880 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  **.** The applic
33890 61 74 69 6f 6e 20 6d 75 73 74 20 66 69 6e 61 6c  ation must final
338a0 69 7a 65 20 65 76 65 72 79 20 5b 70 72 65 70 61  ize every [prepa
338b0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69  red statement] i
338c0 6e 20 6f 72 64 65 72 20 74 6f 20 61 76 6f 69 64  n order to avoid
338d0 0a 2a 2a 20 72 65 73 6f 75 72 63 65 20 6c 65 61  .** resource lea
338e0 6b 73 2e 20 20 49 74 20 69 73 20 61 20 67 72 69  ks.  It is a gri
338f0 65 76 6f 75 73 20 65 72 72 6f 72 20 66 6f 72 20  evous error for 
33900 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
33910 74 6f 20 74 72 79 20 74 6f 20 75 73 65 0a 2a 2a  to try to use.**
33920 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74   a prepared stat
33930 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20 68  ement after it h
33940 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65  as been finalize
33950 64 2e 20 20 41 6e 79 20 75 73 65 20 6f 66 20 61  d.  Any use of a
33960 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61   prepared.** sta
33970 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20  tement after it 
33980 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a  has been finaliz
33990 65 64 20 63 61 6e 20 72 65 73 75 6c 74 20 69 6e  ed can result in
339a0 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 0a 2a   undefined and.*
339b0 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 20 62 65  * undesirable be
339c0 68 61 76 69 6f 72 20 73 75 63 68 20 61 73 20 73  havior such as s
339d0 65 67 66 61 75 6c 74 73 20 61 6e 64 20 68 65 61  egfaults and hea
339e0 70 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f  p corruption..*/
339f0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
33a00 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
33a10 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
33a20 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
33a30 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 20  PI3REF: Reset A 
33a40 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
33a50 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20  nt Object.**.** 
33a60 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 65  The sqlite3_rese
33a70 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  t() function is 
33a80 63 61 6c 6c 65 64 20 74 6f 20 72 65 73 65 74 20  called to reset 
33a90 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
33aa0 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74  ement].** object
33ab0 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69   back to its ini
33ac0 74 69 61 6c 20 73 74 61 74 65 2c 20 72 65 61 64  tial state, read
33ad0 79 20 74 6f 20 62 65 20 72 65 2d 65 78 65 63 75  y to be re-execu
33ae0 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53 51 4c  ted..** ^Any SQL
33af0 20 73 74 61 74 65 6d 65 6e 74 20 76 61 72 69 61   statement varia
33b00 62 6c 65 73 20 74 68 61 74 20 68 61 64 20 76 61  bles that had va
33b10 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f 20 74 68  lues bound to th
33b20 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20  em using.** the 
33b30 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
33b40 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e  ob | sqlite3_bin
33b50 64 5f 2a 28 29 20 41 50 49 5d 20 72 65 74 61 69  d_*() API] retai
33b60 6e 20 74 68 65 69 72 20 76 61 6c 75 65 73 2e 0a  n their values..
33b70 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74 65 33 5f  ** Use [sqlite3_
33b80 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 29  clear_bindings()
33b90 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 62  ] to reset the b
33ba0 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e  indings..**.** ^
33bb0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  The [sqlite3_res
33bc0 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65  et(S)] interface
33bd0 20 72 65 73 65 74 73 20 74 68 65 20 5b 70 72 65   resets the [pre
33be0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
33bf0 20 53 0a 2a 2a 20 62 61 63 6b 20 74 6f 20 74 68   S.** back to th
33c00 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 69  e beginning of i
33c10 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a  ts program..**.*
33c20 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72  * ^If the most r
33c30 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73  ecent call to [s
33c40 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
33c50 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70  for the.** [prep
33c60 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
33c70 53 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49  S returned [SQLI
33c80 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 4c 49  TE_ROW] or [SQLI
33c90 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72 20  TE_DONE],.** or 
33ca0 69 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  if [sqlite3_step
33cb0 28 53 29 5d 20 68 61 73 20 6e 65 76 65 72 20 62  (S)] has never b
33cc0 65 66 6f 72 65 20 62 65 65 6e 20 63 61 6c 6c 65  efore been calle
33cd0 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68 65 6e 20  d on S,.** then 
33ce0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
33cf0 29 5d 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  )] returns [SQLI
33d00 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49  TE_OK]..**.** ^I
33d10 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
33d20 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  t call to [sqlit
33d30 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20  e3_step(S)] for 
33d40 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
33d50 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e   statement] S in
33d60 64 69 63 61 74 65 64 20 61 6e 20 65 72 72 6f 72  dicated an error
33d70 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73 71 6c 69 74  , then.** [sqlit
33d80 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74  e3_reset(S)] ret
33d90 75 72 6e 73 20 61 6e 20 61 70 70 72 6f 70 72 69  urns an appropri
33da0 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ate [error code]
33db0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71  ..**.** ^The [sq
33dc0 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20  lite3_reset(S)] 
33dd0 69 6e 74 65 72 66 61 63 65 20 64 6f 65 73 20 6e  interface does n
33de0 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61  ot change the va
33df0 6c 75 65 73 0a 2a 2a 20 6f 66 20 61 6e 79 20 5b  lues.** of any [
33e00 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
33e10 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 74  b|bindings] on t
33e20 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
33e30 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 53 51  tement] S..*/.SQ
33e40 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
33e50 69 74 65 33 5f 72 65 73 65 74 28 73 71 6c 69 74  ite3_reset(sqlit
33e60 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
33e70 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
33e80 3a 20 43 72 65 61 74 65 20 4f 72 20 52 65 64 65  : Create Or Rede
33e90 66 69 6e 65 20 53 51 4c 20 46 75 6e 63 74 69 6f  fine SQL Functio
33ea0 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ns.** KEYWORDS: 
33eb0 7b 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69  {function creati
33ec0 6f 6e 20 72 6f 75 74 69 6e 65 73 7d 0a 2a 2a 20  on routines}.** 
33ed0 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69  KEYWORDS: {appli
33ee0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
33ef0 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a 2a 20  QL function}.** 
33f00 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69  KEYWORDS: {appli
33f10 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
33f20 51 4c 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a  QL functions}.**
33f30 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74  .** ^These funct
33f40 69 6f 6e 73 20 28 63 6f 6c 6c 65 63 74 69 76 65  ions (collective
33f50 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 22 66 75 6e  ly known as "fun
33f60 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72  ction creation r
33f70 6f 75 74 69 6e 65 73 22 29 0a 2a 2a 20 61 72 65  outines").** are
33f80 20 75 73 65 64 20 74 6f 20 61 64 64 20 53 51 4c   used to add SQL
33f90 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67   functions or ag
33fa0 67 72 65 67 61 74 65 73 20 6f 72 20 74 6f 20 72  gregates or to r
33fb0 65 64 65 66 69 6e 65 20 74 68 65 20 62 65 68 61  edefine the beha
33fc0 76 69 6f 72 0a 2a 2a 20 6f 66 20 65 78 69 73 74  vior.** of exist
33fd0 69 6e 67 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ing SQL function
33fe0 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 2e  s or aggregates.
33ff0 20 20 54 68 65 20 6f 6e 6c 79 20 64 69 66 66 65    The only diffe
34000 72 65 6e 63 65 73 20 62 65 74 77 65 65 6e 0a 2a  rences between.*
34010 2a 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * these routines
34020 20 61 72 65 20 74 68 65 20 74 65 78 74 20 65 6e   are the text en
34030 63 6f 64 69 6e 67 20 65 78 70 65 63 74 65 64 20  coding expected 
34040 66 6f 72 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e  for.** the secon
34050 64 20 70 61 72 61 6d 65 74 65 72 20 28 74 68 65  d parameter (the
34060 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 66 75 6e   name of the fun
34070 63 74 69 6f 6e 20 62 65 69 6e 67 20 63 72 65 61  ction being crea
34080 74 65 64 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20  ted).** and the 
34090 70 72 65 73 65 6e 63 65 20 6f 72 20 61 62 73 65  presence or abse
340a0 6e 63 65 20 6f 66 20 61 20 64 65 73 74 72 75 63  nce of a destruc
340b0 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 66 6f 72  tor callback for
340c0 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74  .** the applicat
340d0 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72  ion data pointer
340e0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ..**.** ^The fir
340f0 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  st parameter is 
34100 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
34110 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 77 68 69  nnection] to whi
34120 63 68 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66 75  ch the SQL.** fu
34130 6e 63 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 20  nction is to be 
34140 61 64 64 65 64 2e 20 20 5e 49 66 20 61 6e 20 61  added.  ^If an a
34150 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 65 73 20  pplication uses 
34160 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 64 61  more than one da
34170 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63  tabase.** connec
34180 74 69 6f 6e 20 74 68 65 6e 20 61 70 70 6c 69 63  tion then applic
34190 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
341a0 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6d 75 73 74  L functions must
341b0 20 62 65 20 61 64 64 65 64 0a 2a 2a 20 74 6f 20   be added.** to 
341c0 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f  each database co
341d0 6e 6e 65 63 74 69 6f 6e 20 73 65 70 61 72 61 74  nnection separat
341e0 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ely..**.** ^The 
341f0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
34200 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
34210 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
34220 20 74 6f 20 62 65 20 63 72 65 61 74 65 64 20 6f   to be created o
34230 72 0a 2a 2a 20 72 65 64 65 66 69 6e 65 64 2e 20  r.** redefined. 
34240 20 5e 54 68 65 20 6c 65 6e 67 74 68 20 6f 66 20   ^The length of 
34250 74 68 65 20 6e 61 6d 65 20 69 73 20 6c 69 6d 69  the name is limi
34260 74 65 64 20 74 6f 20 32 35 35 20 62 79 74 65 73  ted to 255 bytes
34270 20 69 6e 20 61 20 55 54 46 2d 38 0a 2a 2a 20 72   in a UTF-8.** r
34280 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 2c 20 65  epresentation, e
34290 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65 20  xclusive of the 
342a0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 2e  zero-terminator.
342b0 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68 65    ^Note that the
342c0 20 6e 61 6d 65 0a 2a 2a 20 6c 65 6e 67 74 68 20   name.** length 
342d0 6c 69 6d 69 74 20 69 73 20 69 6e 20 55 54 46 2d  limit is in UTF-
342e0 38 20 62 79 74 65 73 2c 20 6e 6f 74 20 63 68 61  8 bytes, not cha
342f0 72 61 63 74 65 72 73 20 6e 6f 72 20 55 54 46 2d  racters nor UTF-
34300 31 36 20 62 79 74 65 73 2e 20 20 0a 2a 2a 20 5e  16 bytes.  .** ^
34310 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63  Any attempt to c
34320 72 65 61 74 65 20 61 20 66 75 6e 63 74 69 6f 6e  reate a function
34330 20 77 69 74 68 20 61 20 6c 6f 6e 67 65 72 20 6e   with a longer n
34340 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72 65 73 75  ame.** will resu
34350 6c 74 20 69 6e 20 5b 53 51 4c 49 54 45 5f 4d 49  lt in [SQLITE_MI
34360 53 55 53 45 5d 20 62 65 69 6e 67 20 72 65 74 75  SUSE] being retu
34370 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  rned..**.** ^The
34380 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
34390 20 28 6e 41 72 67 29 0a 2a 2a 20 69 73 20 74 68   (nArg).** is th
343a0 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75  e number of argu
343b0 6d 65 6e 74 73 20 74 68 61 74 20 74 68 65 20 53  ments that the S
343c0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a  QL function or.*
343d0 2a 20 61 67 67 72 65 67 61 74 65 20 74 61 6b 65  * aggregate take
343e0 73 2e 20 5e 49 66 20 74 68 69 73 20 70 61 72 61  s. ^If this para
343f0 6d 65 74 65 72 20 69 73 20 2d 31 2c 20 74 68 65  meter is -1, the
34400 6e 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  n the SQL functi
34410 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61  on or.** aggrega
34420 74 65 20 6d 61 79 20 74 61 6b 65 20 61 6e 79 20  te may take any 
34430 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65  number of argume
34440 6e 74 73 20 62 65 74 77 65 65 6e 20 30 20 61 6e  nts between 0 an
34450 64 20 74 68 65 20 6c 69 6d 69 74 0a 2a 2a 20 73  d the limit.** s
34460 65 74 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c  et by [sqlite3_l
34470 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f 4c 49  imit]([SQLITE_LI
34480 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47  MIT_FUNCTION_ARG
34490 5d 29 2e 20 20 49 66 20 74 68 65 20 74 68 69 72  ]).  If the thir
344a0 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69  d.** parameter i
344b0 73 20 6c 65 73 73 20 74 68 61 6e 20 2d 31 20 6f  s less than -1 o
344c0 72 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 31  r greater than 1
344d0 32 37 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  27 then the beha
344e0 76 69 6f 72 20 69 73 0a 2a 2a 20 75 6e 64 65 66  vior is.** undef
344f0 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ined..**.** ^The
34500 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
34510 72 2c 20 65 54 65 78 74 52 65 70 2c 20 73 70 65  r, eTextRep, spe
34520 63 69 66 69 65 73 20 77 68 61 74 0a 2a 2a 20 5b  cifies what.** [
34530 53 51 4c 49 54 45 5f 55 54 46 38 20 7c 20 74 65  SQLITE_UTF8 | te
34540 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 74 68 69  xt encoding] thi
34550 73 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 70  s SQL function p
34560 72 65 66 65 72 73 20 66 6f 72 0a 2a 2a 20 69 74  refers for.** it
34570 73 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 45  s parameters.  E
34580 76 65 72 79 20 53 51 4c 20 66 75 6e 63 74 69 6f  very SQL functio
34590 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
345a0 20 6d 75 73 74 20 62 65 20 61 62 6c 65 20 74 6f   must be able to
345b0 20 77 6f 72 6b 0a 2a 2a 20 77 69 74 68 20 55 54   work.** with UT
345c0 46 2d 38 2c 20 55 54 46 2d 31 36 6c 65 2c 20 6f  F-8, UTF-16le, o
345d0 72 20 55 54 46 2d 31 36 62 65 2e 20 20 42 75 74  r UTF-16be.  But
345e0 20 73 6f 6d 65 20 69 6d 70 6c 65 6d 65 6e 74 61   some implementa
345f0 74 69 6f 6e 73 20 6d 61 79 20 62 65 0a 2a 2a 20  tions may be.** 
34600 6d 6f 72 65 20 65 66 66 69 63 69 65 6e 74 20 77  more efficient w
34610 69 74 68 20 6f 6e 65 20 65 6e 63 6f 64 69 6e 67  ith one encoding
34620 20 74 68 61 6e 20 61 6e 6f 74 68 65 72 2e 20 20   than another.  
34630 5e 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  ^An application 
34640 6d 61 79 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71  may.** invoke sq
34650 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
34660 63 74 69 6f 6e 28 29 20 6f 72 20 73 71 6c 69 74  ction() or sqlit
34670 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
34680 6f 6e 31 36 28 29 20 6d 75 6c 74 69 70 6c 65 0a  on16() multiple.
34690 2a 2a 20 74 69 6d 65 73 20 77 69 74 68 20 74 68  ** times with th
346a0 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20  e same function 
346b0 62 75 74 20 77 69 74 68 20 64 69 66 66 65 72 65  but with differe
346c0 6e 74 20 76 61 6c 75 65 73 20 6f 66 20 65 54 65  nt values of eTe
346d0 78 74 52 65 70 2e 0a 2a 2a 20 5e 57 68 65 6e 20  xtRep..** ^When 
346e0 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65  multiple impleme
346f0 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ntations of the 
34700 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 61 72  same function ar
34710 65 20 61 76 61 69 6c 61 62 6c 65 2c 20 53 51 4c  e available, SQL
34720 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 69 63 6b  ite.** will pick
34730 20 74 68 65 20 6f 6e 65 20 74 68 61 74 20 69 6e   the one that in
34740 76 6f 6c 76 65 73 20 74 68 65 20 6c 65 61 73 74  volves the least
34750 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61 20   amount of data 
34760 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20 49  conversion..** I
34770 66 20 74 68 65 72 65 20 69 73 20 6f 6e 6c 79 20  f there is only 
34780 61 20 73 69 6e 67 6c 65 20 69 6d 70 6c 65 6d 65  a single impleme
34790 6e 74 61 74 69 6f 6e 20 77 68 69 63 68 20 64 6f  ntation which do
347a0 65 73 20 6e 6f 74 20 63 61 72 65 20 77 68 61 74  es not care what
347b0 20 74 65 78 74 0a 2a 2a 20 65 6e 63 6f 64 69 6e   text.** encodin
347c0 67 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20  g is used, then 
347d0 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d  the fourth argum
347e0 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 5b 53  ent should be [S
347f0 51 4c 49 54 45 5f 41 4e 59 5d 2e 0a 2a 2a 0a 2a  QLITE_ANY]..**.*
34800 2a 20 5e 28 54 68 65 20 66 69 66 74 68 20 70 61  * ^(The fifth pa
34810 72 61 6d 65 74 65 72 20 69 73 20 61 6e 20 61 72  rameter is an ar
34820 62 69 74 72 61 72 79 20 70 6f 69 6e 74 65 72 2e  bitrary pointer.
34830 20 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61    The implementa
34840 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 66  tion of the.** f
34850 75 6e 63 74 69 6f 6e 20 63 61 6e 20 67 61 69 6e  unction can gain
34860 20 61 63 63 65 73 73 20 74 6f 20 74 68 69 73 20   access to this 
34870 70 6f 69 6e 74 65 72 20 75 73 69 6e 67 20 5b 73  pointer using [s
34880 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61  qlite3_user_data
34890 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ()].)^.**.** ^Th
348a0 65 20 73 69 78 74 68 2c 20 73 65 76 65 6e 74 68  e sixth, seventh
348b0 20 61 6e 64 20 65 69 67 68 74 68 20 70 61 72 61   and eighth para
348c0 6d 65 74 65 72 73 2c 20 78 46 75 6e 63 2c 20 78  meters, xFunc, x
348d0 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 2c  Step and xFinal,
348e0 20 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 73   are.** pointers
348f0 20 74 6f 20 43 2d 6c 61 6e 67 75 61 67 65 20 66   to C-language f
34900 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 69 6d  unctions that im
34910 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20  plement the SQL 
34920 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61  function or.** a
34930 67 67 72 65 67 61 74 65 2e 20 5e 41 20 73 63 61  ggregate. ^A sca
34940 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  lar SQL function
34950 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70   requires an imp
34960 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74  lementation of t
34970 68 65 20 78 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c  he xFunc.** call
34980 62 61 63 6b 20 6f 6e 6c 79 3b 20 4e 55 4c 4c 20  back only; NULL 
34990 70 6f 69 6e 74 65 72 73 20 6d 75 73 74 20 62 65  pointers must be
349a0 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 78   passed as the x
349b0 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 0a  Step and xFinal.
349c0 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20 5e  ** parameters. ^
349d0 41 6e 20 61 67 67 72 65 67 61 74 65 20 53 51 4c  An aggregate SQL
349e0 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72   function requir
349f0 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  es an implementa
34a00 74 69 6f 6e 20 6f 66 20 78 53 74 65 70 0a 2a 2a  tion of xStep.**
34a10 20 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e 64 20   and xFinal and 
34a20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6d 75 73  NULL pointer mus
34a30 74 20 62 65 20 70 61 73 73 65 64 20 66 6f 72 20  t be passed for 
34a40 78 46 75 6e 63 2e 20 5e 54 6f 20 64 65 6c 65 74  xFunc. ^To delet
34a50 65 20 61 6e 20 65 78 69 73 74 69 6e 67 0a 2a 2a  e an existing.**
34a60 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72   SQL function or
34a70 20 61 67 67 72 65 67 61 74 65 2c 20 70 61 73 73   aggregate, pass
34a80 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 66   NULL pointers f
34a90 6f 72 20 61 6c 6c 20 74 68 72 65 65 20 66 75 6e  or all three fun
34aa0 63 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63  ction.** callbac
34ab0 6b 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74  ks..**.** ^(If t
34ac0 68 65 20 6e 69 6e 74 68 20 70 61 72 61 6d 65 74  he ninth paramet
34ad0 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72  er to sqlite3_cr
34ae0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32  eate_function_v2
34af0 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a  () is not NULL,.
34b00 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 64 65  ** then it is de
34b10 73 74 72 75 63 74 6f 72 20 66 6f 72 20 74 68 65  structor for the
34b20 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74   application dat
34b30 61 20 70 6f 69 6e 74 65 72 2e 20 0a 2a 2a 20 54  a pointer. .** T
34b40 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73  he destructor is
34b50 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74 68   invoked when th
34b60 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 65  e function is de
34b70 6c 65 74 65 64 2c 20 65 69 74 68 65 72 20 62 79  leted, either by
34b80 20 62 65 69 6e 67 0a 2a 2a 20 6f 76 65 72 6c 6f   being.** overlo
34b90 61 64 65 64 20 6f 72 20 77 68 65 6e 20 74 68 65  aded or when the
34ba0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
34bb0 74 69 6f 6e 20 63 6c 6f 73 65 73 2e 29 5e 0a 2a  tion closes.)^.*
34bc0 2a 20 5e 54 68 65 20 64 65 73 74 72 75 63 74 6f  * ^The destructo
34bd0 72 20 69 73 20 61 6c 73 6f 20 69 6e 76 6f 6b 65  r is also invoke
34be0 64 20 69 66 20 74 68 65 20 63 61 6c 6c 20 74 6f  d if the call to
34bf0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61  .** sqlite3_crea
34c00 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29  te_function_v2()
34c10 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 57 68 65 6e   fails..** ^When
34c20 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   the destructor 
34c30 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20  callback of the 
34c40 74 65 6e 74 68 20 70 61 72 61 6d 65 74 65 72 20  tenth parameter 
34c50 69 73 20 69 6e 76 6f 6b 65 64 2c 20 69 74 0a 2a  is invoked, it.*
34c60 2a 20 69 73 20 70 61 73 73 65 64 20 61 20 73 69  * is passed a si
34c70 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
34c80 69 63 68 20 69 73 20 61 20 63 6f 70 79 20 6f 66  ich is a copy of
34c90 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
34ca0 20 64 61 74 61 20 0a 2a 2a 20 70 6f 69 6e 74 65   data .** pointe
34cb0 72 20 77 68 69 63 68 20 77 61 73 20 74 68 65 20  r which was the 
34cc0 66 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 20  fifth parameter 
34cd0 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  to sqlite3_creat
34ce0 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 2e  e_function_v2().
34cf0 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 70 65  .**.** ^It is pe
34d00 72 6d 69 74 74 65 64 20 74 6f 20 72 65 67 69 73  rmitted to regis
34d10 74 65 72 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70  ter multiple imp
34d20 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20  lementations of 
34d30 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75 6e 63  the same.** func
34d40 74 69 6f 6e 73 20 77 69 74 68 20 74 68 65 20 73  tions with the s
34d50 61 6d 65 20 6e 61 6d 65 20 62 75 74 20 77 69 74  ame name but wit
34d60 68 20 65 69 74 68 65 72 20 64 69 66 66 65 72 69  h either differi
34d70 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a 2a 2a  ng numbers of.**
34d80 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 64 69   arguments or di
34d90 66 66 65 72 69 6e 67 20 70 72 65 66 65 72 72 65  ffering preferre
34da0 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73  d text encodings
34db0 2e 20 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20  .  ^SQLite will 
34dc0 75 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65  use.** the imple
34dd0 6d 65 6e 74 61 74 69 6f 6e 20 74 68 61 74 20 6d  mentation that m
34de0 6f 73 74 20 63 6c 6f 73 65 6c 79 20 6d 61 74 63  ost closely matc
34df0 68 65 73 20 74 68 65 20 77 61 79 20 69 6e 20 77  hes the way in w
34e00 68 69 63 68 20 74 68 65 0a 2a 2a 20 53 51 4c 20  hich the.** SQL 
34e10 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64  function is used
34e20 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 69  .  ^A function i
34e30 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69  mplementation wi
34e40 74 68 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  th a non-negativ
34e50 65 0a 2a 2a 20 6e 41 72 67 20 70 61 72 61 6d 65  e.** nArg parame
34e60 74 65 72 20 69 73 20 61 20 62 65 74 74 65 72 20  ter is a better 
34e70 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e  match than a fun
34e80 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  ction implementa
34e90 74 69 6f 6e 20 77 69 74 68 0a 2a 2a 20 61 20 6e  tion with.** a n
34ea0 65 67 61 74 69 76 65 20 6e 41 72 67 2e 20 20 5e  egative nArg.  ^
34eb0 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65  A function where
34ec0 20 74 68 65 20 70 72 65 66 65 72 72 65 64 20 74   the preferred t
34ed0 65 78 74 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20  ext encoding.** 
34ee0 6d 61 74 63 68 65 73 20 74 68 65 20 64 61 74 61  matches the data
34ef0 62 61 73 65 20 65 6e 63 6f 64 69 6e 67 20 69 73  base encoding is
34f00 20 61 20 62 65 74 74 65 72 0a 2a 2a 20 6d 61 74   a better.** mat
34f10 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69  ch than a functi
34f20 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63  on where the enc
34f30 6f 64 69 6e 67 20 69 73 20 64 69 66 66 65 72 65  oding is differe
34f40 6e 74 2e 20 20 0a 2a 2a 20 5e 41 20 66 75 6e 63  nt.  .** ^A func
34f50 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65  tion where the e
34f60 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e  ncoding differen
34f70 63 65 20 69 73 20 62 65 74 77 65 65 6e 20 55 54  ce is between UT
34f80 46 31 36 6c 65 20 61 6e 64 20 55 54 46 31 36 62  F16le and UTF16b
34f90 65 0a 2a 2a 20 69 73 20 61 20 63 6c 6f 73 65 72  e.** is a closer
34fa0 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75   match than a fu
34fb0 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65  nction where the
34fc0 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72   encoding differ
34fd0 65 6e 63 65 20 69 73 0a 2a 2a 20 62 65 74 77 65  ence is.** betwe
34fe0 65 6e 20 55 54 46 38 20 61 6e 64 20 55 54 46 31  en UTF8 and UTF1
34ff0 36 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75 69 6c 74 2d  6..**.** ^Built-
35000 69 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79  in functions may
35010 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 20 62   be overloaded b
35020 79 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f  y new applicatio
35030 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
35040 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61  ons..**.** ^An a
35050 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
35060 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 70  ed function is p
35070 65 72 6d 69 74 74 65 64 20 74 6f 20 63 61 6c 6c  ermitted to call
35080 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65   other.** SQLite
35090 20 69 6e 74 65 72 66 61 63 65 73 2e 20 20 48 6f   interfaces.  Ho
350a0 77 65 76 65 72 2c 20 73 75 63 68 20 63 61 6c 6c  wever, such call
350b0 73 20 6d 75 73 74 20 6e 6f 74 0a 2a 2a 20 63 6c  s must not.** cl
350c0 6f 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65  ose the database
350d0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6e 6f 72 20   connection nor 
350e0 66 69 6e 61 6c 69 7a 65 20 6f 72 20 72 65 73 65  finalize or rese
350f0 74 20 74 68 65 20 70 72 65 70 61 72 65 64 0a 2a  t the prepared.*
35100 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 77  * statement in w
35110 68 69 63 68 20 74 68 65 20 66 75 6e 63 74 69 6f  hich the functio
35120 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f  n is running..*/
35130 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
35140 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
35150 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74  unction(.  sqlit
35160 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20  e3 *db,.  const 
35170 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e  char *zFunctionN
35180 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c  ame,.  int nArg,
35190 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c  .  int eTextRep,
351a0 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20  .  void *pApp,. 
351b0 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73   void (*xFunc)(s
351c0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
351d0 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
351e0 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
351f0 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f  Step)(sqlite3_co
35200 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
35210 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
35220 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71  oid (*xFinal)(sq
35230 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a  lite3_context*).
35240 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
35250 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
35260 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20 20 73  _function16(.  s
35270 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f  qlite3 *db,.  co
35280 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e 63 74  nst void *zFunct
35290 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e  ionName,.  int n
352a0 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74  Arg,.  int eText
352b0 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70  Rep,.  void *pAp
352c0 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e  p,.  void (*xFun
352d0 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  c)(sqlite3_conte
352e0 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
352f0 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
35300 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65   (*xStep)(sqlite
35310 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
35320 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
35330 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c  .  void (*xFinal
35340 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
35350 74 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  t*).);.SQLITE_AP
35360 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72  I int sqlite3_cr
35370 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32  eate_function_v2
35380 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
35390 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
353a0 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20  FunctionName,.  
353b0 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20  int nArg,.  int 
353c0 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64  eTextRep,.  void
353d0 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28   *pApp,.  void (
353e0 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f  *xFunc)(sqlite3_
353f0 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
35400 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
35410 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73   void (*xStep)(s
35420 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
35430 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
35440 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
35450 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63  Final)(sqlite3_c
35460 6f 6e 74 65 78 74 2a 29 2c 0a 20 20 76 6f 69 64  ontext*),.  void
35470 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64  (*xDestroy)(void
35480 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  *).);../*.** CAP
35490 49 33 52 45 46 3a 20 54 65 78 74 20 45 6e 63 6f  I3REF: Text Enco
354a0 64 69 6e 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  dings.**.** Thes
354b0 65 20 63 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e  e constant defin
354c0 65 20 69 6e 74 65 67 65 72 20 63 6f 64 65 73 20  e integer codes 
354d0 74 68 61 74 20 72 65 70 72 65 73 65 6e 74 20 74  that represent t
354e0 68 65 20 76 61 72 69 6f 75 73 0a 2a 2a 20 74 65  he various.** te
354f0 78 74 20 65 6e 63 6f 64 69 6e 67 73 20 73 75 70  xt encodings sup
35500 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74 65  ported by SQLite
35510 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
35520 49 54 45 5f 55 54 46 38 20 20 20 20 20 20 20 20  ITE_UTF8        
35530 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c     1.#define SQL
35540 49 54 45 5f 55 54 46 31 36 4c 45 20 20 20 20 20  ITE_UTF16LE     
35550 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
35560 49 54 45 5f 55 54 46 31 36 42 45 20 20 20 20 20  ITE_UTF16BE     
35570 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c     3.#define SQL
35580 49 54 45 5f 55 54 46 31 36 20 20 20 20 20 20 20  ITE_UTF16       
35590 20 20 20 34 20 20 20 20 2f 2a 20 55 73 65 20 6e     4    /* Use n
355a0 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
355b0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
355c0 54 45 5f 41 4e 59 20 20 20 20 20 20 20 20 20 20  TE_ANY          
355d0 20 20 35 20 20 20 20 2f 2a 20 73 71 6c 69 74 65    5    /* sqlite
355e0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
355f0 6e 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e  n only */.#defin
35600 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41  e SQLITE_UTF16_A
35610 4c 49 47 4e 45 44 20 20 38 20 20 20 20 2f 2a 20  LIGNED  8    /* 
35620 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
35630 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f  ollation only */
35640 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
35650 3a 20 44 65 70 72 65 63 61 74 65 64 20 46 75 6e  : Deprecated Fun
35660 63 74 69 6f 6e 73 0a 2a 2a 20 44 45 50 52 45 43  ctions.** DEPREC
35670 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ATED.**.** These
35680 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 5b   functions are [
35690 64 65 70 72 65 63 61 74 65 64 5d 2e 20 20 49 6e  deprecated].  In
356a0 20 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e 74 61   order to mainta
356b0 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20  in.** backwards 
356c0 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 77 69  compatibility wi
356d0 74 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c 20 74  th older code, t
356e0 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 63  hese functions c
356f0 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20 74 6f 20 62  ontinue .** to b
35700 65 20 73 75 70 70 6f 72 74 65 64 2e 20 20 48 6f  e supported.  Ho
35710 77 65 76 65 72 2c 20 6e 65 77 20 61 70 70 6c 69  wever, new appli
35720 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 61  cations should a
35730 76 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73 65 20  void.** the use 
35740 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  of these functio
35750 6e 73 2e 20 20 54 6f 20 68 65 6c 70 20 65 6e 63  ns.  To help enc
35760 6f 75 72 61 67 65 20 70 65 6f 70 6c 65 20 74 6f  ourage people to
35770 20 61 76 6f 69 64 0a 2a 2a 20 75 73 69 6e 67 20   avoid.** using 
35780 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2c  these functions,
35790 20 77 65 20 61 72 65 20 6e 6f 74 20 67 6f 69 6e   we are not goin
357a0 67 20 74 6f 20 74 65 6c 6c 20 79 6f 75 20 77 68  g to tell you wh
357b0 61 74 20 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a 23  at they do..*/.#
357c0 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d  ifndef SQLITE_OM
357d0 49 54 5f 44 45 50 52 45 43 41 54 45 44 0a 53 51  IT_DEPRECATED.SQ
357e0 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f  LITE_API SQLITE_
357f0 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73  DEPRECATED int s
35800 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
35810 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 63  _count(sqlite3_c
35820 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45  ontext*);.SQLITE
35830 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52  _API SQLITE_DEPR
35840 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74  ECATED int sqlit
35850 65 33 5f 65 78 70 69 72 65 64 28 73 71 6c 69 74  e3_expired(sqlit
35860 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54  e3_stmt*);.SQLIT
35870 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50  E_API SQLITE_DEP
35880 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69  RECATED int sqli
35890 74 65 33 5f 74 72 61 6e 73 66 65 72 5f 62 69 6e  te3_transfer_bin
358a0 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74  dings(sqlite3_st
358b0 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d  mt*, sqlite3_stm
358c0 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  t*);.SQLITE_API 
358d0 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
358e0 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 6c  D int sqlite3_gl
358f0 6f 62 61 6c 5f 72 65 63 6f 76 65 72 28 76 6f 69  obal_recover(voi
35900 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53  d);.SQLITE_API S
35910 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
35920 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 74 68   void sqlite3_th
35930 72 65 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69  read_cleanup(voi
35940 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53  d);.SQLITE_API S
35950 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
35960 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d   int sqlite3_mem
35970 6f 72 79 5f 61 6c 61 72 6d 28 76 6f 69 64 28 2a  ory_alarm(void(*
35980 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f  )(void*,sqlite3_
35990 69 6e 74 36 34 2c 69 6e 74 29 2c 0a 20 20 20 20  int64,int),.    
359a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
359b0 20 20 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f    void*,sqlite3_
359c0 69 6e 74 36 34 29 3b 0a 23 65 6e 64 69 66 0a 0a  int64);.#endif..
359d0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
359e0 4f 62 74 61 69 6e 69 6e 67 20 53 51 4c 20 46 75  Obtaining SQL Fu
359f0 6e 63 74 69 6f 6e 20 50 61 72 61 6d 65 74 65 72  nction Parameter
35a00 20 56 61 6c 75 65 73 0a 2a 2a 0a 2a 2a 20 54 68   Values.**.** Th
35a10 65 20 43 2d 6c 61 6e 67 75 61 67 65 20 69 6d 70  e C-language imp
35a20 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 53  lementation of S
35a30 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64  QL functions and
35a40 20 61 67 67 72 65 67 61 74 65 73 20 75 73 65 73   aggregates uses
35a50 0a 2a 2a 20 74 68 69 73 20 73 65 74 20 6f 66 20  .** this set of 
35a60 69 6e 74 65 72 66 61 63 65 20 72 6f 75 74 69 6e  interface routin
35a70 65 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65  es to access the
35a80 20 70 61 72 61 6d 65 74 65 72 20 76 61 6c 75 65   parameter value
35a90 73 20 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 6e 63  s on.** the func
35aa0 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74  tion or aggregat
35ab0 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 75  e..**.** The xFu
35ac0 6e 63 20 28 66 6f 72 20 73 63 61 6c 61 72 20 66  nc (for scalar f
35ad0 75 6e 63 74 69 6f 6e 73 29 20 6f 72 20 78 53 74  unctions) or xSt
35ae0 65 70 20 28 66 6f 72 20 61 67 67 72 65 67 61 74  ep (for aggregat
35af0 65 73 29 20 70 61 72 61 6d 65 74 65 72 73 0a 2a  es) parameters.*
35b00 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72  * to [sqlite3_cr
35b10 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
35b20 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72   and [sqlite3_cr
35b30 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
35b40 29 5d 0a 2a 2a 20 64 65 66 69 6e 65 20 63 61 6c  )].** define cal
35b50 6c 62 61 63 6b 73 20 74 68 61 74 20 69 6d 70 6c  lbacks that impl
35b60 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75  ement the SQL fu
35b70 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72  nctions and aggr
35b80 65 67 61 74 65 73 2e 0a 2a 2a 20 54 68 65 20 33  egates..** The 3
35b90 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
35ba0 74 68 65 73 65 20 63 61 6c 6c 62 61 63 6b 73 20  these callbacks 
35bb0 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  is an array of p
35bc0 6f 69 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 5b 70  ointers to.** [p
35bd0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
35be0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e  _value] objects.
35bf0 20 20 54 68 65 72 65 20 69 73 20 6f 6e 65 20 5b    There is one [
35c00 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
35c10 62 6a 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63  bject for.** eac
35c20 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
35c30 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e  he SQL function.
35c40 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73    These routines
35c50 20 61 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20   are used to.** 
35c60 65 78 74 72 61 63 74 20 76 61 6c 75 65 73 20 66  extract values f
35c70 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33  rom the [sqlite3
35c80 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e  _value] objects.
35c90 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
35ca0 74 69 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 20  tines work only 
35cb0 77 69 74 68 20 5b 70 72 6f 74 65 63 74 65 64 20  with [protected 
35cc0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
35cd0 62 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 61  bjects..** Any a
35ce0 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68  ttempt to use th
35cf0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 20  ese routines on 
35d00 61 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  an [unprotected 
35d10 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a  sqlite3_value].*
35d20 2a 20 6f 62 6a 65 63 74 20 72 65 73 75 6c 74 73  * object results
35d30 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65   in undefined be
35d40 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  havior..**.** ^T
35d50 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f  hese routines wo
35d60 72 6b 20 6a 75 73 74 20 6c 69 6b 65 20 74 68 65  rk just like the
35d70 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 5b   corresponding [
35d80 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75  column access fu
35d90 6e 63 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65  nctions].** exce
35da0 70 74 20 74 68 61 74 20 20 74 68 65 73 65 20 72  pt that  these r
35db0 6f 75 74 69 6e 65 73 20 74 61 6b 65 20 61 20 73  outines take a s
35dc0 69 6e 67 6c 65 20 5b 70 72 6f 74 65 63 74 65 64  ingle [protected
35dd0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
35de0 6f 62 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e 74 65  object.** pointe
35df0 72 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 5b  r instead of a [
35e00 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20 70  sqlite3_stmt*] p
35e10 6f 69 6e 74 65 72 20 61 6e 64 20 61 6e 20 69 6e  ointer and an in
35e20 74 65 67 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d  teger column num
35e30 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ber..**.** ^The 
35e40 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
35e50 78 74 31 36 28 29 20 69 6e 74 65 72 66 61 63 65  xt16() interface
35e60 20 65 78 74 72 61 63 74 73 20 61 20 55 54 46 2d   extracts a UTF-
35e70 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69 6e 20  16 string.** in 
35e80 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 2d  the native byte-
35e90 6f 72 64 65 72 20 6f 66 20 74 68 65 20 68 6f 73  order of the hos
35ea0 74 20 6d 61 63 68 69 6e 65 2e 20 20 5e 54 68 65  t machine.  ^The
35eb0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
35ec0 65 5f 74 65 78 74 31 36 62 65 28 29 20 61 6e 64  e_text16be() and
35ed0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
35ee0 65 78 74 31 36 6c 65 28 29 20 69 6e 74 65 72 66  ext16le() interf
35ef0 61 63 65 73 0a 2a 2a 20 65 78 74 72 61 63 74 20  aces.** extract 
35f00 55 54 46 2d 31 36 20 73 74 72 69 6e 67 73 20 61  UTF-16 strings a
35f10 73 20 62 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64  s big-endian and
35f20 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72   little-endian r
35f30 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a  espectively..**.
35f40 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33  ** ^(The sqlite3
35f50 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74  _value_numeric_t
35f60 79 70 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  ype() interface 
35f70 61 74 74 65 6d 70 74 73 20 74 6f 20 61 70 70 6c  attempts to appl
35f80 79 0a 2a 2a 20 6e 75 6d 65 72 69 63 20 61 66 66  y.** numeric aff
35f90 69 6e 69 74 79 20 74 6f 20 74 68 65 20 76 61 6c  inity to the val
35fa0 75 65 2e 20 20 54 68 69 73 20 6d 65 61 6e 73 20  ue.  This means 
35fb0 74 68 61 74 20 61 6e 20 61 74 74 65 6d 70 74 20  that an attempt 
35fc0 69 73 0a 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f  is.** made to co
35fd0 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75 65 20  nvert the value 
35fe0 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 6f 72  to an integer or
35ff0 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e   floating point.
36000 20 20 49 66 0a 2a 2a 20 73 75 63 68 20 61 20 63    If.** such a c
36010 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 6f 73  onversion is pos
36020 73 69 62 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f  sible without lo
36030 73 73 20 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f  ss of informatio
36040 6e 20 28 69 6e 20 6f 74 68 65 72 0a 2a 2a 20 77  n (in other.** w
36050 6f 72 64 73 2c 20 69 66 20 74 68 65 20 76 61 6c  ords, if the val
36060 75 65 20 69 73 20 61 20 73 74 72 69 6e 67 20 74  ue is a string t
36070 68 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61  hat looks like a
36080 20 6e 75 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e   number).** then
36090 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20   the conversion 
360a0 69 73 20 70 65 72 66 6f 72 6d 65 64 2e 20 20 4f  is performed.  O
360b0 74 68 65 72 77 69 73 65 20 6e 6f 20 63 6f 6e 76  therwise no conv
360c0 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a  ersion occurs..*
360d0 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 4e  * The [SQLITE_IN
360e0 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65  TEGER | datatype
360f0 5d 20 61 66 74 65 72 20 63 6f 6e 76 65 72 73 69  ] after conversi
36100 6f 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29  on is returned.)
36110 5e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 70  ^.**.** Please p
36120 61 79 20 70 61 72 74 69 63 75 6c 61 72 20 61 74  ay particular at
36130 74 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65 20 66  tention to the f
36140 61 63 74 20 74 68 61 74 20 74 68 65 20 70 6f 69  act that the poi
36150 6e 74 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a  nter returned.**
36160 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76   from [sqlite3_v
36170 61 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73  alue_blob()], [s
36180 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
36190 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c  t()], or.** [sql
361a0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
361b0 36 28 29 5d 20 63 61 6e 20 62 65 20 69 6e 76 61  6()] can be inva
361c0 6c 69 64 61 74 65 64 20 62 79 20 61 20 73 75 62  lidated by a sub
361d0 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 0a  sequent call to.
361e0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ** [sqlite3_valu
361f0 65 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73 71 6c  e_bytes()], [sql
36200 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
36210 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  16()], [sqlite3_
36220 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a  value_text()],.*
36230 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61  * or [sqlite3_va
36240 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 2e 0a 2a  lue_text16()]..*
36250 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
36260 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  nes must be call
36270 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65  ed from the same
36280 20 74 68 72 65 61 64 20 61 73 0a 2a 2a 20 74 68   thread as.** th
36290 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74  e SQL function t
362a0 68 61 74 20 73 75 70 70 6c 69 65 64 20 74 68 65  hat supplied the
362b0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a   [sqlite3_value*
362c0 5d 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2f  ] parameters..*/
362d0 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
362e0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
362f0 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 69 74  value_blob(sqlit
36300 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49  e3_value*);.SQLI
36310 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
36320 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 73  e3_value_bytes(s
36330 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
36340 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
36350 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
36360 65 73 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c  es16(sqlite3_val
36370 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  ue*);.SQLITE_API
36380 20 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f   double sqlite3_
36390 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73 71 6c  value_double(sql
363a0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51  ite3_value*);.SQ
363b0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
363c0 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 73  ite3_value_int(s
363d0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
363e0 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74  SQLITE_API sqlit
363f0 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
36400 5f 76 61 6c 75 65 5f 69 6e 74 36 34 28 73 71 6c  _value_int64(sql
36410 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51  ite3_value*);.SQ
36420 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 75  LITE_API const u
36430 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71  nsigned char *sq
36440 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
36450 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
36460 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  ;.SQLITE_API con
36470 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
36480 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 73 71  _value_text16(sq
36490 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53  lite3_value*);.S
364a0 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
364b0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61  void *sqlite3_va
364c0 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 73 71 6c  lue_text16le(sql
364d0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51  ite3_value*);.SQ
364e0 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76  LITE_API const v
364f0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c  oid *sqlite3_val
36500 75 65 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69  ue_text16be(sqli
36510 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c  te3_value*);.SQL
36520 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
36530 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 73  te3_value_type(s
36540 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
36550 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
36560 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d  qlite3_value_num
36570 65 72 69 63 5f 74 79 70 65 28 73 71 6c 69 74 65  eric_type(sqlite
36580 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a  3_value*);../*.*
36590 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61  * CAPI3REF: Obta
365a0 69 6e 20 41 67 67 72 65 67 61 74 65 20 46 75 6e  in Aggregate Fun
365b0 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 0a 2a 2a  ction Context.**
365c0 0a 2a 2a 20 49 6d 70 6c 65 6d 65 6e 74 61 74 69  .** Implementati
365d0 6f 6e 73 20 6f 66 20 61 67 67 72 65 67 61 74 65  ons of aggregate
365e0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 75   SQL functions u
365f0 73 65 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69  se this.** routi
36600 6e 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d  ne to allocate m
36610 65 6d 6f 72 79 20 66 6f 72 20 73 74 6f 72 69 6e  emory for storin
36620 67 20 74 68 65 69 72 20 73 74 61 74 65 2e 0a 2a  g their state..*
36630 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
36640 74 69 6d 65 20 74 68 65 20 73 71 6c 69 74 65 33  time the sqlite3
36650 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
36660 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20  xt(C,N) routine 
36670 69 73 20 63 61 6c 6c 65 64 20 0a 2a 2a 20 66 6f  is called .** fo
36680 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 61  r a particular a
36690 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f  ggregate functio
366a0 6e 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6c 6c  n, SQLite.** all
366b0 6f 63 61 74 65 73 20 4e 20 6f 66 20 6d 65 6d 6f  ocates N of memo
366c0 72 79 2c 20 7a 65 72 6f 65 73 20 6f 75 74 20 74  ry, zeroes out t
366d0 68 61 74 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 20  hat memory, and 
366e0 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
366f0 72 0a 2a 2a 20 74 6f 20 74 68 65 20 6e 65 77 20  r.** to the new 
36700 6d 65 6d 6f 72 79 2e 20 5e 4f 6e 20 73 65 63 6f  memory. ^On seco
36710 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e  nd and subsequen
36720 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71  t calls to.** sq
36730 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
36740 63 6f 6e 74 65 78 74 28 29 20 66 6f 72 20 74 68  context() for th
36750 65 20 73 61 6d 65 20 61 67 67 72 65 67 61 74 65  e same aggregate
36760 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e   function instan
36770 63 65 2c 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20  ce,.** the same 
36780 62 75 66 66 65 72 20 69 73 20 72 65 74 75 72 6e  buffer is return
36790 65 64 2e 20 20 53 71 6c 69 74 65 33 5f 61 67 67  ed.  Sqlite3_agg
367a0 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29  regate_context()
367b0 20 69 73 20 6e 6f 72 6d 61 6c 6c 79 0a 2a 2a 20   is normally.** 
367c0 63 61 6c 6c 65 64 20 6f 6e 63 65 20 66 6f 72 20  called once for 
367d0 65 61 63 68 20 69 6e 76 6f 63 61 74 69 6f 6e 20  each invocation 
367e0 6f 66 20 74 68 65 20 78 53 74 65 70 20 63 61 6c  of the xStep cal
367f0 6c 62 61 63 6b 20 61 6e 64 20 74 68 65 6e 20 6f  lback and then o
36800 6e 65 0a 2a 2a 20 6c 61 73 74 20 74 69 6d 65 20  ne.** last time 
36810 77 68 65 6e 20 74 68 65 20 78 46 69 6e 61 6c 20  when the xFinal 
36820 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
36830 6b 65 64 2e 20 20 5e 28 57 68 65 6e 20 6e 6f 20  ked.  ^(When no 
36840 72 6f 77 73 20 6d 61 74 63 68 0a 2a 2a 20 61 6e  rows match.** an
36850 20 61 67 67 72 65 67 61 74 65 20 71 75 65 72 79   aggregate query
36860 2c 20 74 68 65 20 78 53 74 65 70 28 29 20 63 61  , the xStep() ca
36870 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 61 67  llback of the ag
36880 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e  gregate function
36890 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
368a0 6f 6e 20 69 73 20 6e 65 76 65 72 20 63 61 6c 6c  on is never call
368b0 65 64 20 61 6e 64 20 78 46 69 6e 61 6c 28 29 20  ed and xFinal() 
368c0 69 73 20 63 61 6c 6c 65 64 20 65 78 61 63 74 6c  is called exactl
368d0 79 20 6f 6e 63 65 2e 0a 2a 2a 20 49 6e 20 74 68  y once..** In th
368e0 6f 73 65 20 63 61 73 65 73 2c 20 73 71 6c 69 74  ose cases, sqlit
368f0 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
36900 74 65 78 74 28 29 20 6d 69 67 68 74 20 62 65 20  text() might be 
36910 63 61 6c 6c 65 64 20 66 6f 72 20 74 68 65 0a 2a  called for the.*
36920 2a 20 66 69 72 73 74 20 74 69 6d 65 20 66 72 6f  * first time fro
36930 6d 20 77 69 74 68 69 6e 20 78 46 69 6e 61 6c 28  m within xFinal(
36940 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ).)^.**.** ^The 
36950 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
36960 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72  e_context(C,N) r
36970 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61  outine returns a
36980 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 0a 2a   NULL pointer .*
36990 2a 20 77 68 65 6e 20 66 69 72 73 74 20 63 61 6c  * when first cal
369a0 6c 65 64 20 69 66 20 4e 20 69 73 20 6c 65 73 73  led if N is less
369b0 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74   than or equal t
369c0 6f 20 7a 65 72 6f 20 6f 72 20 69 66 20 61 20 6d  o zero or if a m
369d0 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74  emory.** allocat
369e0 65 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 0a  e error occurs..
369f0 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 61 6d 6f 75  **.** ^(The amou
36a00 6e 74 20 6f 66 20 73 70 61 63 65 20 61 6c 6c 6f  nt of space allo
36a10 63 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33  cated by sqlite3
36a20 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
36a30 78 74 28 43 2c 4e 29 20 69 73 0a 2a 2a 20 64 65  xt(C,N) is.** de
36a40 74 65 72 6d 69 6e 65 64 20 62 79 20 74 68 65 20  termined by the 
36a50 4e 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 66  N parameter on f
36a60 69 72 73 74 20 73 75 63 63 65 73 73 66 75 6c 20  irst successful 
36a70 63 61 6c 6c 2e 20 20 43 68 61 6e 67 69 6e 67 20  call.  Changing 
36a80 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20  the.** value of 
36a90 4e 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20  N in subsequent 
36aa0 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
36ab0 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
36ac0 74 28 29 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68  t() within.** th
36ad0 65 20 73 61 6d 65 20 61 67 67 72 65 67 61 74 65  e same aggregate
36ae0 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e   function instan
36af0 63 65 20 77 69 6c 6c 20 6e 6f 74 20 72 65 73 69  ce will not resi
36b00 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a  ze the memory.**
36b10 20 61 6c 6c 6f 63 61 74 69 6f 6e 2e 29 5e 20 20   allocation.)^  
36b20 57 69 74 68 69 6e 20 74 68 65 20 78 46 69 6e 61  Within the xFina
36b30 6c 20 63 61 6c 6c 62 61 63 6b 2c 20 69 74 20 69  l callback, it i
36b40 73 20 63 75 73 74 6f 6d 61 72 79 20 74 6f 20 73  s customary to s
36b50 65 74 0a 2a 2a 20 4e 3d 30 20 69 6e 20 63 61 6c  et.** N=0 in cal
36b60 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 61 67  ls to sqlite3_ag
36b70 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
36b80 43 2c 4e 29 20 73 6f 20 74 68 61 74 20 6e 6f 20  C,N) so that no 
36b90 0a 2a 2a 20 70 6f 69 6e 74 6c 65 73 73 20 6d 65  .** pointless me
36ba0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  mory allocations
36bb0 20 6f 63 63 75 72 2e 0a 2a 2a 0a 2a 2a 20 5e 53   occur..**.** ^S
36bc0 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 63 61  QLite automatica
36bd0 6c 6c 79 20 66 72 65 65 73 20 74 68 65 20 6d 65  lly frees the me
36be0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65 64 20 62  mory allocated b
36bf0 79 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67  y .** sqlite3_ag
36c00 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
36c10 29 20 77 68 65 6e 20 74 68 65 20 61 67 67 72 65  ) when the aggre
36c20 67 61 74 65 20 71 75 65 72 79 20 63 6f 6e 63 6c  gate query concl
36c30 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  udes..**.** The 
36c40 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
36c50 6d 75 73 74 20 62 65 20 61 20 63 6f 70 79 20 6f  must be a copy o
36c60 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  f the.** [sqlite
36c70 33 5f 63 6f 6e 74 65 78 74 20 7c 20 53 51 4c 20  3_context | SQL 
36c80 66 75 6e 63 74 69 6f 6e 20 63 6f 6e 74 65 78 74  function context
36c90 5d 20 74 68 61 74 20 69 73 20 74 68 65 20 66 69  ] that is the fi
36ca0 72 73 74 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  rst parameter.**
36cb0 20 74 6f 20 74 68 65 20 78 53 74 65 70 20 6f 72   to the xStep or
36cc0 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b   xFinal callback
36cd0 20 72 6f 75 74 69 6e 65 20 74 68 61 74 20 69 6d   routine that im
36ce0 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 61 67 67  plements the agg
36cf0 72 65 67 61 74 65 0a 2a 2a 20 66 75 6e 63 74 69  regate.** functi
36d00 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  on..**.** This r
36d10 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63  outine must be c
36d20 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73  alled from the s
36d30 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68  ame thread in wh
36d40 69 63 68 0a 2a 2a 20 74 68 65 20 61 67 67 72 65  ich.** the aggre
36d50 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f  gate SQL functio
36d60 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f  n is running..*/
36d70 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
36d80 20 2a 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67   *sqlite3_aggreg
36d90 61 74 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c 69  ate_context(sqli
36da0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
36db0 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a  t nBytes);../*.*
36dc0 2a 20 43 41 50 49 33 52 45 46 3a 20 55 73 65 72  * CAPI3REF: User
36dd0 20 44 61 74 61 20 46 6f 72 20 46 75 6e 63 74 69   Data For Functi
36de0 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ons.**.** ^The s
36df0 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61  qlite3_user_data
36e00 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  () interface ret
36e10 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a  urns a copy of.*
36e20 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 68  * the pointer th
36e30 61 74 20 77 61 73 20 74 68 65 20 70 55 73 65 72  at was the pUser
36e40 44 61 74 61 20 70 61 72 61 6d 65 74 65 72 20 28  Data parameter (
36e50 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65  the 5th paramete
36e60 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71  r).** of the [sq
36e70 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
36e80 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20  ction()].** and 
36e90 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
36ea0 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f  function16()] ro
36eb0 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67  utines that orig
36ec0 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74  inally.** regist
36ed0 65 72 65 64 20 74 68 65 20 61 70 70 6c 69 63 61  ered the applica
36ee0 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e  tion defined fun
36ef0 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  ction..**.** Thi
36f00 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62  s routine must b
36f10 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  e called from th
36f20 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e  e same thread in
36f30 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 70   which.** the ap
36f40 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
36f50 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  d function is ru
36f60 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45  nning..*/.SQLITE
36f70 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74  _API void *sqlit
36f80 65 33 5f 75 73 65 72 5f 64 61 74 61 28 73 71 6c  e3_user_data(sql
36f90 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a  ite3_context*);.
36fa0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
36fb0 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63   Database Connec
36fc0 74 69 6f 6e 20 46 6f 72 20 46 75 6e 63 74 69 6f  tion For Functio
36fd0 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ns.**.** ^The sq
36fe0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62  lite3_context_db
36ff0 5f 68 61 6e 64 6c 65 28 29 20 69 6e 74 65 72 66  _handle() interf
37000 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f  ace returns a co
37010 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69  py of.** the poi
37020 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 64 61 74  nter to the [dat
37030 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
37040 5d 20 28 74 68 65 20 31 73 74 20 70 61 72 61 6d  ] (the 1st param
37050 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20  eter).** of the 
37060 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
37070 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61  function()].** a
37080 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  nd [sqlite3_crea
37090 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d  te_function16()]
370a0 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f   routines that o
370b0 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67  riginally.** reg
370c0 69 73 74 65 72 65 64 20 74 68 65 20 61 70 70 6c  istered the appl
370d0 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20  ication defined 
370e0 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c  function..*/.SQL
370f0 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 20  ITE_API sqlite3 
37100 2a 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  *sqlite3_context
37110 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74  _db_handle(sqlit
37120 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f  e3_context*);../
37130 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
37140 75 6e 63 74 69 6f 6e 20 41 75 78 69 6c 69 61 72  unction Auxiliar
37150 79 20 44 61 74 61 0a 2a 2a 0a 2a 2a 20 54 68 65  y Data.**.** The
37160 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79  se functions may
37170 20 62 65 20 75 73 65 64 20 62 79 20 28 6e 6f 6e   be used by (non
37180 2d 61 67 67 72 65 67 61 74 65 29 20 53 51 4c 20  -aggregate) SQL 
37190 66 75 6e 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20  functions to.** 
371a0 61 73 73 6f 63 69 61 74 65 20 6d 65 74 61 64 61  associate metada
371b0 74 61 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74  ta with argument
371c0 20 76 61 6c 75 65 73 2e 20 49 66 20 74 68 65 20   values. If the 
371d0 73 61 6d 65 20 76 61 6c 75 65 20 69 73 20 70 61  same value is pa
371e0 73 73 65 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69  ssed to.** multi
371f0 70 6c 65 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20  ple invocations 
37200 6f 66 20 74 68 65 20 73 61 6d 65 20 53 51 4c 20  of the same SQL 
37210 66 75 6e 63 74 69 6f 6e 20 64 75 72 69 6e 67 20  function during 
37220 71 75 65 72 79 20 65 78 65 63 75 74 69 6f 6e 2c  query execution,
37230 20 75 6e 64 65 72 0a 2a 2a 20 73 6f 6d 65 20 63   under.** some c
37240 69 72 63 75 6d 73 74 61 6e 63 65 73 20 74 68 65  ircumstances the
37250 20 61 73 73 6f 63 69 61 74 65 64 20 6d 65 74 61   associated meta
37260 64 61 74 61 20 6d 61 79 20 62 65 20 70 72 65 73  data may be pres
37270 65 72 76 65 64 2e 20 20 41 6e 20 65 78 61 6d 70  erved.  An examp
37280 6c 65 0a 2a 2a 20 6f 66 20 77 68 65 72 65 20 74  le.** of where t
37290 68 69 73 20 6d 69 67 68 74 20 62 65 20 75 73 65  his might be use
372a0 66 75 6c 20 69 73 20 69 6e 20 61 20 72 65 67 75  ful is in a regu
372b0 6c 61 72 2d 65 78 70 72 65 73 73 69 6f 6e 20 6d  lar-expression m
372c0 61 74 63 68 69 6e 67 0a 2a 2a 20 66 75 6e 63 74  atching.** funct
372d0 69 6f 6e 2e 20 54 68 65 20 63 6f 6d 70 69 6c 65  ion. The compile
372e0 64 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65  d version of the
372f0 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73   regular express
37300 69 6f 6e 20 63 61 6e 20 62 65 20 73 74 6f 72 65  ion can be store
37310 64 20 61 73 0a 2a 2a 20 6d 65 74 61 64 61 74 61  d as.** metadata
37320 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
37330 20 74 68 65 20 70 61 74 74 65 72 6e 20 73 74 72   the pattern str
37340 69 6e 67 2e 20 20 0a 2a 2a 20 54 68 65 6e 20 61  ing.  .** Then a
37350 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 70 61  s long as the pa
37360 74 74 65 72 6e 20 73 74 72 69 6e 67 20 72 65 6d  ttern string rem
37370 61 69 6e 73 20 74 68 65 20 73 61 6d 65 2c 0a 2a  ains the same,.*
37380 2a 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 20 72  * the compiled r
37390 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f  egular expressio
373a0 6e 20 63 61 6e 20 62 65 20 72 65 75 73 65 64 20  n can be reused 
373b0 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 69  on multiple.** i
373c0 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68  nvocations of th
373d0 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 2e  e same function.
373e0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
373f0 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28  te3_get_auxdata(
37400 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
37410 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
37420 20 74 68 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a   the metadata.**
37430 20 61 73 73 6f 63 69 61 74 65 64 20 62 79 20 74   associated by t
37440 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  he sqlite3_set_a
37450 75 78 64 61 74 61 28 29 20 66 75 6e 63 74 69 6f  uxdata() functio
37460 6e 20 77 69 74 68 20 74 68 65 20 4e 74 68 20 61  n with the Nth a
37470 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 61 6c 75 65  rgument.** value
37480 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74   to the applicat
37490 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
374a0 74 69 6f 6e 2e 20 5e 49 66 20 74 68 65 72 65 20  tion. ^If there 
374b0 69 73 20 6e 6f 20 6d 65 74 61 64 61 74 61 0a 2a  is no metadata.*
374c0 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  * associated wit
374d0 68 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 61  h the function a
374e0 72 67 75 6d 65 6e 74 2c 20 74 68 69 73 20 73 71  rgument, this sq
374f0 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74  lite3_get_auxdat
37500 61 28 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  a() interface.**
37510 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20   returns a NULL 
37520 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  pointer..**.** ^
37530 54 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  The sqlite3_set_
37540 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29  auxdata(C,N,P,X)
37550 20 69 6e 74 65 72 66 61 63 65 20 73 61 76 65 73   interface saves
37560 20 50 20 61 73 20 6d 65 74 61 64 61 74 61 20 66   P as metadata f
37570 6f 72 20 74 68 65 20 4e 2d 74 68 0a 2a 2a 20 61  or the N-th.** a
37580 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 61  rgument of the a
37590 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
375a0 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 20 5e 53  ed function.  ^S
375b0 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c  ubsequent.** cal
375c0 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 67 65  ls to sqlite3_ge
375d0 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 29 20 72  t_auxdata(C,N) r
375e0 65 74 75 72 6e 20 50 20 66 72 6f 6d 20 74 68 65  eturn P from the
375f0 20 6d 6f 73 74 20 72 65 63 65 6e 74 0a 2a 2a 20   most recent.** 
37600 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
37610 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20 63 61 6c  ata(C,N,P,X) cal
37620 6c 20 69 66 20 74 68 65 20 6d 65 74 61 64 61 74  l if the metadat
37630 61 20 69 73 20 73 74 69 6c 6c 20 76 61 6c 69 64  a is still valid
37640 20 6f 72 0a 2a 2a 20 4e 55 4c 4c 20 69 66 20 74   or.** NULL if t
37650 68 65 20 6d 65 74 61 64 61 74 61 20 68 61 73 20  he metadata has 
37660 62 65 65 6e 20 64 69 73 63 61 72 64 65 64 2e 0a  been discarded..
37670 2a 2a 20 5e 41 66 74 65 72 20 65 61 63 68 20 63  ** ^After each c
37680 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
37690 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50  et_auxdata(C,N,P
376a0 2c 58 29 20 77 68 65 72 65 20 58 20 69 73 20 6e  ,X) where X is n
376b0 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 53 51 4c 69  ot NULL,.** SQLi
376c0 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74  te will invoke t
376d0 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 66 75  he destructor fu
376e0 6e 63 74 69 6f 6e 20 58 20 77 69 74 68 20 70 61  nction X with pa
376f0 72 61 6d 65 74 65 72 20 50 20 65 78 61 63 74 6c  rameter P exactl
37700 79 0a 2a 2a 20 6f 6e 63 65 2c 20 77 68 65 6e 20  y.** once, when 
37710 74 68 65 20 6d 65 74 61 64 61 74 61 20 69 73 20  the metadata is 
37720 64 69 73 63 61 72 64 65 64 2e 0a 2a 2a 20 53 51  discarded..** SQ
37730 4c 69 74 65 20 69 73 20 66 72 65 65 20 74 6f 20  Lite is free to 
37740 64 69 73 63 61 72 64 20 74 68 65 20 6d 65 74 61  discard the meta
37750 64 61 74 61 20 61 74 20 61 6e 79 20 74 69 6d 65  data at any time
37760 2c 20 69 6e 63 6c 75 64 69 6e 67 3a 20 3c 75 6c  , including: <ul
37770 3e 0a 2a 2a 20 3c 6c 69 3e 20 77 68 65 6e 20 74  >.** <li> when t
37780 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
37790 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65   function parame
377a0 74 65 72 20 63 68 61 6e 67 65 73 2c 20 6f 72 0a  ter changes, or.
377b0 2a 2a 20 3c 6c 69 3e 20 77 68 65 6e 20 5b 73 71  ** <li> when [sq
377c0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
377d0 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  r [sqlite3_final
377e0 69 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64  ize()] is called
377f0 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20   for the.**     
37800 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
37810 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 77 68 65 6e 20  or.** <li> when 
37820 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
37830 61 74 61 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ata() is invoked
37840 20 61 67 61 69 6e 20 6f 6e 20 74 68 65 20 73 61   again on the sa
37850 6d 65 20 70 61 72 61 6d 65 74 65 72 2c 20 6f 72  me parameter, or
37860 0a 2a 2a 20 3c 6c 69 3e 20 64 75 72 69 6e 67 20  .** <li> during 
37870 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 71 6c  the original sql
37880 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
37890 28 29 20 63 61 6c 6c 20 77 68 65 6e 20 61 20 6d  () call when a m
378a0 65 6d 6f 72 79 20 0a 2a 2a 20 20 20 20 20 20 61  emory .**      a
378b0 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20  llocation error 
378c0 6f 63 63 75 72 73 2e 20 3c 2f 75 6c 3e 29 5e 0a  occurs. </ul>)^.
378d0 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 65 20 6c  **.** Note the l
378e0 61 73 74 20 62 75 6c 6c 65 74 20 69 6e 20 70 61  ast bullet in pa
378f0 72 74 69 63 75 6c 61 72 2e 20 20 54 68 65 20 64  rticular.  The d
37900 65 73 74 72 75 63 74 6f 72 20 58 20 69 6e 20 0a  estructor X in .
37910 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  ** sqlite3_set_a
37920 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20  uxdata(C,N,P,X) 
37930 6d 69 67 68 74 20 62 65 20 63 61 6c 6c 65 64 20  might be called 
37940 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65 66  immediately, bef
37950 6f 72 65 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74  ore the.** sqlit
37960 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29  e3_set_auxdata()
37970 20 69 6e 74 65 72 66 61 63 65 20 65 76 65 6e 20   interface even 
37980 72 65 74 75 72 6e 73 2e 20 20 48 65 6e 63 65 20  returns.  Hence 
37990 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
379a0 61 74 61 28 29 0a 2a 2a 20 73 68 6f 75 6c 64 20  ata().** should 
379b0 62 65 20 63 61 6c 6c 65 64 20 6e 65 61 72 20 74  be called near t
379c0 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 66 75  he end of the fu
379d0 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74  nction implement
379e0 61 74 69 6f 6e 20 61 6e 64 20 74 68 65 0a 2a 2a  ation and the.**
379f0 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
37a00 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  entation should 
37a10 6e 6f 74 20 6d 61 6b 65 20 61 6e 79 20 75 73 65  not make any use
37a20 20 6f 66 20 50 20 61 66 74 65 72 0a 2a 2a 20 73   of P after.** s
37a30 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
37a40 74 61 28 29 20 68 61 73 20 62 65 65 6e 20 63 61  ta() has been ca
37a50 6c 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e  lled..**.** ^(In
37a60 20 70 72 61 63 74 69 63 65 2c 20 6d 65 74 61 64   practice, metad
37a70 61 74 61 20 69 73 20 70 72 65 73 65 72 76 65 64  ata is preserved
37a80 20 62 65 74 77 65 65 6e 20 66 75 6e 63 74 69 6f   between functio
37a90 6e 20 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20 66  n calls for.** f
37aa0 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65  unction paramete
37ab0 72 73 20 74 68 61 74 20 61 72 65 20 63 6f 6d 70  rs that are comp
37ac0 69 6c 65 2d 74 69 6d 65 20 63 6f 6e 73 74 61 6e  ile-time constan
37ad0 74 73 2c 20 69 6e 63 6c 75 64 69 6e 67 20 6c 69  ts, including li
37ae0 74 65 72 61 6c 0a 2a 2a 20 76 61 6c 75 65 73 20  teral.** values 
37af0 61 6e 64 20 5b 70 61 72 61 6d 65 74 65 72 73 5d  and [parameters]
37b00 20 61 6e 64 20 65 78 70 72 65 73 73 69 6f 6e 73   and expressions
37b10 20 63 6f 6d 70 6f 73 65 64 20 66 72 6f 6d 20 74   composed from t
37b20 68 65 20 73 61 6d 65 2e 29 5e 0a 2a 2a 0a 2a 2a  he same.)^.**.**
37b30 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
37b40 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66  must be called f
37b50 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72  rom the same thr
37b60 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20  ead in which.** 
37b70 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
37b80 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a   is running..*/.
37b90 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
37ba0 2a 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78  *sqlite3_get_aux
37bb0 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e  data(sqlite3_con
37bc0 74 65 78 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 53  text*, int N);.S
37bd0 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73  QLITE_API void s
37be0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
37bf0 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ta(sqlite3_conte
37c00 78 74 2a 2c 20 69 6e 74 20 4e 2c 20 76 6f 69 64  xt*, int N, void
37c10 2a 2c 20 76 6f 69 64 20 28 2a 29 28 76 6f 69 64  *, void (*)(void
37c20 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  *));.../*.** CAP
37c30 49 33 52 45 46 3a 20 43 6f 6e 73 74 61 6e 74 73  I3REF: Constants
37c40 20 44 65 66 69 6e 69 6e 67 20 53 70 65 63 69 61   Defining Specia
37c50 6c 20 44 65 73 74 72 75 63 74 6f 72 20 42 65 68  l Destructor Beh
37c60 61 76 69 6f 72 0a 2a 2a 0a 2a 2a 20 54 68 65 73  avior.**.** Thes
37c70 65 20 61 72 65 20 73 70 65 63 69 61 6c 20 76 61  e are special va
37c80 6c 75 65 73 20 66 6f 72 20 74 68 65 20 64 65 73  lues for the des
37c90 74 72 75 63 74 6f 72 20 74 68 61 74 20 69 73 20  tructor that is 
37ca0 70 61 73 73 65 64 20 69 6e 20 61 73 20 74 68 65  passed in as the
37cb0 0a 2a 2a 20 66 69 6e 61 6c 20 61 72 67 75 6d 65  .** final argume
37cc0 6e 74 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c  nt to routines l
37cd0 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ike [sqlite3_res
37ce0 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20 20 5e 49  ult_blob()].  ^I
37cf0 66 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  f the destructor
37d00 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20  .** argument is 
37d10 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 69  SQLITE_STATIC, i
37d20 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  t means that the
37d30 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 65 72   content pointer
37d40 20 69 73 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20   is constant.** 
37d50 61 6e 64 20 77 69 6c 6c 20 6e 65 76 65 72 20 63  and will never c
37d60 68 61 6e 67 65 2e 20 20 49 74 20 64 6f 65 73 20  hange.  It does 
37d70 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 64  not need to be d
37d80 65 73 74 72 6f 79 65 64 2e 20 20 5e 54 68 65 0a  estroyed.  ^The.
37d90 2a 2a 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49  ** SQLITE_TRANSI
37da0 45 4e 54 20 76 61 6c 75 65 20 6d 65 61 6e 73 20  ENT value means 
37db0 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74  that the content
37dc0 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 63 68 61   will likely cha
37dd0 6e 67 65 20 69 6e 0a 2a 2a 20 74 68 65 20 6e 65  nge in.** the ne
37de0 61 72 20 66 75 74 75 72 65 20 61 6e 64 20 74 68  ar future and th
37df0 61 74 20 53 51 4c 69 74 65 20 73 68 6f 75 6c 64  at SQLite should
37e00 20 6d 61 6b 65 20 69 74 73 20 6f 77 6e 20 70 72   make its own pr
37e10 69 76 61 74 65 20 63 6f 70 79 20 6f 66 0a 2a 2a  ivate copy of.**
37e20 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 62 65 66   the content bef
37e30 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a  ore returning..*
37e40 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 64 65 66  *.** The typedef
37e50 20 69 73 20 6e 65 63 65 73 73 61 72 79 20 74 6f   is necessary to
37e60 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20 70 72 6f   work around pro
37e70 62 6c 65 6d 73 20 69 6e 20 63 65 72 74 61 69 6e  blems in certain
37e80 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c 65 72  .** C++ compiler
37e90 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 76 6f  s..*/.typedef vo
37ea0 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 64 65 73  id (*sqlite3_des
37eb0 74 72 75 63 74 6f 72 5f 74 79 70 65 29 28 76 6f  tructor_type)(vo
37ec0 69 64 2a 29 3b 0a 23 64 65 66 69 6e 65 20 53 51  id*);.#define SQ
37ed0 4c 49 54 45 5f 53 54 41 54 49 43 20 20 20 20 20  LITE_STATIC     
37ee0 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72   ((sqlite3_destr
37ef0 75 63 74 6f 72 5f 74 79 70 65 29 30 29 0a 23 64  uctor_type)0).#d
37f00 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41  efine SQLITE_TRA
37f10 4e 53 49 45 4e 54 20 20 20 28 28 73 71 6c 69 74  NSIENT   ((sqlit
37f20 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79  e3_destructor_ty
37f30 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41  pe)-1)../*.** CA
37f40 50 49 33 52 45 46 3a 20 53 65 74 74 69 6e 67 20  PI3REF: Setting 
37f50 54 68 65 20 52 65 73 75 6c 74 20 4f 66 20 41 6e  The Result Of An
37f60 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 0a 2a 2a   SQL Function.**
37f70 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
37f80 65 73 20 61 72 65 20 75 73 65 64 20 62 79 20 74  es are used by t
37f90 68 65 20 78 46 75 6e 63 20 6f 72 20 78 46 69 6e  he xFunc or xFin
37fa0 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61  al callbacks tha
37fb0 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 20 53  t.** implement S
37fc0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64  QL functions and
37fd0 20 61 67 67 72 65 67 61 74 65 73 2e 20 20 53 65   aggregates.  Se
37fe0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72  e.** [sqlite3_cr
37ff0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
38000 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72   and [sqlite3_cr
38010 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
38020 29 5d 0a 2a 2a 20 66 6f 72 20 61 64 64 69 74 69  )].** for additi
38030 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
38040 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75  ..**.** These fu
38050 6e 63 74 69 6f 6e 73 20 77 6f 72 6b 20 76 65 72  nctions work ver
38060 79 20 6d 75 63 68 20 6c 69 6b 65 20 74 68 65 20  y much like the 
38070 5b 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69  [parameter bindi
38080 6e 67 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a  ng] family of.**
38090 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 64 20   functions used 
380a0 74 6f 20 62 69 6e 64 20 76 61 6c 75 65 73 20 74  to bind values t
380b0 6f 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72  o host parameter
380c0 73 20 69 6e 20 70 72 65 70 61 72 65 64 20 73 74  s in prepared st
380d0 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 52 65 66  atements..** Ref
380e0 65 72 20 74 6f 20 74 68 65 20 5b 53 51 4c 20 70  er to the [SQL p
380f0 61 72 61 6d 65 74 65 72 5d 20 64 6f 63 75 6d 65  arameter] docume
38100 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69  ntation for addi
38110 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69  tional informati
38120 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  on..**.** ^The s
38130 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
38140 6f 62 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  ob() interface s
38150 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 66  ets the result f
38160 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63  rom.** an applic
38170 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
38180 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65  nction to be the
38190 20 42 4c 4f 42 20 77 68 6f 73 65 20 63 6f 6e 74   BLOB whose cont
381a0 65 6e 74 20 69 73 20 70 6f 69 6e 74 65 64 0a 2a  ent is pointed.*
381b0 2a 20 74 6f 20 62 79 20 74 68 65 20 73 65 63 6f  * to by the seco
381c0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64  nd parameter and
381d0 20 77 68 69 63 68 20 69 73 20 4e 20 62 79 74 65   which is N byte
381e0 73 20 6c 6f 6e 67 20 77 68 65 72 65 20 4e 20 69  s long where N i
381f0 73 20 74 68 65 0a 2a 2a 20 74 68 69 72 64 20 70  s the.** third p
38200 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
38210 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
38220 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 69  ult_zeroblob() i
38230 6e 74 65 72 66 61 63 65 73 20 73 65 74 20 74 68  nterfaces set th
38240 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74  e result of.** t
38250 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
38260 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
38270 74 6f 20 62 65 20 61 20 42 4c 4f 42 20 63 6f 6e  to be a BLOB con
38280 74 61 69 6e 69 6e 67 20 61 6c 6c 20 7a 65 72 6f  taining all zero
38290 0a 2a 2a 20 62 79 74 65 73 20 61 6e 64 20 4e 20  .** bytes and N 
382a0 62 79 74 65 73 20 69 6e 20 73 69 7a 65 2c 20 77  bytes in size, w
382b0 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 76 61  here N is the va
382c0 6c 75 65 20 6f 66 20 74 68 65 20 32 6e 64 20 70  lue of the 2nd p
382d0 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
382e0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
382f0 75 6c 74 5f 64 6f 75 62 6c 65 28 29 20 69 6e 74  ult_double() int
38300 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20  erface sets the 
38310 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61  result from.** a
38320 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  n application-de
38330 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
38340 6f 20 62 65 20 61 20 66 6c 6f 61 74 69 6e 67 20  o be a floating 
38350 70 6f 69 6e 74 20 76 61 6c 75 65 20 73 70 65 63  point value spec
38360 69 66 69 65 64 0a 2a 2a 20 62 79 20 69 74 73 20  ified.** by its 
38370 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  2nd argument..**
38380 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
38390 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20  _result_error() 
383a0 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  and sqlite3_resu
383b0 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 66 75 6e  lt_error16() fun
383c0 63 74 69 6f 6e 73 0a 2a 2a 20 63 61 75 73 65 20  ctions.** cause 
383d0 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20  the implemented 
383e0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  SQL function to 
383f0 74 68 72 6f 77 20 61 6e 20 65 78 63 65 70 74 69  throw an excepti
38400 6f 6e 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75  on..** ^SQLite u
38410 73 65 73 20 74 68 65 20 73 74 72 69 6e 67 20 70  ses the string p
38420 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65  ointed to by the
38430 0a 2a 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65  .** 2nd paramete
38440 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 72 65 73  r of sqlite3_res
38450 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 20 73  ult_error() or s
38460 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
38470 72 6f 72 31 36 28 29 0a 2a 2a 20 61 73 20 74 68  ror16().** as th
38480 65 20 74 65 78 74 20 6f 66 20 61 6e 20 65 72 72  e text of an err
38490 6f 72 20 6d 65 73 73 61 67 65 2e 20 20 5e 53 51  or message.  ^SQ
384a0 4c 69 74 65 20 69 6e 74 65 72 70 72 65 74 73 20  Lite interprets 
384b0 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73  the error.** mes
384c0 73 61 67 65 20 73 74 72 69 6e 67 20 66 72 6f 6d  sage string from
384d0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
384e0 65 72 72 6f 72 28 29 20 61 73 20 55 54 46 2d 38  error() as UTF-8
384f0 2e 20 5e 53 51 4c 69 74 65 0a 2a 2a 20 69 6e 74  . ^SQLite.** int
38500 65 72 70 72 65 74 73 20 74 68 65 20 73 74 72 69  erprets the stri
38510 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ng from sqlite3_
38520 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
38530 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6e 61   as UTF-16 in na
38540 74 69 76 65 0a 2a 2a 20 62 79 74 65 20 6f 72 64  tive.** byte ord
38550 65 72 2e 20 20 5e 49 66 20 74 68 65 20 74 68 69  er.  ^If the thi
38560 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
38570 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
38580 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c  rror().** or sql
38590 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
385a0 72 31 36 28 29 20 69 73 20 6e 65 67 61 74 69 76  r16() is negativ
385b0 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61  e then SQLite ta
385c0 6b 65 73 20 61 73 20 74 68 65 20 65 72 72 6f 72  kes as the error
385d0 0a 2a 2a 20 6d 65 73 73 61 67 65 20 61 6c 6c 20  .** message all 
385e0 74 65 78 74 20 75 70 20 74 68 72 6f 75 67 68 20  text up through 
385f0 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63  the first zero c
38600 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 66  haracter..** ^If
38610 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
38620 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
38630 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f  result_error() o
38640 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73  r.** sqlite3_res
38650 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69 73  ult_error16() is
38660 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 74 68   non-negative th
38670 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20  en SQLite takes 
38680 74 68 61 74 20 6d 61 6e 79 0a 2a 2a 20 62 79 74  that many.** byt
38690 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65  es (not characte
386a0 72 73 29 20 66 72 6f 6d 20 74 68 65 20 32 6e 64  rs) from the 2nd
386b0 20 70 61 72 61 6d 65 74 65 72 20 61 73 20 74 68   parameter as th
386c0 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e  e error message.
386d0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
386e0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20  _result_error() 
386f0 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  and sqlite3_resu
38700 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20  lt_error16().** 
38710 72 6f 75 74 69 6e 65 73 20 6d 61 6b 65 20 61 20  routines make a 
38720 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20  private copy of 
38730 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
38740 65 20 74 65 78 74 20 62 65 66 6f 72 65 0a 2a 2a  e text before.**
38750 20 74 68 65 79 20 72 65 74 75 72 6e 2e 20 20 48   they return.  H
38760 65 6e 63 65 2c 20 74 68 65 20 63 61 6c 6c 69 6e  ence, the callin
38770 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 64  g function can d
38780 65 61 6c 6c 6f 63 61 74 65 20 6f 72 0a 2a 2a 20  eallocate or.** 
38790 6d 6f 64 69 66 79 20 74 68 65 20 74 65 7