System.Data.SQLite
Hex Artifact Content
Not logged in

Artifact b04c70267a12450b6a6ba1bd3a1a3ca827d663aa:


0000: 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  /***************
0010: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0020: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0030: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0040: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a  ***************.
0050: 2a 2a 20 54 68 69 73 20 66 69 6c 65 20 69 73 20  ** This file is 
0060: 61 6e 20 61 6d 61 6c 67 61 6d 61 74 69 6f 6e 20  an amalgamation 
0070: 6f 66 20 6d 61 6e 79 20 73 65 70 61 72 61 74 65  of many separate
0080: 20 43 20 73 6f 75 72 63 65 20 66 69 6c 65 73 20   C source files 
0090: 66 72 6f 6d 20 53 51 4c 69 74 65 0a 2a 2a 20 76  from SQLite.** v
00a0: 65 72 73 69 6f 6e 20 33 2e 37 2e 37 2e 20 20 42  ersion 3.7.7.  B
00b0: 79 20 63 6f 6d 62 69 6e 69 6e 67 20 61 6c 6c 20  y combining all 
00c0: 74 68 65 20 69 6e 64 69 76 69 64 75 61 6c 20 43  the individual C
00d0: 20 63 6f 64 65 20 66 69 6c 65 73 20 69 6e 74 6f   code files into
00e0: 20 74 68 69 73 20 0a 2a 2a 20 73 69 6e 67 6c 65   this .** single
00f0: 20 6c 61 72 67 65 20 66 69 6c 65 2c 20 74 68 65   large file, the
0100: 20 65 6e 74 69 72 65 20 63 6f 64 65 20 63 61 6e   entire code can
0110: 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 61 73 20   be compiled as 
0120: 61 20 73 69 6e 67 6c 65 20 74 72 61 6e 73 6c 61  a single transla
0130: 74 69 6f 6e 0a 2a 2a 20 75 6e 69 74 2e 20 20 54  tion.** unit.  T
0140: 68 69 73 20 61 6c 6c 6f 77 73 20 6d 61 6e 79 20  his allows many 
0150: 63 6f 6d 70 69 6c 65 72 73 20 74 6f 20 64 6f 20  compilers to do 
0160: 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 73 20 74 68  optimizations th
0170: 61 74 20 77 6f 75 6c 64 20 6e 6f 74 20 62 65 0a  at would not be.
0180: 2a 2a 20 70 6f 73 73 69 62 6c 65 20 69 66 20 74  ** possible if t
0190: 68 65 20 66 69 6c 65 73 20 77 65 72 65 20 63 6f  he files were co
01a0: 6d 70 69 6c 65 64 20 73 65 70 61 72 61 74 65 6c  mpiled separatel
01b0: 79 2e 20 20 50 65 72 66 6f 72 6d 61 6e 63 65 20  y.  Performance 
01c0: 69 6d 70 72 6f 76 65 6d 65 6e 74 73 0a 2a 2a 20  improvements.** 
01d0: 6f 66 20 35 25 20 6f 72 20 6d 6f 72 65 20 61 72  of 5% or more ar
01e0: 65 20 63 6f 6d 6d 6f 6e 6c 79 20 73 65 65 6e 20  e commonly seen 
01f0: 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63  when SQLite is c
0200: 6f 6d 70 69 6c 65 64 20 61 73 20 61 20 73 69 6e  ompiled as a sin
0210: 67 6c 65 0a 2a 2a 20 74 72 61 6e 73 6c 61 74 69  gle.** translati
0220: 6f 6e 20 75 6e 69 74 2e 0a 2a 2a 0a 2a 2a 20 54  on unit..**.** T
0230: 68 69 73 20 66 69 6c 65 20 69 73 20 61 6c 6c 20  his file is all 
0240: 79 6f 75 20 6e 65 65 64 20 74 6f 20 63 6f 6d 70  you need to comp
0250: 69 6c 65 20 53 51 4c 69 74 65 2e 20 20 54 6f 20  ile SQLite.  To 
0260: 75 73 65 20 53 51 4c 69 74 65 20 69 6e 20 6f 74  use SQLite in ot
0270: 68 65 72 0a 2a 2a 20 70 72 6f 67 72 61 6d 73 2c  her.** programs,
0280: 20 79 6f 75 20 6e 65 65 64 20 74 68 69 73 20 66   you need this f
0290: 69 6c 65 20 61 6e 64 20 74 68 65 20 22 73 71 6c  ile and the "sql
02a0: 69 74 65 33 2e 68 22 20 68 65 61 64 65 72 20 66  ite3.h" header f
02b0: 69 6c 65 20 74 68 61 74 20 64 65 66 69 6e 65 73  ile that defines
02c0: 0a 2a 2a 20 74 68 65 20 70 72 6f 67 72 61 6d 6d  .** the programm
02d0: 69 6e 67 20 69 6e 74 65 72 66 61 63 65 20 74 6f  ing interface to
02e0: 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72   the SQLite libr
02f0: 61 72 79 2e 20 20 28 49 66 20 79 6f 75 20 64 6f  ary.  (If you do
0300: 20 6e 6f 74 20 68 61 76 65 20 0a 2a 2a 20 74 68   not have .** th
0310: 65 20 22 73 71 6c 69 74 65 33 2e 68 22 20 68 65  e "sqlite3.h" he
0320: 61 64 65 72 20 66 69 6c 65 20 61 74 20 68 61 6e  ader file at han
0330: 64 2c 20 79 6f 75 20 77 69 6c 6c 20 66 69 6e 64  d, you will find
0340: 20 61 20 63 6f 70 79 20 65 6d 62 65 64 64 65 64   a copy embedded
0350: 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20 74   within.** the t
0360: 65 78 74 20 6f 66 20 74 68 69 73 20 66 69 6c 65  ext of this file
0370: 2e 20 20 53 65 61 72 63 68 20 66 6f 72 20 22 42  .  Search for "B
0380: 65 67 69 6e 20 66 69 6c 65 20 73 71 6c 69 74 65  egin file sqlite
0390: 33 2e 68 22 20 74 6f 20 66 69 6e 64 20 74 68 65  3.h" to find the
03a0: 20 73 74 61 72 74 0a 2a 2a 20 6f 66 20 74 68 65   start.** of the
03b0: 20 65 6d 62 65 64 64 65 64 20 73 71 6c 69 74 65   embedded sqlite
03c0: 33 2e 68 20 68 65 61 64 65 72 20 66 69 6c 65 2e  3.h header file.
03d0: 29 20 41 64 64 69 74 69 6f 6e 61 6c 20 63 6f 64  ) Additional cod
03e0: 65 20 66 69 6c 65 73 20 6d 61 79 20 62 65 20 6e  e files may be n
03f0: 65 65 64 65 64 0a 2a 2a 20 69 66 20 79 6f 75 20  eeded.** if you 
0400: 77 61 6e 74 20 61 20 77 72 61 70 70 65 72 20 74  want a wrapper t
0410: 6f 20 69 6e 74 65 72 66 61 63 65 20 53 51 4c 69  o interface SQLi
0420: 74 65 20 77 69 74 68 20 79 6f 75 72 20 63 68 6f  te with your cho
0430: 69 63 65 20 6f 66 20 70 72 6f 67 72 61 6d 6d 69  ice of programmi
0440: 6e 67 0a 2a 2a 20 6c 61 6e 67 75 61 67 65 2e 20  ng.** language. 
0450: 54 68 65 20 63 6f 64 65 20 66 6f 72 20 74 68 65  The code for the
0460: 20 22 73 71 6c 69 74 65 33 22 20 63 6f 6d 6d 61   "sqlite3" comma
0470: 6e 64 2d 6c 69 6e 65 20 73 68 65 6c 6c 20 69 73  nd-line shell is
0480: 20 61 6c 73 6f 20 69 6e 20 61 0a 2a 2a 20 73 65   also in a.** se
0490: 70 61 72 61 74 65 20 66 69 6c 65 2e 20 54 68 69  parate file. Thi
04a0: 73 20 66 69 6c 65 20 63 6f 6e 74 61 69 6e 73 20  s file contains 
04b0: 6f 6e 6c 79 20 63 6f 64 65 20 66 6f 72 20 74 68  only code for th
04c0: 65 20 63 6f 72 65 20 53 51 4c 69 74 65 20 6c 69  e core SQLite li
04d0: 62 72 61 72 79 2e 0a 2a 2f 0a 23 64 65 66 69 6e  brary..*/.#defin
04e0: 65 20 53 51 4c 49 54 45 5f 43 4f 52 45 20 31 0a  e SQLITE_CORE 1.
04f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
0500: 4d 41 4c 47 41 4d 41 54 49 4f 4e 20 31 0a 23 69  MALGAMATION 1.#i
0510: 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 50 52 49  fndef SQLITE_PRI
0520: 56 41 54 45 0a 23 20 64 65 66 69 6e 65 20 53 51  VATE.# define SQ
0530: 4c 49 54 45 5f 50 52 49 56 41 54 45 20 73 74 61  LITE_PRIVATE sta
0540: 74 69 63 0a 23 65 6e 64 69 66 0a 23 69 66 6e 64  tic.#endif.#ifnd
0550: 65 66 20 53 51 4c 49 54 45 5f 41 50 49 0a 23 20  ef SQLITE_API.# 
0560: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 50  define SQLITE_AP
0570: 49 0a 23 65 6e 64 69 66 0a 2f 2a 2a 2a 2a 2a 2a  I.#endif./******
0580: 2a 2a 2a 2a 2a 2a 2a 2a 20 42 65 67 69 6e 20 66  ******** Begin f
0590: 69 6c 65 20 73 71 6c 69 74 65 49 6e 74 2e 68 20  ile sqliteInt.h 
05a0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
05b0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
05c0: 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a 0a 2a 2a 20 32  *******/./*.** 2
05d0: 30 30 31 20 53 65 70 74 65 6d 62 65 72 20 31 35  001 September 15
05e0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f  .**.** The autho
05f0: 72 20 64 69 73 63 6c 61 69 6d 73 20 63 6f 70 79  r disclaims copy
0600: 72 69 67 68 74 20 74 6f 20 74 68 69 73 20 73 6f  right to this so
0610: 75 72 63 65 20 63 6f 64 65 2e 20 20 49 6e 20 70  urce code.  In p
0620: 6c 61 63 65 20 6f 66 0a 2a 2a 20 61 20 6c 65 67  lace of.** a leg
0630: 61 6c 20 6e 6f 74 69 63 65 2c 20 68 65 72 65 20  al notice, here 
0640: 69 73 20 61 20 62 6c 65 73 73 69 6e 67 3a 0a 2a  is a blessing:.*
0650: 2a 0a 2a 2a 20 20 20 20 4d 61 79 20 79 6f 75 20  *.**    May you 
0660: 64 6f 20 67 6f 6f 64 20 61 6e 64 20 6e 6f 74 20  do good and not 
0670: 65 76 69 6c 2e 0a 2a 2a 20 20 20 20 4d 61 79 20  evil..**    May 
0680: 79 6f 75 20 66 69 6e 64 20 66 6f 72 67 69 76 65  you find forgive
0690: 6e 65 73 73 20 66 6f 72 20 79 6f 75 72 73 65 6c  ness for yoursel
06a0: 66 20 61 6e 64 20 66 6f 72 67 69 76 65 20 6f 74  f and forgive ot
06b0: 68 65 72 73 2e 0a 2a 2a 20 20 20 20 4d 61 79 20  hers..**    May 
06c0: 79 6f 75 20 73 68 61 72 65 20 66 72 65 65 6c 79  you share freely
06d0: 2c 20 6e 65 76 65 72 20 74 61 6b 69 6e 67 20 6d  , never taking m
06e0: 6f 72 65 20 74 68 61 6e 20 79 6f 75 20 67 69 76  ore than you giv
06f0: 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  e..**.**********
0700: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0710: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0720: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0730: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a  ***************.
0740: 2a 2a 20 49 6e 74 65 72 6e 61 6c 20 69 6e 74 65  ** Internal inte
0750: 72 66 61 63 65 20 64 65 66 69 6e 69 74 69 6f 6e  rface definition
0760: 73 20 66 6f 72 20 53 51 4c 69 74 65 2e 0a 2a 2a  s for SQLite..**
0770: 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53 51 4c  .*/.#ifndef _SQL
0780: 49 54 45 49 4e 54 5f 48 5f 0a 23 64 65 66 69 6e  ITEINT_H_.#defin
0790: 65 20 5f 53 51 4c 49 54 45 49 4e 54 5f 48 5f 0a  e _SQLITEINT_H_.
07a0: 0a 2f 2a 0a 2a 2a 20 54 68 65 73 65 20 23 64 65  ./*.** These #de
07b0: 66 69 6e 65 73 20 73 68 6f 75 6c 64 20 65 6e 61  fines should ena
07c0: 62 6c 65 20 3e 32 47 42 20 66 69 6c 65 20 73 75  ble >2GB file su
07d0: 70 70 6f 72 74 20 6f 6e 20 50 4f 53 49 58 20 69  pport on POSIX i
07e0: 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79  f the.** underly
07f0: 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79  ing operating sy
0800: 73 74 65 6d 20 73 75 70 70 6f 72 74 73 20 69 74  stem supports it
0810: 2e 20 20 49 66 20 74 68 65 20 4f 53 20 6c 61 63  .  If the OS lac
0820: 6b 73 0a 2a 2a 20 6c 61 72 67 65 20 66 69 6c 65  ks.** large file
0830: 20 73 75 70 70 6f 72 74 2c 20 6f 72 20 69 66 20   support, or if 
0840: 74 68 65 20 4f 53 20 69 73 20 77 69 6e 64 6f 77  the OS is window
0850: 73 2c 20 74 68 65 73 65 20 73 68 6f 75 6c 64 20  s, these should 
0860: 62 65 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 0a 2a 2a  be no-ops..**.**
0870: 20 54 69 63 6b 65 74 20 23 32 37 33 39 3a 20 20   Ticket #2739:  
0880: 54 68 65 20 5f 4c 41 52 47 45 46 49 4c 45 5f 53  The _LARGEFILE_S
0890: 4f 55 52 43 45 20 6d 61 63 72 6f 20 6d 75 73 74  OURCE macro must
08a0: 20 61 70 70 65 61 72 20 62 65 66 6f 72 65 20 61   appear before a
08b0: 6e 79 0a 2a 2a 20 73 79 73 74 65 6d 20 23 69 6e  ny.** system #in
08c0: 63 6c 75 64 65 73 2e 20 20 48 65 6e 63 65 2c 20  cludes.  Hence, 
08d0: 74 68 69 73 20 62 6c 6f 63 6b 20 6f 66 20 63 6f  this block of co
08e0: 64 65 20 6d 75 73 74 20 62 65 20 74 68 65 20 76  de must be the v
08f0: 65 72 79 20 66 69 72 73 74 0a 2a 2a 20 63 6f 64  ery first.** cod
0900: 65 20 69 6e 20 61 6c 6c 20 73 6f 75 72 63 65 20  e in all source 
0910: 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 4c 61 72  files..**.** Lar
0920: 67 65 20 66 69 6c 65 20 73 75 70 70 6f 72 74 20  ge file support 
0930: 63 61 6e 20 62 65 20 64 69 73 61 62 6c 65 64 20  can be disabled 
0940: 75 73 69 6e 67 20 74 68 65 20 2d 44 53 51 4c 49  using the -DSQLI
0950: 54 45 5f 44 49 53 41 42 4c 45 5f 4c 46 53 20 73  TE_DISABLE_LFS s
0960: 77 69 74 63 68 0a 2a 2a 20 6f 6e 20 74 68 65 20  witch.** on the 
0970: 63 6f 6d 70 69 6c 65 72 20 63 6f 6d 6d 61 6e 64  compiler command
0980: 20 6c 69 6e 65 2e 20 20 54 68 69 73 20 69 73 20   line.  This is 
0990: 6e 65 63 65 73 73 61 72 79 20 69 66 20 79 6f 75  necessary if you
09a0: 20 61 72 65 20 63 6f 6d 70 69 6c 69 6e 67 0a 2a   are compiling.*
09b0: 2a 20 6f 6e 20 61 20 72 65 63 65 6e 74 20 6d 61  * on a recent ma
09c0: 63 68 69 6e 65 20 28 65 78 3a 20 52 65 64 20 48  chine (ex: Red H
09d0: 61 74 20 37 2e 32 29 20 62 75 74 20 79 6f 75 20  at 7.2) but you 
09e0: 77 61 6e 74 20 79 6f 75 72 20 63 6f 64 65 20 74  want your code t
09f0: 6f 20 77 6f 72 6b 0a 2a 2a 20 6f 6e 20 61 6e 20  o work.** on an 
0a00: 6f 6c 64 65 72 20 6d 61 63 68 69 6e 65 20 28 65  older machine (e
0a10: 78 3a 20 52 65 64 20 48 61 74 20 36 2e 30 29 2e  x: Red Hat 6.0).
0a20: 20 20 49 66 20 79 6f 75 20 63 6f 6d 70 69 6c 65    If you compile
0a30: 20 6f 6e 20 52 65 64 20 48 61 74 20 37 2e 32 0a   on Red Hat 7.2.
0a40: 2a 2a 20 77 69 74 68 6f 75 74 20 74 68 69 73 20  ** without this 
0a50: 6f 70 74 69 6f 6e 2c 20 4c 46 53 20 69 73 20 65  option, LFS is e
0a60: 6e 61 62 6c 65 2e 20 20 42 75 74 20 4c 46 53 20  nable.  But LFS 
0a70: 64 6f 65 73 20 6e 6f 74 20 65 78 69 73 74 20 69  does not exist i
0a80: 6e 20 74 68 65 20 6b 65 72 6e 65 6c 0a 2a 2a 20  n the kernel.** 
0a90: 69 6e 20 52 65 64 20 48 61 74 20 36 2e 30 2c 20  in Red Hat 6.0, 
0aa0: 73 6f 20 74 68 65 20 63 6f 64 65 20 77 6f 6e 27  so the code won'
0ab0: 74 20 77 6f 72 6b 2e 20 20 48 65 6e 63 65 2c 20  t work.  Hence, 
0ac0: 66 6f 72 20 6d 61 78 69 6d 75 6d 20 62 69 6e 61  for maximum bina
0ad0: 72 79 0a 2a 2a 20 70 6f 72 74 61 62 69 6c 69 74  ry.** portabilit
0ae0: 79 20 79 6f 75 20 73 68 6f 75 6c 64 20 6f 6d 69  y you should omi
0af0: 74 20 4c 46 53 2e 0a 2a 2a 0a 2a 2a 20 53 69 6d  t LFS..**.** Sim
0b00: 69 6c 61 72 20 69 73 20 74 72 75 65 20 66 6f 72  ilar is true for
0b10: 20 4d 61 63 20 4f 53 20 58 2e 20 20 4c 46 53 20   Mac OS X.  LFS 
0b20: 69 73 20 6f 6e 6c 79 20 73 75 70 70 6f 72 74 65  is only supporte
0b30: 64 20 6f 6e 20 4d 61 63 20 4f 53 20 58 20 39 20  d on Mac OS X 9 
0b40: 61 6e 64 20 6c 61 74 65 72 2e 0a 2a 2f 0a 23 69  and later..*/.#i
0b50: 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 44 49 53  fndef SQLITE_DIS
0b60: 41 42 4c 45 5f 4c 46 53 0a 23 20 64 65 66 69 6e  ABLE_LFS.# defin
0b70: 65 20 5f 4c 41 52 47 45 5f 46 49 4c 45 20 20 20  e _LARGE_FILE   
0b80: 20 20 20 20 31 0a 23 20 69 66 6e 64 65 66 20 5f      1.# ifndef _
0b90: 46 49 4c 45 5f 4f 46 46 53 45 54 5f 42 49 54 53  FILE_OFFSET_BITS
0ba0: 0a 23 20 20 20 64 65 66 69 6e 65 20 5f 46 49 4c  .#   define _FIL
0bb0: 45 5f 4f 46 46 53 45 54 5f 42 49 54 53 20 36 34  E_OFFSET_BITS 64
0bc0: 0a 23 20 65 6e 64 69 66 0a 23 20 64 65 66 69 6e  .# endif.# defin
0bd0: 65 20 5f 4c 41 52 47 45 46 49 4c 45 5f 53 4f 55  e _LARGEFILE_SOU
0be0: 52 43 45 20 31 0a 23 65 6e 64 69 66 0a 0a 2f 2a  RCE 1.#endif../*
0bf0: 0a 2a 2a 20 49 6e 63 6c 75 64 65 20 74 68 65 20  .** Include the 
0c00: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 68 65  configuration he
0c10: 61 64 65 72 20 6f 75 74 70 75 74 20 62 79 20 27  ader output by '
0c20: 63 6f 6e 66 69 67 75 72 65 27 20 69 66 20 77 65  configure' if we
0c30: 27 72 65 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a  're using the.**
0c40: 20 61 75 74 6f 63 6f 6e 66 2d 62 61 73 65 64 20   autoconf-based 
0c50: 62 75 69 6c 64 0a 2a 2f 0a 23 69 66 64 65 66 20  build.*/.#ifdef 
0c60: 5f 48 41 56 45 5f 53 51 4c 49 54 45 5f 43 4f 4e  _HAVE_SQLITE_CON
0c70: 46 49 47 5f 48 0a 23 69 6e 63 6c 75 64 65 20 22  FIG_H.#include "
0c80: 63 6f 6e 66 69 67 2e 68 22 0a 23 65 6e 64 69 66  config.h".#endif
0c90: 0a 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ../*************
0ca0: 2a 20 49 6e 63 6c 75 64 65 20 73 71 6c 69 74 65  * Include sqlite
0cb0: 4c 69 6d 69 74 2e 68 20 69 6e 20 74 68 65 20 6d  Limit.h in the m
0cc0: 69 64 64 6c 65 20 6f 66 20 73 71 6c 69 74 65 49  iddle of sqliteI
0cd0: 6e 74 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  nt.h ***********
0ce0: 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  /./*************
0cf0: 2a 20 42 65 67 69 6e 20 66 69 6c 65 20 73 71 6c  * Begin file sql
0d00: 69 74 65 4c 69 6d 69 74 2e 68 20 2a 2a 2a 2a 2a  iteLimit.h *****
0d10: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0d20: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0d30: 2f 0a 2f 2a 0a 2a 2a 20 32 30 30 37 20 4d 61 79  /./*.** 2007 May
0d40: 20 37 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74   7.**.** The aut
0d50: 68 6f 72 20 64 69 73 63 6c 61 69 6d 73 20 63 6f  hor disclaims co
0d60: 70 79 72 69 67 68 74 20 74 6f 20 74 68 69 73 20  pyright to this 
0d70: 73 6f 75 72 63 65 20 63 6f 64 65 2e 20 20 49 6e  source code.  In
0d80: 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 61 20 6c   place of.** a l
0d90: 65 67 61 6c 20 6e 6f 74 69 63 65 2c 20 68 65 72  egal notice, her
0da0: 65 20 69 73 20 61 20 62 6c 65 73 73 69 6e 67 3a  e is a blessing:
0db0: 0a 2a 2a 0a 2a 2a 20 20 20 20 4d 61 79 20 79 6f  .**.**    May yo
0dc0: 75 20 64 6f 20 67 6f 6f 64 20 61 6e 64 20 6e 6f  u do good and no
0dd0: 74 20 65 76 69 6c 2e 0a 2a 2a 20 20 20 20 4d 61  t evil..**    Ma
0de0: 79 20 79 6f 75 20 66 69 6e 64 20 66 6f 72 67 69  y you find forgi
0df0: 76 65 6e 65 73 73 20 66 6f 72 20 79 6f 75 72 73  veness for yours
0e00: 65 6c 66 20 61 6e 64 20 66 6f 72 67 69 76 65 20  elf and forgive 
0e10: 6f 74 68 65 72 73 2e 0a 2a 2a 20 20 20 20 4d 61  others..**    Ma
0e20: 79 20 79 6f 75 20 73 68 61 72 65 20 66 72 65 65  y you share free
0e30: 6c 79 2c 20 6e 65 76 65 72 20 74 61 6b 69 6e 67  ly, never taking
0e40: 20 6d 6f 72 65 20 74 68 61 6e 20 79 6f 75 20 67   more than you g
0e50: 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 2a 2a  ive..**.********
0e60: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0e70: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0e80: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0e90: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0ea0: 2a 0a 2a 2a 20 0a 2a 2a 20 54 68 69 73 20 66 69  *.** .** This fi
0eb0: 6c 65 20 64 65 66 69 6e 65 73 20 76 61 72 69 6f  le defines vario
0ec0: 75 73 20 6c 69 6d 69 74 73 20 6f 66 20 77 68 61  us limits of wha
0ed0: 74 20 53 51 4c 69 74 65 20 63 61 6e 20 70 72 6f  t SQLite can pro
0ee0: 63 65 73 73 2e 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  cess..*/../*.** 
0ef0: 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67  The maximum leng
0f00: 74 68 20 6f 66 20 61 20 54 45 58 54 20 6f 72 20  th of a TEXT or 
0f10: 42 4c 4f 42 20 69 6e 20 62 79 74 65 73 2e 20 20  BLOB in bytes.  
0f20: 20 54 68 69 73 20 61 6c 73 6f 0a 2a 2a 20 6c 69   This also.** li
0f30: 6d 69 74 73 20 74 68 65 20 73 69 7a 65 20 6f 66  mits the size of
0f40: 20 61 20 72 6f 77 20 69 6e 20 61 20 74 61 62 6c   a row in a tabl
0f50: 65 20 6f 72 20 69 6e 64 65 78 2e 0a 2a 2a 0a 2a  e or index..**.*
0f60: 2a 20 54 68 65 20 68 61 72 64 20 6c 69 6d 69 74  * The hard limit
0f70: 20 69 73 20 74 68 65 20 61 62 69 6c 69 74 79 20   is the ability 
0f80: 6f 66 20 61 20 33 32 2d 62 69 74 20 73 69 67 6e  of a 32-bit sign
0f90: 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 74 6f  ed integer.** to
0fa0: 20 63 6f 75 6e 74 20 74 68 65 20 73 69 7a 65 3a   count the size:
0fb0: 20 32 5e 33 31 2d 31 20 6f 72 20 32 31 34 37 34   2^31-1 or 21474
0fc0: 38 33 36 34 37 2e 0a 2a 2f 0a 23 69 66 6e 64 65  83647..*/.#ifnde
0fd0: 66 20 53 51 4c 49 54 45 5f 4d 41 58 5f 4c 45 4e  f SQLITE_MAX_LEN
0fe0: 47 54 48 0a 23 20 64 65 66 69 6e 65 20 53 51 4c  GTH.# define SQL
0ff0: 49 54 45 5f 4d 41 58 5f 4c 45 4e 47 54 48 20 31  ITE_MAX_LENGTH 1
1000: 30 30 30 30 30 30 30 30 30 0a 23 65 6e 64 69 66  000000000.#endif
1010: 0a 0a 2f 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20  ../*.** This is 
1020: 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  the maximum numb
1030: 65 72 20 6f 66 0a 2a 2a 0a 2a 2a 20 20 20 20 2a  er of.**.**    *
1040: 20 43 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74 61   Columns in a ta
1050: 62 6c 65 0a 2a 2a 20 20 20 20 2a 20 43 6f 6c 75  ble.**    * Colu
1060: 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65 78 0a  mns in an index.
1070: 2a 2a 20 20 20 20 2a 20 43 6f 6c 75 6d 6e 73 20  **    * Columns 
1080: 69 6e 20 61 20 76 69 65 77 0a 2a 2a 20 20 20 20  in a view.**    
1090: 2a 20 54 65 72 6d 73 20 69 6e 20 74 68 65 20 53  * Terms in the S
10a0: 45 54 20 63 6c 61 75 73 65 20 6f 66 20 61 6e 20  ET clause of an 
10b0: 55 50 44 41 54 45 20 73 74 61 74 65 6d 65 6e 74  UPDATE statement
10c0: 0a 2a 2a 20 20 20 20 2a 20 54 65 72 6d 73 20 69  .**    * Terms i
10d0: 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  n the result set
10e0: 20 6f 66 20 61 20 53 45 4c 45 43 54 20 73 74 61   of a SELECT sta
10f0: 74 65 6d 65 6e 74 0a 2a 2a 20 20 20 20 2a 20 54  tement.**    * T
1100: 65 72 6d 73 20 69 6e 20 74 68 65 20 47 52 4f 55  erms in the GROU
1110: 50 20 42 59 20 6f 72 20 4f 52 44 45 52 20 42 59  P BY or ORDER BY
1120: 20 63 6c 61 75 73 65 73 20 6f 66 20 61 20 53 45   clauses of a SE
1130: 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 0a  LECT statement..
1140: 2a 2a 20 20 20 20 2a 20 54 65 72 6d 73 20 69 6e  **    * Terms in
1150: 20 74 68 65 20 56 41 4c 55 45 53 20 63 6c 61 75   the VALUES clau
1160: 73 65 20 6f 66 20 61 6e 20 49 4e 53 45 52 54 20  se of an INSERT 
1170: 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20  statement.**.** 
1180: 54 68 65 20 68 61 72 64 20 75 70 70 65 72 20 6c  The hard upper l
1190: 69 6d 69 74 20 68 65 72 65 20 69 73 20 33 32 36  imit here is 326
11a0: 37 36 2e 20 20 4d 6f 73 74 20 64 61 74 61 62 61  76.  Most databa
11b0: 73 65 20 70 65 6f 70 6c 65 20 77 69 6c 6c 0a 2a  se people will.*
11c0: 2a 20 74 65 6c 6c 20 79 6f 75 20 74 68 61 74 20  * tell you that 
11d0: 69 6e 20 61 20 77 65 6c 6c 2d 6e 6f 72 6d 61 6c  in a well-normal
11e0: 69 7a 65 64 20 64 61 74 61 62 61 73 65 2c 20 79  ized database, y
11f0: 6f 75 20 75 73 75 61 6c 6c 79 20 73 68 6f 75 6c  ou usually shoul
1200: 64 0a 2a 2a 20 6e 6f 74 20 68 61 76 65 20 6d 6f  d.** not have mo
1210: 72 65 20 74 68 61 6e 20 61 20 64 6f 7a 65 6e 20  re than a dozen 
1220: 6f 72 20 73 6f 20 63 6f 6c 75 6d 6e 73 20 69 6e  or so columns in
1230: 20 61 6e 79 20 74 61 62 6c 65 2e 20 20 41 6e 64   any table.  And
1240: 20 69 66 0a 2a 2a 20 74 68 61 74 20 69 73 20 74   if.** that is t
1250: 68 65 20 63 61 73 65 2c 20 74 68 65 72 65 20 69  he case, there i
1260: 73 20 6e 6f 20 70 6f 69 6e 74 20 69 6e 20 68 61  s no point in ha
1270: 76 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20 61  ving more than a
1280: 20 66 65 77 0a 2a 2a 20 64 6f 7a 65 6e 20 76 61   few.** dozen va
1290: 6c 75 65 73 20 69 6e 20 61 6e 79 20 6f 66 20 74  lues in any of t
12a0: 68 65 20 6f 74 68 65 72 20 73 69 74 75 61 74 69  he other situati
12b0: 6f 6e 73 20 64 65 73 63 72 69 62 65 64 20 61 62  ons described ab
12c0: 6f 76 65 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20  ove..*/.#ifndef 
12d0: 53 51 4c 49 54 45 5f 4d 41 58 5f 43 4f 4c 55 4d  SQLITE_MAX_COLUM
12e0: 4e 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54  N.# define SQLIT
12f0: 45 5f 4d 41 58 5f 43 4f 4c 55 4d 4e 20 32 30 30  E_MAX_COLUMN 200
1300: 30 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20  0.#endif../*.** 
1310: 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67  The maximum leng
1320: 74 68 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 53  th of a single S
1330: 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20  QL statement in 
1340: 62 79 74 65 73 2e 0a 2a 2a 0a 2a 2a 20 49 74 20  bytes..**.** It 
1350: 75 73 65 64 20 74 6f 20 62 65 20 74 68 65 20 63  used to be the c
1360: 61 73 65 20 74 68 61 74 20 73 65 74 74 69 6e 67  ase that setting
1370: 20 74 68 69 73 20 76 61 6c 75 65 20 74 6f 20 7a   this value to z
1380: 65 72 6f 20 77 6f 75 6c 64 0a 2a 2a 20 74 75 72  ero would.** tur
1390: 6e 20 74 68 65 20 6c 69 6d 69 74 20 6f 66 66 2e  n the limit off.
13a0: 20 20 54 68 61 74 20 69 73 20 6e 6f 20 6c 6f 6e    That is no lon
13b0: 67 65 72 20 74 72 75 65 2e 20 20 49 74 20 69 73  ger true.  It is
13c0: 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 0a 2a 2a   not possible.**
13d0: 20 74 6f 20 74 75 72 6e 20 74 68 69 73 20 6c 69   to turn this li
13e0: 6d 69 74 20 6f 66 66 2e 0a 2a 2f 0a 23 69 66 6e  mit off..*/.#ifn
13f0: 64 65 66 20 53 51 4c 49 54 45 5f 4d 41 58 5f 53  def SQLITE_MAX_S
1400: 51 4c 5f 4c 45 4e 47 54 48 0a 23 20 64 65 66 69  QL_LENGTH.# defi
1410: 6e 65 20 53 51 4c 49 54 45 5f 4d 41 58 5f 53 51  ne SQLITE_MAX_SQ
1420: 4c 5f 4c 45 4e 47 54 48 20 31 30 30 30 30 30 30  L_LENGTH 1000000
1430: 30 30 30 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a  000.#endif../*.*
1440: 2a 20 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65  * The maximum de
1450: 70 74 68 20 6f 66 20 61 6e 20 65 78 70 72 65 73  pth of an expres
1460: 73 69 6f 6e 20 74 72 65 65 2e 20 54 68 69 73 20  sion tree. This 
1470: 69 73 20 6c 69 6d 69 74 65 64 20 74 6f 20 0a 2a  is limited to .*
1480: 2a 20 73 6f 6d 65 20 65 78 74 65 6e 74 20 62 79  * some extent by
1490: 20 53 51 4c 49 54 45 5f 4d 41 58 5f 53 51 4c 5f   SQLITE_MAX_SQL_
14a0: 4c 45 4e 47 54 48 2e 20 42 75 74 20 73 6f 6d 65  LENGTH. But some
14b0: 74 69 6d 65 20 79 6f 75 20 6d 69 67 68 74 20 0a  time you might .
14c0: 2a 2a 20 77 61 6e 74 20 74 6f 20 70 6c 61 63 65  ** want to place
14d0: 20 6d 6f 72 65 20 73 65 76 65 72 65 20 6c 69 6d   more severe lim
14e0: 69 74 73 20 6f 6e 20 74 68 65 20 63 6f 6d 70 6c  its on the compl
14f0: 65 78 69 74 79 20 6f 66 20 61 6e 20 0a 2a 2a 20  exity of an .** 
1500: 65 78 70 72 65 73 73 69 6f 6e 2e 0a 2a 2a 0a 2a  expression..**.*
1510: 2a 20 41 20 76 61 6c 75 65 20 6f 66 20 30 20 75  * A value of 0 u
1520: 73 65 64 20 74 6f 20 6d 65 61 6e 20 74 68 61 74  sed to mean that
1530: 20 74 68 65 20 6c 69 6d 69 74 20 77 61 73 20 6e   the limit was n
1540: 6f 74 20 65 6e 66 6f 72 63 65 64 2e 0a 2a 2a 20  ot enforced..** 
1550: 42 75 74 20 74 68 61 74 20 69 73 20 6e 6f 20 6c  But that is no l
1560: 6f 6e 67 65 72 20 74 72 75 65 2e 20 20 54 68 65  onger true.  The
1570: 20 6c 69 6d 69 74 20 69 73 20 6e 6f 77 20 73 74   limit is now st
1580: 72 69 63 74 6c 79 20 65 6e 66 6f 72 63 65 64 0a  rictly enforced.
1590: 2a 2a 20 61 74 20 61 6c 6c 20 74 69 6d 65 73 2e  ** at all times.
15a0: 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  .*/.#ifndef SQLI
15b0: 54 45 5f 4d 41 58 5f 45 58 50 52 5f 44 45 50 54  TE_MAX_EXPR_DEPT
15c0: 48 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54  H.# define SQLIT
15d0: 45 5f 4d 41 58 5f 45 58 50 52 5f 44 45 50 54 48  E_MAX_EXPR_DEPTH
15e0: 20 31 30 30 30 0a 23 65 6e 64 69 66 0a 0a 2f 2a   1000.#endif../*
15f0: 0a 2a 2a 20 54 68 65 20 6d 61 78 69 6d 75 6d 20  .** The maximum 
1600: 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20  number of terms 
1610: 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45  in a compound SE
1620: 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 0a  LECT statement..
1630: 2a 2a 20 54 68 65 20 63 6f 64 65 20 67 65 6e 65  ** The code gene
1640: 72 61 74 6f 72 20 66 6f 72 20 63 6f 6d 70 6f 75  rator for compou
1650: 6e 64 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d  nd SELECT statem
1660: 65 6e 74 73 20 64 6f 65 73 20 6f 6e 65 0a 2a 2a  ents does one.**
1670: 20 6c 65 76 65 6c 20 6f 66 20 72 65 63 75 72 73   level of recurs
1680: 69 6f 6e 20 66 6f 72 20 65 61 63 68 20 74 65 72  ion for each ter
1690: 6d 2e 20 20 41 20 73 74 61 63 6b 20 6f 76 65 72  m.  A stack over
16a0: 66 6c 6f 77 20 63 61 6e 20 72 65 73 75 6c 74 0a  flow can result.
16b0: 2a 2a 20 69 66 20 74 68 65 20 6e 75 6d 62 65 72  ** if the number
16c0: 20 6f 66 20 74 65 72 6d 73 20 69 73 20 74 6f 6f   of terms is too
16d0: 20 6c 61 72 67 65 2e 20 20 49 6e 20 70 72 61 63   large.  In prac
16e0: 74 69 63 65 2c 20 6d 6f 73 74 20 53 51 4c 0a 2a  tice, most SQL.*
16f0: 2a 20 6e 65 76 65 72 20 68 61 73 20 6d 6f 72 65  * never has more
1700: 20 74 68 61 6e 20 33 20 6f 72 20 34 20 74 65 72   than 3 or 4 ter
1710: 6d 73 2e 20 20 55 73 65 20 61 20 76 61 6c 75 65  ms.  Use a value
1720: 20 6f 66 20 30 20 74 6f 20 64 69 73 61 62 6c 65   of 0 to disable
1730: 0a 2a 2a 20 61 6e 79 20 6c 69 6d 69 74 20 6f 6e  .** any limit on
1740: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74   the number of t
1750: 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75  erms in a compou
1760: 6e 74 20 53 45 4c 45 43 54 2e 0a 2a 2f 0a 23 69  nt SELECT..*/.#i
1770: 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4d 41 58  fndef SQLITE_MAX
1780: 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54  _COMPOUND_SELECT
1790: 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45  .# define SQLITE
17a0: 5f 4d 41 58 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45  _MAX_COMPOUND_SE
17b0: 4c 45 43 54 20 35 30 30 0a 23 65 6e 64 69 66 0a  LECT 500.#endif.
17c0: 0a 2f 2a 0a 2a 2a 20 54 68 65 20 6d 61 78 69 6d  ./*.** The maxim
17d0: 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 6f 70 63  um number of opc
17e0: 6f 64 65 73 20 69 6e 20 61 20 56 44 42 45 20 70  odes in a VDBE p
17f0: 72 6f 67 72 61 6d 2e 0a 2a 2a 20 4e 6f 74 20 63  rogram..** Not c
1800: 75 72 72 65 6e 74 6c 79 20 65 6e 66 6f 72 63 65  urrently enforce
1810: 64 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51  d..*/.#ifndef SQ
1820: 4c 49 54 45 5f 4d 41 58 5f 56 44 42 45 5f 4f 50  LITE_MAX_VDBE_OP
1830: 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45  .# define SQLITE
1840: 5f 4d 41 58 5f 56 44 42 45 5f 4f 50 20 32 35 30  _MAX_VDBE_OP 250
1850: 30 30 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a  00.#endif../*.**
1860: 20 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d   The maximum num
1870: 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73  ber of arguments
1880: 20 74 6f 20 61 6e 20 53 51 4c 20 66 75 6e 63 74   to an SQL funct
1890: 69 6f 6e 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20  ion..*/.#ifndef 
18a0: 53 51 4c 49 54 45 5f 4d 41 58 5f 46 55 4e 43 54  SQLITE_MAX_FUNCT
18b0: 49 4f 4e 5f 41 52 47 0a 23 20 64 65 66 69 6e 65  ION_ARG.# define
18c0: 20 53 51 4c 49 54 45 5f 4d 41 58 5f 46 55 4e 43   SQLITE_MAX_FUNC
18d0: 54 49 4f 4e 5f 41 52 47 20 31 32 37 0a 23 65 6e  TION_ARG 127.#en
18e0: 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 6d  dif../*.** The m
18f0: 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
1900: 20 69 6e 2d 6d 65 6d 6f 72 79 20 70 61 67 65 73   in-memory pages
1910: 20 74 6f 20 75 73 65 20 66 6f 72 20 74 68 65 20   to use for the 
1920: 6d 61 69 6e 20 64 61 74 61 62 61 73 65 0a 2a 2a  main database.**
1930: 20 74 61 62 6c 65 20 61 6e 64 20 66 6f 72 20 74   table and for t
1940: 65 6d 70 6f 72 61 72 79 20 74 61 62 6c 65 73 2e  emporary tables.
1950: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 44 45 46    The SQLITE_DEF
1960: 41 55 4c 54 5f 43 41 43 48 45 5f 53 49 5a 45 0a  AULT_CACHE_SIZE.
1970: 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54  */.#ifndef SQLIT
1980: 45 5f 44 45 46 41 55 4c 54 5f 43 41 43 48 45 5f  E_DEFAULT_CACHE_
1990: 53 49 5a 45 0a 23 20 64 65 66 69 6e 65 20 53 51  SIZE.# define SQ
19a0: 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 43 41 43  LITE_DEFAULT_CAC
19b0: 48 45 5f 53 49 5a 45 20 20 32 30 30 30 0a 23 65  HE_SIZE  2000.#e
19c0: 6e 64 69 66 0a 23 69 66 6e 64 65 66 20 53 51 4c  ndif.#ifndef SQL
19d0: 49 54 45 5f 44 45 46 41 55 4c 54 5f 54 45 4d 50  ITE_DEFAULT_TEMP
19e0: 5f 43 41 43 48 45 5f 53 49 5a 45 0a 23 20 64 65  _CACHE_SIZE.# de
19f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 46 41  fine SQLITE_DEFA
1a00: 55 4c 54 5f 54 45 4d 50 5f 43 41 43 48 45 5f 53  ULT_TEMP_CACHE_S
1a10: 49 5a 45 20 20 35 30 30 0a 23 65 6e 64 69 66 0a  IZE  500.#endif.
1a20: 0a 2f 2a 0a 2a 2a 20 54 68 65 20 64 65 66 61 75  ./*.** The defau
1a30: 6c 74 20 6e 75 6d 62 65 72 20 6f 66 20 66 72 61  lt number of fra
1a40: 6d 65 73 20 74 6f 20 61 63 63 75 6d 75 6c 61 74  mes to accumulat
1a50: 65 20 69 6e 20 74 68 65 20 6c 6f 67 20 66 69 6c  e in the log fil
1a60: 65 20 62 65 66 6f 72 65 0a 2a 2a 20 63 68 65 63  e before.** chec
1a70: 6b 70 6f 69 6e 74 69 6e 67 20 74 68 65 20 64 61  kpointing the da
1a80: 74 61 62 61 73 65 20 69 6e 20 57 41 4c 20 6d 6f  tabase in WAL mo
1a90: 64 65 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53  de..*/.#ifndef S
1aa0: 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 57 41  QLITE_DEFAULT_WA
1ab0: 4c 5f 41 55 54 4f 43 48 45 43 4b 50 4f 49 4e 54  L_AUTOCHECKPOINT
1ac0: 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45  .# define SQLITE
1ad0: 5f 44 45 46 41 55 4c 54 5f 57 41 4c 5f 41 55 54  _DEFAULT_WAL_AUT
1ae0: 4f 43 48 45 43 4b 50 4f 49 4e 54 20 20 31 30 30  OCHECKPOINT  100
1af0: 30 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20  0.#endif../*.** 
1b00: 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
1b10: 65 72 20 6f 66 20 61 74 74 61 63 68 65 64 20 64  er of attached d
1b20: 61 74 61 62 61 73 65 73 2e 20 20 54 68 69 73 20  atabases.  This 
1b30: 6d 75 73 74 20 62 65 20 62 65 74 77 65 65 6e 20  must be between 
1b40: 30 0a 2a 2a 20 61 6e 64 20 36 32 2e 20 20 54 68  0.** and 62.  Th
1b50: 65 20 75 70 70 65 72 20 62 6f 75 6e 64 20 6f 6e  e upper bound on
1b60: 20 36 32 20 69 73 20 62 65 63 61 75 73 65 20 61   62 is because a
1b70: 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20   64-bit integer 
1b80: 62 69 74 6d 61 70 0a 2a 2a 20 69 73 20 75 73 65  bitmap.** is use
1b90: 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20  d internally to 
1ba0: 74 72 61 63 6b 20 61 74 74 61 63 68 65 64 20 64  track attached d
1bb0: 61 74 61 62 61 73 65 73 2e 0a 2a 2f 0a 23 69 66  atabases..*/.#if
1bc0: 6e 64 65 66 20 53 51 4c 49 54 45 5f 4d 41 58 5f  ndef SQLITE_MAX_
1bd0: 41 54 54 41 43 48 45 44 0a 23 20 64 65 66 69 6e  ATTACHED.# defin
1be0: 65 20 53 51 4c 49 54 45 5f 4d 41 58 5f 41 54 54  e SQLITE_MAX_ATT
1bf0: 41 43 48 45 44 20 31 30 0a 23 65 6e 64 69 66 0a  ACHED 10.#endif.
1c00: 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 6d 61 78 69  ../*.** The maxi
1c10: 6d 75 6d 20 76 61 6c 75 65 20 6f 66 20 61 20 3f  mum value of a ?
1c20: 6e 6e 6e 20 77 69 6c 64 63 61 72 64 20 74 68 61  nnn wildcard tha
1c30: 74 20 74 68 65 20 70 61 72 73 65 72 20 77 69 6c  t the parser wil
1c40: 6c 20 61 63 63 65 70 74 2e 0a 2a 2f 0a 23 69 66  l accept..*/.#if
1c50: 6e 64 65 66 20 53 51 4c 49 54 45 5f 4d 41 58 5f  ndef SQLITE_MAX_
1c60: 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 0a  VARIABLE_NUMBER.
1c70: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
1c80: 4d 41 58 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d  MAX_VARIABLE_NUM
1c90: 42 45 52 20 39 39 39 0a 23 65 6e 64 69 66 0a 0a  BER 999.#endif..
1ca0: 2f 2a 20 4d 61 78 69 6d 75 6d 20 70 61 67 65 20  /* Maximum page 
1cb0: 73 69 7a 65 2e 20 20 54 68 65 20 75 70 70 65 72  size.  The upper
1cc0: 20 62 6f 75 6e 64 20 6f 6e 20 74 68 69 73 20 76   bound on this v
1cd0: 61 6c 75 65 20 69 73 20 36 35 35 33 36 2e 20 20  alue is 65536.  
1ce0: 54 68 69 73 20 61 20 6c 69 6d 69 74 0a 2a 2a 20  This a limit.** 
1cf0: 69 6d 70 6f 73 65 64 20 62 79 20 74 68 65 20 75  imposed by the u
1d00: 73 65 20 6f 66 20 31 36 2d 62 69 74 20 6f 66 66  se of 16-bit off
1d10: 73 65 74 73 20 77 69 74 68 69 6e 20 65 61 63 68  sets within each
1d20: 20 70 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 45 61 72   page..**.** Ear
1d30: 6c 69 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66  lier versions of
1d40: 20 53 51 4c 69 74 65 20 61 6c 6c 6f 77 65 64 20   SQLite allowed 
1d50: 74 68 65 20 75 73 65 72 20 74 6f 20 63 68 61 6e  the user to chan
1d60: 67 65 20 74 68 69 73 20 76 61 6c 75 65 20 61 74  ge this value at
1d70: 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65  .** compile time
1d80: 2e 20 54 68 69 73 20 69 73 20 6e 6f 20 6c 6f 6e  . This is no lon
1d90: 67 65 72 20 70 65 72 6d 69 74 74 65 64 2c 20 6f  ger permitted, o
1da0: 6e 20 74 68 65 20 67 72 6f 75 6e 64 73 20 74 68  n the grounds th
1db0: 61 74 20 69 74 20 63 72 65 61 74 65 73 0a 2a 2a  at it creates.**
1dc0: 20 61 20 6c 69 62 72 61 72 79 20 74 68 61 74 20   a library that 
1dd0: 69 73 20 74 65 63 68 6e 69 63 61 6c 6c 79 20 69  is technically i
1de0: 6e 63 6f 6d 70 61 74 69 62 6c 65 20 77 69 74 68  ncompatible with
1df0: 20 61 6e 20 53 51 4c 69 74 65 20 6c 69 62 72 61   an SQLite libra
1e00: 72 79 20 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20  ry .** compiled 
1e10: 77 69 74 68 20 61 20 64 69 66 66 65 72 65 6e 74  with a different
1e20: 20 6c 69 6d 69 74 2e 20 49 66 20 61 20 70 72 6f   limit. If a pro
1e30: 63 65 73 73 20 6f 70 65 72 61 74 69 6e 67 20 6f  cess operating o
1e40: 6e 20 61 20 64 61 74 61 62 61 73 65 20 0a 2a 2a  n a database .**
1e50: 20 77 69 74 68 20 61 20 70 61 67 65 2d 73 69 7a   with a page-siz
1e60: 65 20 6f 66 20 36 35 35 33 36 20 62 79 74 65 73  e of 65536 bytes
1e70: 20 63 72 61 73 68 65 73 2c 20 74 68 65 6e 20 61   crashes, then a
1e80: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 53 51  n instance of SQ
1e90: 4c 69 74 65 20 0a 2a 2a 20 63 6f 6d 70 69 6c 65  Lite .** compile
1ea0: 64 20 77 69 74 68 20 74 68 65 20 64 65 66 61 75  d with the defau
1eb0: 6c 74 20 70 61 67 65 2d 73 69 7a 65 20 6c 69 6d  lt page-size lim
1ec0: 69 74 20 77 69 6c 6c 20 6e 6f 74 20 62 65 20 61  it will not be a
1ed0: 62 6c 65 20 74 6f 20 72 6f 6c 6c 62 61 63 6b 20  ble to rollback 
1ee0: 0a 2a 2a 20 74 68 65 20 61 62 6f 72 74 65 64 20  .** the aborted 
1ef0: 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 54 68 69  transaction. Thi
1f00: 73 20 63 6f 75 6c 64 20 6c 65 61 64 20 74 6f 20  s could lead to 
1f10: 64 61 74 61 62 61 73 65 20 63 6f 72 72 75 70 74  database corrupt
1f20: 69 6f 6e 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53  ion..*/.#ifdef S
1f30: 51 4c 49 54 45 5f 4d 41 58 5f 50 41 47 45 5f 53  QLITE_MAX_PAGE_S
1f40: 49 5a 45 0a 23 20 75 6e 64 65 66 20 53 51 4c 49  IZE.# undef SQLI
1f50: 54 45 5f 4d 41 58 5f 50 41 47 45 5f 53 49 5a 45  TE_MAX_PAGE_SIZE
1f60: 0a 23 65 6e 64 69 66 0a 23 64 65 66 69 6e 65 20  .#endif.#define 
1f70: 53 51 4c 49 54 45 5f 4d 41 58 5f 50 41 47 45 5f  SQLITE_MAX_PAGE_
1f80: 53 49 5a 45 20 36 35 35 33 36 0a 0a 0a 2f 2a 0a  SIZE 65536.../*.
1f90: 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20 73  ** The default s
1fa0: 69 7a 65 20 6f 66 20 61 20 64 61 74 61 62 61 73  ize of a databas
1fb0: 65 20 70 61 67 65 2e 0a 2a 2f 0a 23 69 66 6e 64  e page..*/.#ifnd
1fc0: 65 66 20 53 51 4c 49 54 45 5f 44 45 46 41 55 4c  ef SQLITE_DEFAUL
1fd0: 54 5f 50 41 47 45 5f 53 49 5a 45 0a 23 20 64 65  T_PAGE_SIZE.# de
1fe0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 46 41  fine SQLITE_DEFA
1ff0: 55 4c 54 5f 50 41 47 45 5f 53 49 5a 45 20 31 30  ULT_PAGE_SIZE 10
2000: 32 34 0a 23 65 6e 64 69 66 0a 23 69 66 20 53 51  24.#endif.#if SQ
2010: 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 50 41 47  LITE_DEFAULT_PAG
2020: 45 5f 53 49 5a 45 3e 53 51 4c 49 54 45 5f 4d 41  E_SIZE>SQLITE_MA
2030: 58 5f 50 41 47 45 5f 53 49 5a 45 0a 23 20 75 6e  X_PAGE_SIZE.# un
2040: 64 65 66 20 53 51 4c 49 54 45 5f 44 45 46 41 55  def SQLITE_DEFAU
2050: 4c 54 5f 50 41 47 45 5f 53 49 5a 45 0a 23 20 64  LT_PAGE_SIZE.# d
2060: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 46  efine SQLITE_DEF
2070: 41 55 4c 54 5f 50 41 47 45 5f 53 49 5a 45 20 53  AULT_PAGE_SIZE S
2080: 51 4c 49 54 45 5f 4d 41 58 5f 50 41 47 45 5f 53  QLITE_MAX_PAGE_S
2090: 49 5a 45 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a  IZE.#endif../*.*
20a0: 2a 20 4f 72 64 69 6e 61 72 69 6c 79 2c 20 69 66  * Ordinarily, if
20b0: 20 6e 6f 20 76 61 6c 75 65 20 69 73 20 65 78 70   no value is exp
20c0: 6c 69 63 69 74 6c 79 20 70 72 6f 76 69 64 65 64  licitly provided
20d0: 2c 20 53 51 4c 69 74 65 20 63 72 65 61 74 65 73  , SQLite creates
20e0: 20 64 61 74 61 62 61 73 65 73 0a 2a 2a 20 77 69   databases.** wi
20f0: 74 68 20 70 61 67 65 20 73 69 7a 65 20 53 51 4c  th page size SQL
2100: 49 54 45 5f 44 45 46 41 55 4c 54 5f 50 41 47 45  ITE_DEFAULT_PAGE
2110: 5f 53 49 5a 45 2e 20 48 6f 77 65 76 65 72 2c 20  _SIZE. However, 
2120: 62 61 73 65 64 20 6f 6e 20 63 65 72 74 61 69 6e  based on certain
2130: 0a 2a 2a 20 64 65 76 69 63 65 20 63 68 61 72 61  .** device chara
2140: 63 74 65 72 69 73 74 69 63 73 20 28 73 65 63 74  cteristics (sect
2150: 6f 72 2d 73 69 7a 65 20 61 6e 64 20 61 74 6f 6d  or-size and atom
2160: 69 63 20 77 72 69 74 65 28 29 20 73 75 70 70 6f  ic write() suppo
2170: 72 74 29 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 6d  rt),.** SQLite m
2180: 61 79 20 63 68 6f 6f 73 65 20 61 20 6c 61 72 67  ay choose a larg
2190: 65 72 20 76 61 6c 75 65 2e 20 54 68 69 73 20 63  er value. This c
21a0: 6f 6e 73 74 61 6e 74 20 69 73 20 74 68 65 20 6d  onstant is the m
21b0: 61 78 69 6d 75 6d 20 76 61 6c 75 65 0a 2a 2a 20  aximum value.** 
21c0: 53 51 4c 69 74 65 20 77 69 6c 6c 20 63 68 6f 6f  SQLite will choo
21d0: 73 65 20 6f 6e 20 69 74 73 20 6f 77 6e 2e 0a 2a  se on its own..*
21e0: 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45  /.#ifndef SQLITE
21f0: 5f 4d 41 58 5f 44 45 46 41 55 4c 54 5f 50 41 47  _MAX_DEFAULT_PAG
2200: 45 5f 53 49 5a 45 0a 23 20 64 65 66 69 6e 65 20  E_SIZE.# define 
2210: 53 51 4c 49 54 45 5f 4d 41 58 5f 44 45 46 41 55  SQLITE_MAX_DEFAU
2220: 4c 54 5f 50 41 47 45 5f 53 49 5a 45 20 38 31 39  LT_PAGE_SIZE 819
2230: 32 0a 23 65 6e 64 69 66 0a 23 69 66 20 53 51 4c  2.#endif.#if SQL
2240: 49 54 45 5f 4d 41 58 5f 44 45 46 41 55 4c 54 5f  ITE_MAX_DEFAULT_
2250: 50 41 47 45 5f 53 49 5a 45 3e 53 51 4c 49 54 45  PAGE_SIZE>SQLITE
2260: 5f 4d 41 58 5f 50 41 47 45 5f 53 49 5a 45 0a 23  _MAX_PAGE_SIZE.#
2270: 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 4d 41   undef SQLITE_MA
2280: 58 5f 44 45 46 41 55 4c 54 5f 50 41 47 45 5f 53  X_DEFAULT_PAGE_S
2290: 49 5a 45 0a 23 20 64 65 66 69 6e 65 20 53 51 4c  IZE.# define SQL
22a0: 49 54 45 5f 4d 41 58 5f 44 45 46 41 55 4c 54 5f  ITE_MAX_DEFAULT_
22b0: 50 41 47 45 5f 53 49 5a 45 20 53 51 4c 49 54 45  PAGE_SIZE SQLITE
22c0: 5f 4d 41 58 5f 50 41 47 45 5f 53 49 5a 45 0a 23  _MAX_PAGE_SIZE.#
22d0: 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a 2a 20 4d 61  endif.../*.** Ma
22e0: 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
22f0: 70 61 67 65 73 20 69 6e 20 6f 6e 65 20 64 61 74  pages in one dat
2300: 61 62 61 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a  abase file..**.*
2310: 2a 20 54 68 69 73 20 69 73 20 72 65 61 6c 6c 79  * This is really
2320: 20 6a 75 73 74 20 74 68 65 20 64 65 66 61 75 6c   just the defaul
2330: 74 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20  t value for the 
2340: 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 20 70  max_page_count p
2350: 72 61 67 6d 61 2e 0a 2a 2a 20 54 68 69 73 20 76  ragma..** This v
2360: 61 6c 75 65 20 63 61 6e 20 62 65 20 6c 6f 77 65  alue can be lowe
2370: 72 65 64 20 28 6f 72 20 72 61 69 73 65 64 29 20  red (or raised) 
2380: 61 74 20 72 75 6e 2d 74 69 6d 65 20 75 73 69 6e  at run-time usin
2390: 67 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 6d 61  g that the.** ma
23a0: 78 5f 70 61 67 65 5f 63 6f 75 6e 74 20 6d 61 63  x_page_count mac
23b0: 72 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53  ro..*/.#ifndef S
23c0: 51 4c 49 54 45 5f 4d 41 58 5f 50 41 47 45 5f 43  QLITE_MAX_PAGE_C
23d0: 4f 55 4e 54 0a 23 20 64 65 66 69 6e 65 20 53 51  OUNT.# define SQ
23e0: 4c 49 54 45 5f 4d 41 58 5f 50 41 47 45 5f 43 4f  LITE_MAX_PAGE_CO
23f0: 55 4e 54 20 31 30 37 33 37 34 31 38 32 33 0a 23  UNT 1073741823.#
2400: 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 4d 61 78  endif../*.** Max
2410: 69 6d 75 6d 20 6c 65 6e 67 74 68 20 28 69 6e 20  imum length (in 
2420: 62 79 74 65 73 29 20 6f 66 20 74 68 65 20 70 61  bytes) of the pa
2430: 74 74 65 72 6e 20 69 6e 20 61 20 4c 49 4b 45 20  ttern in a LIKE 
2440: 6f 72 20 47 4c 4f 42 0a 2a 2a 20 6f 70 65 72 61  or GLOB.** opera
2450: 74 6f 72 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20  tor..*/.#ifndef 
2460: 53 51 4c 49 54 45 5f 4d 41 58 5f 4c 49 4b 45 5f  SQLITE_MAX_LIKE_
2470: 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 0a 23  PATTERN_LENGTH.#
2480: 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d   define SQLITE_M
2490: 41 58 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f  AX_LIKE_PATTERN_
24a0: 4c 45 4e 47 54 48 20 35 30 30 30 30 0a 23 65 6e  LENGTH 50000.#en
24b0: 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 4d 61 78 69 6d  dif../*.** Maxim
24c0: 75 6d 20 64 65 70 74 68 20 6f 66 20 72 65 63 75  um depth of recu
24d0: 72 73 69 6f 6e 20 66 6f 72 20 74 72 69 67 67 65  rsion for trigge
24e0: 72 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 76 61 6c 75  rs..**.** A valu
24f0: 65 20 6f 66 20 31 20 6d 65 61 6e 73 20 74 68 61  e of 1 means tha
2500: 74 20 61 20 74 72 69 67 67 65 72 20 70 72 6f 67  t a trigger prog
2510: 72 61 6d 20 77 69 6c 6c 20 6e 6f 74 20 62 65 20  ram will not be 
2520: 61 62 6c 65 20 74 6f 20 69 74 73 65 6c 66 0a 2a  able to itself.*
2530: 2a 20 66 69 72 65 20 61 6e 79 20 74 72 69 67 67  * fire any trigg
2540: 65 72 73 2e 20 41 20 76 61 6c 75 65 20 6f 66 20  ers. A value of 
2550: 30 20 6d 65 61 6e 73 20 74 68 61 74 20 6e 6f 20  0 means that no 
2560: 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 73  trigger programs
2570: 20 61 74 20 61 6c 6c 20 0a 2a 2a 20 6d 61 79 20   at all .** may 
2580: 62 65 20 65 78 65 63 75 74 65 64 2e 0a 2a 2f 0a  be executed..*/.
2590: 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4d  #ifndef SQLITE_M
25a0: 41 58 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48  AX_TRIGGER_DEPTH
25b0: 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45  .# define SQLITE
25c0: 5f 4d 41 58 5f 54 52 49 47 47 45 52 5f 44 45 50  _MAX_TRIGGER_DEP
25d0: 54 48 20 31 30 30 30 0a 23 65 6e 64 69 66 0a 0a  TH 1000.#endif..
25e0: 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20  /************** 
25f0: 45 6e 64 20 6f 66 20 73 71 6c 69 74 65 4c 69 6d  End of sqliteLim
2600: 69 74 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  it.h ***********
2610: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
2620: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a  **************/.
2630: 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20  /************** 
2640: 43 6f 6e 74 69 6e 75 69 6e 67 20 77 68 65 72 65  Continuing where
2650: 20 77 65 20 6c 65 66 74 20 6f 66 66 20 69 6e 20   we left off in 
2660: 73 71 6c 69 74 65 49 6e 74 2e 68 20 2a 2a 2a 2a  sqliteInt.h ****
2670: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a  **************/.
2680: 0a 2f 2a 20 44 69 73 61 62 6c 65 20 6e 75 69 73  ./* Disable nuis
2690: 61 6e 63 65 20 77 61 72 6e 69 6e 67 73 20 6f 6e  ance warnings on
26a0: 20 42 6f 72 6c 61 6e 64 20 63 6f 6d 70 69 6c 65   Borland compile
26b0: 72 73 20 2a 2f 0a 23 69 66 20 64 65 66 69 6e 65  rs */.#if define
26c0: 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29 0a  d(__BORLANDC__).
26d0: 23 70 72 61 67 6d 61 20 77 61 72 6e 20 2d 72 63  #pragma warn -rc
26e0: 68 20 2f 2a 20 75 6e 72 65 61 63 68 61 62 6c 65  h /* unreachable
26f0: 20 63 6f 64 65 20 2a 2f 0a 23 70 72 61 67 6d 61   code */.#pragma
2700: 20 77 61 72 6e 20 2d 63 63 63 20 2f 2a 20 43 6f   warn -ccc /* Co
2710: 6e 64 69 74 69 6f 6e 20 69 73 20 61 6c 77 61 79  ndition is alway
2720: 73 20 74 72 75 65 20 6f 72 20 66 61 6c 73 65 20  s true or false 
2730: 2a 2f 0a 23 70 72 61 67 6d 61 20 77 61 72 6e 20  */.#pragma warn 
2740: 2d 61 75 73 20 2f 2a 20 41 73 73 69 67 6e 65 64  -aus /* Assigned
2750: 20 76 61 6c 75 65 20 69 73 20 6e 65 76 65 72 20   value is never 
2760: 75 73 65 64 20 2a 2f 0a 23 70 72 61 67 6d 61 20  used */.#pragma 
2770: 77 61 72 6e 20 2d 63 73 75 20 2f 2a 20 43 6f 6d  warn -csu /* Com
2780: 70 61 72 69 6e 67 20 73 69 67 6e 65 64 20 61 6e  paring signed an
2790: 64 20 75 6e 73 69 67 6e 65 64 20 2a 2f 0a 23 70  d unsigned */.#p
27a0: 72 61 67 6d 61 20 77 61 72 6e 20 2d 73 70 61 20  ragma warn -spa 
27b0: 2f 2a 20 53 75 73 70 69 63 69 6f 75 73 20 70 6f  /* Suspicious po
27c0: 69 6e 74 65 72 20 61 72 69 74 68 6d 65 74 69 63  inter arithmetic
27d0: 20 2a 2f 0a 23 65 6e 64 69 66 0a 0a 2f 2a 20 4e   */.#endif../* N
27e0: 65 65 64 65 64 20 66 6f 72 20 76 61 72 69 6f 75  eeded for variou
27f0: 73 20 64 65 66 69 6e 69 74 69 6f 6e 73 2e 2e 2e  s definitions...
2800: 20 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 47 4e 55   */.#ifndef _GNU
2810: 5f 53 4f 55 52 43 45 0a 23 20 64 65 66 69 6e 65  _SOURCE.# define
2820: 20 5f 47 4e 55 5f 53 4f 55 52 43 45 0a 23 65 6e   _GNU_SOURCE.#en
2830: 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 49 6e 63 6c 75  dif../*.** Inclu
2840: 64 65 20 73 74 61 6e 64 61 72 64 20 68 65 61 64  de standard head
2850: 65 72 20 66 69 6c 65 73 20 61 73 20 6e 65 63 65  er files as nece
2860: 73 73 61 72 79 0a 2a 2f 0a 23 69 66 64 65 66 20  ssary.*/.#ifdef 
2870: 48 41 56 45 5f 53 54 44 49 4e 54 5f 48 0a 23 69  HAVE_STDINT_H.#i
2880: 6e 63 6c 75 64 65 20 3c 73 74 64 69 6e 74 2e 68  nclude <stdint.h
2890: 3e 0a 23 65 6e 64 69 66 0a 23 69 66 64 65 66 20  >.#endif.#ifdef 
28a0: 48 41 56 45 5f 49 4e 54 54 59 50 45 53 5f 48 0a  HAVE_INTTYPES_H.
28b0: 23 69 6e 63 6c 75 64 65 20 3c 69 6e 74 74 79 70  #include <inttyp
28c0: 65 73 2e 68 3e 0a 23 65 6e 64 69 66 0a 0a 2f 2a  es.h>.#endif../*
28d0: 0a 2a 2a 20 54 68 65 20 6e 75 6d 62 65 72 20 6f  .** The number o
28e0: 66 20 73 61 6d 70 6c 65 73 20 6f 66 20 61 6e 20  f samples of an 
28f0: 69 6e 64 65 78 20 74 68 61 74 20 53 51 4c 69 74  index that SQLit
2900: 65 20 74 61 6b 65 73 20 69 6e 20 6f 72 64 65 72  e takes in order
2910: 20 74 6f 20 0a 2a 2a 20 63 6f 6e 73 74 72 75 63   to .** construc
2920: 74 20 61 20 68 69 73 74 6f 67 72 61 6d 20 6f 66  t a histogram of
2930: 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6e 74 65   the table conte
2940: 6e 74 20 77 68 65 6e 20 72 75 6e 6e 69 6e 67 20  nt when running 
2950: 41 4e 41 4c 59 5a 45 0a 2a 2a 20 61 6e 64 20 77  ANALYZE.** and w
2960: 69 74 68 20 53 51 4c 49 54 45 5f 45 4e 41 42 4c  ith SQLITE_ENABL
2970: 45 5f 53 54 41 54 32 0a 2a 2f 0a 23 64 65 66 69  E_STAT2.*/.#defi
2980: 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f  ne SQLITE_INDEX_
2990: 53 41 4d 50 4c 45 53 20 31 30 0a 0a 2f 2a 0a 2a  SAMPLES 10../*.*
29a0: 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  * The following 
29b0: 6d 61 63 72 6f 73 20 61 72 65 20 75 73 65 64 20  macros are used 
29c0: 74 6f 20 63 61 73 74 20 70 6f 69 6e 74 65 72 73  to cast pointers
29d0: 20 74 6f 20 69 6e 74 65 67 65 72 73 20 61 6e 64   to integers and
29e0: 0a 2a 2a 20 69 6e 74 65 67 65 72 73 20 74 6f 20  .** integers to 
29f0: 70 6f 69 6e 74 65 72 73 2e 20 20 54 68 65 20 77  pointers.  The w
2a00: 61 79 20 79 6f 75 20 64 6f 20 74 68 69 73 20 76  ay you do this v
2a10: 61 72 69 65 73 20 66 72 6f 6d 20 6f 6e 65 20 63  aries from one c
2a20: 6f 6d 70 69 6c 65 72 0a 2a 2a 20 74 6f 20 74 68  ompiler.** to th
2a30: 65 20 6e 65 78 74 2c 20 73 6f 20 77 65 20 68 61  e next, so we ha
2a40: 76 65 20 64 65 76 65 6c 6f 70 65 64 20 74 68 65  ve developed the
2a50: 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 65 74 20 6f   following set o
2a60: 66 20 23 69 66 20 73 74 61 74 65 6d 65 6e 74 73  f #if statements
2a70: 0a 2a 2a 20 74 6f 20 67 65 6e 65 72 61 74 65 20  .** to generate 
2a80: 61 70 70 72 6f 70 72 69 61 74 65 20 6d 61 63 72  appropriate macr
2a90: 6f 73 20 66 6f 72 20 61 20 77 69 64 65 20 72 61  os for a wide ra
2aa0: 6e 67 65 20 6f 66 20 63 6f 6d 70 69 6c 65 72 73  nge of compilers
2ab0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 72 72  ..**.** The corr
2ac0: 65 63 74 20 22 41 4e 53 49 22 20 77 61 79 20 74  ect "ANSI" way t
2ad0: 6f 20 64 6f 20 74 68 69 73 20 69 73 20 74 6f 20  o do this is to 
2ae0: 75 73 65 20 74 68 65 20 69 6e 74 70 74 72 5f 74  use the intptr_t
2af0: 20 74 79 70 65 2e 20 0a 2a 2a 20 55 6e 66 6f 72   type. .** Unfor
2b00: 74 75 6e 61 74 65 6c 79 2c 20 74 68 61 74 20 74  tunately, that t
2b10: 79 70 65 64 65 66 20 69 73 20 6e 6f 74 20 61 76  ypedef is not av
2b20: 61 69 6c 61 62 6c 65 20 6f 6e 20 61 6c 6c 20 63  ailable on all c
2b30: 6f 6d 70 69 6c 65 72 73 2c 20 6f 72 0a 2a 2a 20  ompilers, or.** 
2b40: 69 66 20 69 74 20 69 73 20 61 76 61 69 6c 61 62  if it is availab
2b50: 6c 65 2c 20 69 74 20 72 65 71 75 69 72 65 73 20  le, it requires 
2b60: 61 6e 20 23 69 6e 63 6c 75 64 65 20 6f 66 20 73  an #include of s
2b70: 70 65 63 69 66 69 63 20 68 65 61 64 65 72 73 0a  pecific headers.
2b80: 2a 2a 20 74 68 61 74 20 76 61 72 79 20 66 72 6f  ** that vary fro
2b90: 6d 20 6f 6e 65 20 6d 61 63 68 69 6e 65 20 74 6f  m one machine to
2ba0: 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2a 0a 2a 2a   the next..**.**
2bb0: 20 54 69 63 6b 65 74 20 23 33 38 36 30 3a 20 20   Ticket #3860:  
2bc0: 54 68 65 20 6c 6c 76 6d 2d 67 63 63 2d 34 2e 32  The llvm-gcc-4.2
2bd0: 20 63 6f 6d 70 69 6c 65 72 20 66 72 6f 6d 20 41   compiler from A
2be0: 70 70 6c 65 20 63 68 6f 6b 65 73 20 6f 6e 0a 2a  pple chokes on.*
2bf0: 2a 20 74 68 65 20 28 28 76 6f 69 64 2a 29 26 28  * the ((void*)&(
2c00: 28 63 68 61 72 2a 29 30 29 5b 58 5d 29 20 63 6f  (char*)0)[X]) co
2c10: 6e 73 74 72 75 63 74 2e 20 20 42 75 74 20 4d 53  nstruct.  But MS
2c20: 56 43 20 63 68 6f 6b 65 73 20 6f 6e 20 28 28 76  VC chokes on ((v
2c30: 6f 69 64 2a 29 28 58 29 29 2e 0a 2a 2a 20 53 6f  oid*)(X))..** So
2c40: 20 77 65 20 68 61 76 65 20 74 6f 20 64 65 66 69   we have to defi
2c50: 6e 65 20 74 68 65 20 6d 61 63 72 6f 73 20 69 6e  ne the macros in
2c60: 20 64 69 66 66 65 72 65 6e 74 20 77 61 79 73 20   different ways 
2c70: 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65  depending on the
2c80: 0a 2a 2a 20 63 6f 6d 70 69 6c 65 72 2e 0a 2a 2f  .** compiler..*/
2c90: 0a 23 69 66 20 64 65 66 69 6e 65 64 28 5f 5f 50  .#if defined(__P
2ca0: 54 52 44 49 46 46 5f 54 59 50 45 5f 5f 29 20 20  TRDIFF_TYPE__)  
2cb0: 2f 2a 20 54 68 69 73 20 63 61 73 65 20 73 68 6f  /* This case sho
2cc0: 75 6c 64 20 77 6f 72 6b 20 66 6f 72 20 47 43 43  uld work for GCC
2cd0: 20 2a 2f 0a 23 20 64 65 66 69 6e 65 20 53 51 4c   */.# define SQL
2ce0: 49 54 45 5f 49 4e 54 5f 54 4f 5f 50 54 52 28 58  ITE_INT_TO_PTR(X
2cf0: 29 20 20 28 28 76 6f 69 64 2a 29 28 5f 5f 50 54  )  ((void*)(__PT
2d00: 52 44 49 46 46 5f 54 59 50 45 5f 5f 29 28 58 29  RDIFF_TYPE__)(X)
2d10: 29 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54  ).# define SQLIT
2d20: 45 5f 50 54 52 5f 54 4f 5f 49 4e 54 28 58 29 20  E_PTR_TO_INT(X) 
2d30: 20 28 28 69 6e 74 29 28 5f 5f 50 54 52 44 49 46   ((int)(__PTRDIF
2d40: 46 5f 54 59 50 45 5f 5f 29 28 58 29 29 0a 23 65  F_TYPE__)(X)).#e
2d50: 6c 69 66 20 21 64 65 66 69 6e 65 64 28 5f 5f 47  lif !defined(__G
2d60: 4e 55 43 5f 5f 29 20 20 20 20 20 20 20 2f 2a 20  NUC__)       /* 
2d70: 57 6f 72 6b 73 20 66 6f 72 20 63 6f 6d 70 69 6c  Works for compil
2d80: 65 72 73 20 6f 74 68 65 72 20 74 68 61 6e 20 4c  ers other than L
2d90: 4c 56 4d 20 2a 2f 0a 23 20 64 65 66 69 6e 65 20  LVM */.# define 
2da0: 53 51 4c 49 54 45 5f 49 4e 54 5f 54 4f 5f 50 54  SQLITE_INT_TO_PT
2db0: 52 28 58 29 20 20 28 28 76 6f 69 64 2a 29 26 28  R(X)  ((void*)&(
2dc0: 28 63 68 61 72 2a 29 30 29 5b 58 5d 29 0a 23 20  (char*)0)[X]).# 
2dd0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 54  define SQLITE_PT
2de0: 52 5f 54 4f 5f 49 4e 54 28 58 29 20 20 28 28 69  R_TO_INT(X)  ((i
2df0: 6e 74 29 28 28 28 63 68 61 72 2a 29 58 29 2d 28  nt)(((char*)X)-(
2e00: 63 68 61 72 2a 29 30 29 29 0a 23 65 6c 69 66 20  char*)0)).#elif 
2e10: 64 65 66 69 6e 65 64 28 48 41 56 45 5f 53 54 44  defined(HAVE_STD
2e20: 49 4e 54 5f 48 29 20 20 20 2f 2a 20 55 73 65 20  INT_H)   /* Use 
2e30: 74 68 69 73 20 63 61 73 65 20 69 66 20 77 65 20  this case if we 
2e40: 68 61 76 65 20 41 4e 53 49 20 68 65 61 64 65 72  have ANSI header
2e50: 73 20 2a 2f 0a 23 20 64 65 66 69 6e 65 20 53 51  s */.# define SQ
2e60: 4c 49 54 45 5f 49 4e 54 5f 54 4f 5f 50 54 52 28  LITE_INT_TO_PTR(
2e70: 58 29 20 20 28 28 76 6f 69 64 2a 29 28 69 6e 74  X)  ((void*)(int
2e80: 70 74 72 5f 74 29 28 58 29 29 0a 23 20 64 65 66  ptr_t)(X)).# def
2e90: 69 6e 65 20 53 51 4c 49 54 45 5f 50 54 52 5f 54  ine SQLITE_PTR_T
2ea0: 4f 5f 49 4e 54 28 58 29 20 20 28 28 69 6e 74 29  O_INT(X)  ((int)
2eb0: 28 69 6e 74 70 74 72 5f 74 29 28 58 29 29 0a 23  (intptr_t)(X)).#
2ec0: 65 6c 73 65 20 20 20 20 20 20 20 20 20 20 20 20  else            
2ed0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
2ee0: 20 47 65 6e 65 72 61 74 65 73 20 61 20 77 61 72   Generates a war
2ef0: 6e 69 6e 67 20 2d 20 62 75 74 20 69 74 20 61 6c  ning - but it al
2f00: 77 61 79 73 20 77 6f 72 6b 73 20 2a 2f 0a 23 20  ways works */.# 
2f10: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
2f20: 54 5f 54 4f 5f 50 54 52 28 58 29 20 20 28 28 76  T_TO_PTR(X)  ((v
2f30: 6f 69 64 2a 29 28 58 29 29 0a 23 20 64 65 66 69  oid*)(X)).# defi
2f40: 6e 65 20 53 51 4c 49 54 45 5f 50 54 52 5f 54 4f  ne SQLITE_PTR_TO
2f50: 5f 49 4e 54 28 58 29 20 20 28 28 69 6e 74 29 28  _INT(X)  ((int)(
2f60: 58 29 29 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a  X)).#endif../*.*
2f70: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 54 48 52  * The SQLITE_THR
2f80: 45 41 44 53 41 46 45 20 6d 61 63 72 6f 20 6d 75  EADSAFE macro mu
2f90: 73 74 20 62 65 20 64 65 66 69 6e 65 64 20 61 73  st be defined as
2fa0: 20 30 2c 20 31 2c 20 6f 72 20 32 2e 0a 2a 2a 20   0, 1, or 2..** 
2fb0: 30 20 6d 65 61 6e 73 20 6d 75 74 65 78 65 73 20  0 means mutexes 
2fc0: 61 72 65 20 70 65 72 6d 61 6e 65 6e 74 6c 79 20  are permanently 
2fd0: 64 69 73 61 62 6c 65 20 61 6e 64 20 74 68 65 20  disable and the 
2fe0: 6c 69 62 72 61 72 79 20 69 73 20 6e 65 76 65 72  library is never
2ff0: 0a 2a 2a 20 74 68 72 65 61 64 73 61 66 65 2e 20  .** threadsafe. 
3000: 20 31 20 6d 65 61 6e 73 20 74 68 65 20 6c 69 62   1 means the lib
3010: 72 61 72 79 20 69 73 20 73 65 72 69 61 6c 69 7a  rary is serializ
3020: 65 64 20 77 68 69 63 68 20 69 73 20 74 68 65 20  ed which is the 
3030: 68 69 67 68 65 73 74 0a 2a 2a 20 6c 65 76 65 6c  highest.** level
3040: 20 6f 66 20 74 68 72 65 61 64 73 61 66 65 74 79   of threadsafety
3050: 2e 20 20 32 20 6d 65 61 6e 73 20 74 68 65 20 6c  .  2 means the l
3060: 69 62 61 72 79 20 69 73 20 6d 75 6c 74 69 74 68  ibary is multith
3070: 72 65 61 64 65 64 20 2d 20 6d 75 6c 74 69 70 6c  readed - multipl
3080: 65 0a 2a 2a 20 74 68 72 65 61 64 73 20 63 61 6e  e.** threads can
3090: 20 75 73 65 20 53 51 4c 69 74 65 20 61 73 20 6c   use SQLite as l
30a0: 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20 74 68  ong as no two th
30b0: 72 65 61 64 73 20 74 72 79 20 74 6f 20 75 73 65  reads try to use
30c0: 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 64 61 74   the same.** dat
30d0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
30e0: 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d   at the same tim
30f0: 65 2e 0a 2a 2a 0a 2a 2a 20 4f 6c 64 65 72 20 76  e..**.** Older v
3100: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
3110: 65 20 75 73 65 64 20 61 6e 20 6f 70 74 69 6f 6e  e used an option
3120: 61 6c 20 54 48 52 45 41 44 53 41 46 45 20 6d 61  al THREADSAFE ma
3130: 63 72 6f 2e 0a 2a 2a 20 57 65 20 73 75 70 70 6f  cro..** We suppo
3140: 72 74 20 74 68 61 74 20 66 6f 72 20 6c 65 67 61  rt that for lega
3150: 63 79 2e 0a 2a 2f 0a 23 69 66 20 21 64 65 66 69  cy..*/.#if !defi
3160: 6e 65 64 28 53 51 4c 49 54 45 5f 54 48 52 45 41  ned(SQLITE_THREA
3170: 44 53 41 46 45 29 0a 23 69 66 20 64 65 66 69 6e  DSAFE).#if defin
3180: 65 64 28 54 48 52 45 41 44 53 41 46 45 29 0a 23  ed(THREADSAFE).#
3190: 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54   define SQLITE_T
31a0: 48 52 45 41 44 53 41 46 45 20 54 48 52 45 41 44  HREADSAFE THREAD
31b0: 53 41 46 45 0a 23 65 6c 73 65 0a 23 20 64 65 66  SAFE.#else.# def
31c0: 69 6e 65 20 53 51 4c 49 54 45 5f 54 48 52 45 41  ine SQLITE_THREA
31d0: 44 53 41 46 45 20 31 20 2f 2a 20 49 4d 50 3a 20  DSAFE 1 /* IMP: 
31e0: 52 2d 30 37 32 37 32 2d 32 32 33 30 39 20 2a 2f  R-07272-22309 */
31f0: 0a 23 65 6e 64 69 66 0a 23 65 6e 64 69 66 0a 0a  .#endif.#endif..
3200: 2f 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  /*.** The SQLITE
3210: 5f 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41 54  _DEFAULT_MEMSTAT
3220: 55 53 20 6d 61 63 72 6f 20 6d 75 73 74 20 62 65  US macro must be
3230: 20 64 65 66 69 6e 65 64 20 61 73 20 65 69 74 68   defined as eith
3240: 65 72 20 30 20 6f 72 20 31 2e 0a 2a 2a 20 49 74  er 0 or 1..** It
3250: 20 64 65 74 65 72 6d 69 6e 65 73 20 77 68 65 74   determines whet
3260: 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 66  her or not the f
3270: 65 61 74 75 72 65 73 20 72 65 6c 61 74 65 64 20  eatures related 
3280: 74 6f 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f  to .** SQLITE_CO
3290: 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 61  NFIG_MEMSTATUS a
32a0: 72 65 20 61 76 61 69 6c 61 62 6c 65 20 62 79 20  re available by 
32b0: 64 65 66 61 75 6c 74 20 6f 72 20 6e 6f 74 2e 20  default or not. 
32c0: 54 68 69 73 20 76 61 6c 75 65 20 63 61 6e 0a 2a  This value can.*
32d0: 2a 20 62 65 20 6f 76 65 72 72 69 64 64 65 6e 20  * be overridden 
32e0: 61 74 20 72 75 6e 74 69 6d 65 20 75 73 69 6e 67  at runtime using
32f0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e   the sqlite3_con
3300: 66 69 67 28 29 20 41 50 49 2e 0a 2a 2f 0a 23 69  fig() API..*/.#i
3310: 66 20 21 64 65 66 69 6e 65 64 28 53 51 4c 49 54  f !defined(SQLIT
3320: 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41  E_DEFAULT_MEMSTA
3330: 54 55 53 29 0a 23 20 64 65 66 69 6e 65 20 53 51  TUS).# define SQ
3340: 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d  LITE_DEFAULT_MEM
3350: 53 54 41 54 55 53 20 31 0a 23 65 6e 64 69 66 0a  STATUS 1.#endif.
3360: 0a 2f 2a 0a 2a 2a 20 45 78 61 63 74 6c 79 20 6f  ./*.** Exactly o
3370: 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77  ne of the follow
3380: 69 6e 67 20 6d 61 63 72 6f 73 20 6d 75 73 74 20  ing macros must 
3390: 62 65 20 64 65 66 69 6e 65 64 20 69 6e 20 6f 72  be defined in or
33a0: 64 65 72 20 74 6f 0a 2a 2a 20 73 70 65 63 69 66  der to.** specif
33b0: 79 20 77 68 69 63 68 20 6d 65 6d 6f 72 79 20 61  y which memory a
33c0: 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73  llocation subsys
33d0: 74 65 6d 20 74 6f 20 75 73 65 2e 0a 2a 2a 0a 2a  tem to use..**.*
33e0: 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 53 59 53  *     SQLITE_SYS
33f0: 54 45 4d 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20  TEM_MALLOC      
3400: 20 20 20 20 2f 2f 20 55 73 65 20 6e 6f 72 6d 61      // Use norma
3410: 6c 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28  l system malloc(
3420: 29 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f  ).**     SQLITE_
3430: 4d 45 4d 44 45 42 55 47 20 20 20 20 20 20 20 20  MEMDEBUG        
3440: 20 20 20 20 20 20 20 2f 2f 20 44 65 62 75 67 67         // Debugg
3450: 69 6e 67 20 76 65 72 73 69 6f 6e 20 6f 66 20 73  ing version of s
3460: 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 0a 2a  ystem malloc().*
3470: 2a 0a 2a 2a 20 28 48 69 73 74 6f 72 69 63 61 6c  *.** (Historical
3480: 20 6e 6f 74 65 3a 20 20 54 68 65 72 65 20 75 73   note:  There us
3490: 65 64 20 74 6f 20 62 65 20 73 65 76 65 72 61 6c  ed to be several
34a0: 20 6f 74 68 65 72 20 6f 70 74 69 6f 6e 73 2c 20   other options, 
34b0: 62 75 74 20 77 65 27 76 65 0a 2a 2a 20 70 61 72  but we've.** par
34c0: 65 64 20 69 74 20 64 6f 77 6e 20 74 6f 20 6a 75  ed it down to ju
34d0: 73 74 20 74 68 65 73 65 20 74 77 6f 2e 29 0a 2a  st these two.).*
34e0: 2a 0a 2a 2a 20 49 66 20 6e 6f 6e 65 20 6f 66 20  *.** If none of 
34f0: 74 68 65 20 61 62 6f 76 65 20 61 72 65 20 64 65  the above are de
3500: 66 69 6e 65 64 2c 20 74 68 65 6e 20 73 65 74 20  fined, then set 
3510: 53 51 4c 49 54 45 5f 53 59 53 54 45 4d 5f 4d 41  SQLITE_SYSTEM_MA
3520: 4c 4c 4f 43 20 61 73 0a 2a 2a 20 74 68 65 20 64  LLOC as.** the d
3530: 65 66 61 75 6c 74 2e 0a 2a 2f 0a 23 69 66 20 64  efault..*/.#if d
3540: 65 66 69 6e 65 64 28 53 51 4c 49 54 45 5f 53 59  efined(SQLITE_SY
3550: 53 54 45 4d 5f 4d 41 4c 4c 4f 43 29 2b 64 65 66  STEM_MALLOC)+def
3560: 69 6e 65 64 28 53 51 4c 49 54 45 5f 4d 45 4d 44  ined(SQLITE_MEMD
3570: 45 42 55 47 29 3e 31 0a 23 20 65 72 72 6f 72 20  EBUG)>1.# error 
3580: 22 41 74 20 6d 6f 73 74 20 6f 6e 65 20 6f 66 20  "At most one of 
3590: 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 6f  the following co
35a0: 6d 70 69 6c 65 2d 74 69 6d 65 20 63 6f 6e 66 69  mpile-time confi
35b0: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
35c0: 5c 0a 20 69 73 20 61 6c 6c 6f 77 73 3a 20 53 51  \. is allows: SQ
35d0: 4c 49 54 45 5f 53 59 53 54 45 4d 5f 4d 41 4c 4c  LITE_SYSTEM_MALL
35e0: 4f 43 2c 20 53 51 4c 49 54 45 5f 4d 45 4d 44 45  OC, SQLITE_MEMDE
35f0: 42 55 47 22 0a 23 65 6e 64 69 66 0a 23 69 66 20  BUG".#endif.#if 
3600: 64 65 66 69 6e 65 64 28 53 51 4c 49 54 45 5f 53  defined(SQLITE_S
3610: 59 53 54 45 4d 5f 4d 41 4c 4c 4f 43 29 2b 64 65  YSTEM_MALLOC)+de
3620: 66 69 6e 65 64 28 53 51 4c 49 54 45 5f 4d 45 4d  fined(SQLITE_MEM
3630: 44 45 42 55 47 29 3d 3d 30 0a 23 20 64 65 66 69  DEBUG)==0.# defi
3640: 6e 65 20 53 51 4c 49 54 45 5f 53 59 53 54 45 4d  ne SQLITE_SYSTEM
3650: 5f 4d 41 4c 4c 4f 43 20 31 0a 23 65 6e 64 69 66  _MALLOC 1.#endif
3660: 0a 0a 2f 2a 0a 2a 2a 20 49 66 20 53 51 4c 49 54  ../*.** If SQLIT
3670: 45 5f 4d 41 4c 4c 4f 43 5f 53 4f 46 54 5f 4c 49  E_MALLOC_SOFT_LI
3680: 4d 49 54 20 69 73 20 6e 6f 74 20 7a 65 72 6f 2c  MIT is not zero,
3690: 20 74 68 65 6e 20 74 72 79 20 74 6f 20 6b 65 65   then try to kee
36a0: 70 20 74 68 65 0a 2a 2a 20 73 69 7a 65 73 20 6f  p the.** sizes o
36b0: 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  f memory allocat
36c0: 69 6f 6e 73 20 62 65 6c 6f 77 20 74 68 69 73 20  ions below this 
36d0: 76 61 6c 75 65 20 77 68 65 72 65 20 70 6f 73 73  value where poss
36e0: 69 62 6c 65 2e 0a 2a 2f 0a 23 69 66 20 21 64 65  ible..*/.#if !de
36f0: 66 69 6e 65 64 28 53 51 4c 49 54 45 5f 4d 41 4c  fined(SQLITE_MAL
3700: 4c 4f 43 5f 53 4f 46 54 5f 4c 49 4d 49 54 29 0a  LOC_SOFT_LIMIT).
3710: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
3720: 4d 41 4c 4c 4f 43 5f 53 4f 46 54 5f 4c 49 4d 49  MALLOC_SOFT_LIMI
3730: 54 20 31 30 32 34 0a 23 65 6e 64 69 66 0a 0a 2f  T 1024.#endif../
3740: 2a 0a 2a 2a 20 57 65 20 6e 65 65 64 20 74 6f 20  *.** We need to 
3750: 64 65 66 69 6e 65 20 5f 58 4f 50 45 4e 5f 53 4f  define _XOPEN_SO
3760: 55 52 43 45 20 61 73 20 66 6f 6c 6c 6f 77 73 20  URCE as follows 
3770: 69 6e 20 6f 72 64 65 72 20 74 6f 20 65 6e 61 62  in order to enab
3780: 6c 65 0a 2a 2a 20 72 65 63 75 72 73 69 76 65 20  le.** recursive 
3790: 6d 75 74 65 78 65 73 20 6f 6e 20 6d 6f 73 74 20  mutexes on most 
37a0: 55 6e 69 78 20 73 79 73 74 65 6d 73 2e 20 20 42  Unix systems.  B
37b0: 75 74 20 4d 61 63 20 4f 53 20 58 20 69 73 20 64  ut Mac OS X is d
37c0: 69 66 66 65 72 65 6e 74 2e 0a 2a 2a 20 54 68 65  ifferent..** The
37d0: 20 5f 58 4f 50 45 4e 5f 53 4f 55 52 43 45 20 64   _XOPEN_SOURCE d
37e0: 65 66 69 6e 65 20 63 61 75 73 65 73 20 70 72 6f  efine causes pro
37f0: 62 6c 65 6d 73 20 66 6f 72 20 4d 61 63 20 4f 53  blems for Mac OS
3800: 20 58 20 77 65 20 61 72 65 20 74 6f 6c 64 2c 0a   X we are told,.
3810: 2a 2a 20 73 6f 20 69 74 20 69 73 20 6f 6d 69 74  ** so it is omit
3820: 74 65 64 20 74 68 65 72 65 2e 20 20 53 65 65 20  ted there.  See 
3830: 74 69 63 6b 65 74 20 23 32 36 37 33 2e 0a 2a 2a  ticket #2673..**
3840: 0a 2a 2a 20 4c 61 74 65 72 20 77 65 20 6c 65 61  .** Later we lea
3850: 72 6e 20 74 68 61 74 20 5f 58 4f 50 45 4e 5f 53  rn that _XOPEN_S
3860: 4f 55 52 43 45 20 69 73 20 70 6f 6f 72 6c 79 20  OURCE is poorly 
3870: 6f 72 20 69 6e 63 6f 72 72 65 63 74 6c 79 0a 2a  or incorrectly.*
3880: 2a 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 6f 6e  * implemented on
3890: 20 73 6f 6d 65 20 73 79 73 74 65 6d 73 2e 20 20   some systems.  
38a0: 53 6f 20 77 65 20 61 76 6f 69 64 20 64 65 66 69  So we avoid defi
38b0: 6e 69 6e 67 20 69 74 20 61 74 20 61 6c 6c 0a 2a  ning it at all.*
38c0: 2a 20 69 66 20 69 74 20 69 73 20 61 6c 72 65 61  * if it is alrea
38d0: 64 79 20 64 65 66 69 6e 65 64 20 6f 72 20 69 66  dy defined or if
38e0: 20 69 74 20 69 73 20 75 6e 6e 65 65 64 65 64 20   it is unneeded 
38f0: 62 65 63 61 75 73 65 20 77 65 20 61 72 65 0a 2a  because we are.*
3900: 2a 20 6e 6f 74 20 64 6f 69 6e 67 20 61 20 74 68  * not doing a th
3910: 72 65 61 64 73 61 66 65 20 62 75 69 6c 64 2e 20  readsafe build. 
3920: 20 54 69 63 6b 65 74 20 23 32 36 38 31 2e 0a 2a   Ticket #2681..*
3930: 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 69  *.** See also ti
3940: 63 6b 65 74 20 23 32 37 34 31 2e 0a 2a 2f 0a 23  cket #2741..*/.#
3950: 69 66 20 21 64 65 66 69 6e 65 64 28 5f 58 4f 50  if !defined(_XOP
3960: 45 4e 5f 53 4f 55 52 43 45 29 20 26 26 20 21 64  EN_SOURCE) && !d
3970: 65 66 69 6e 65 64 28 5f 5f 44 41 52 57 49 4e 5f  efined(__DARWIN_
3980: 5f 29 20 26 26 20 21 64 65 66 69 6e 65 64 28 5f  _) && !defined(_
3990: 5f 41 50 50 4c 45 5f 5f 29 20 26 26 20 53 51 4c  _APPLE__) && SQL
39a0: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 0a 23  ITE_THREADSAFE.#
39b0: 20 20 64 65 66 69 6e 65 20 5f 58 4f 50 45 4e 5f    define _XOPEN_
39c0: 53 4f 55 52 43 45 20 35 30 30 20 20 2f 2a 20 4e  SOURCE 500  /* N
39d0: 65 65 64 65 64 20 74 6f 20 65 6e 61 62 6c 65 20  eeded to enable 
39e0: 70 74 68 72 65 61 64 20 72 65 63 75 72 73 69 76  pthread recursiv
39f0: 65 20 6d 75 74 65 78 65 73 20 2a 2f 0a 23 65 6e  e mutexes */.#en
3a00: 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 54  dif../*.** The T
3a10: 43 4c 20 68 65 61 64 65 72 73 20 61 72 65 20 6f  CL headers are o
3a20: 6e 6c 79 20 6e 65 65 64 65 64 20 77 68 65 6e 20  nly needed when 
3a30: 63 6f 6d 70 69 6c 69 6e 67 20 74 68 65 20 54 43  compiling the TC
3a40: 4c 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2f 0a 23  L bindings..*/.#
3a50: 69 66 20 64 65 66 69 6e 65 64 28 53 51 4c 49 54  if defined(SQLIT
3a60: 45 5f 54 43 4c 29 20 7c 7c 20 64 65 66 69 6e 65  E_TCL) || define
3a70: 64 28 54 43 4c 53 48 29 0a 23 20 69 6e 63 6c 75  d(TCLSH).# inclu
3a80: 64 65 20 3c 74 63 6c 2e 68 3e 0a 23 65 6e 64 69  de <tcl.h>.#endi
3a90: 66 0a 0a 2f 2a 0a 2a 2a 20 4d 61 6e 79 20 70 65  f../*.** Many pe
3aa0: 6f 70 6c 65 20 61 72 65 20 66 61 69 6c 69 6e 67  ople are failing
3ab0: 20 74 6f 20 73 65 74 20 2d 44 4e 44 45 42 55 47   to set -DNDEBUG
3ac0: 3d 31 20 77 68 65 6e 20 63 6f 6d 70 69 6c 69 6e  =1 when compilin
3ad0: 67 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 53 65 74  g SQLite..** Set
3ae0: 74 69 6e 67 20 4e 44 45 42 55 47 20 6d 61 6b 65  ting NDEBUG make
3af0: 73 20 74 68 65 20 63 6f 64 65 20 73 6d 61 6c 6c  s the code small
3b00: 65 72 20 61 6e 64 20 72 75 6e 20 66 61 73 74 65  er and run faste
3b10: 72 2e 20 20 53 6f 20 74 68 65 20 66 6f 6c 6c 6f  r.  So the follo
3b20: 77 69 6e 67 0a 2a 2a 20 6c 69 6e 65 73 20 61 72  wing.** lines ar
3b30: 65 20 61 64 64 65 64 20 74 6f 20 61 75 74 6f 6d  e added to autom
3b40: 61 74 69 63 61 6c 6c 79 20 73 65 74 20 4e 44 45  atically set NDE
3b50: 42 55 47 20 75 6e 6c 65 73 73 20 74 68 65 20 2d  BUG unless the -
3b60: 44 53 51 4c 49 54 45 5f 44 45 42 55 47 3d 31 0a  DSQLITE_DEBUG=1.
3b70: 2a 2a 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74  ** option is set
3b80: 2e 20 20 54 68 75 73 20 4e 44 45 42 55 47 20 62  .  Thus NDEBUG b
3b90: 65 63 6f 6d 65 73 20 61 6e 20 6f 70 74 2d 69 6e  ecomes an opt-in
3ba0: 20 72 61 74 68 65 72 20 74 68 61 6e 20 61 6e 20   rather than an 
3bb0: 6f 70 74 2d 6f 75 74 0a 2a 2a 20 66 65 61 74 75  opt-out.** featu
3bc0: 72 65 2e 0a 2a 2f 0a 23 69 66 20 21 64 65 66 69  re..*/.#if !defi
3bd0: 6e 65 64 28 4e 44 45 42 55 47 29 20 26 26 20 21  ned(NDEBUG) && !
3be0: 64 65 66 69 6e 65 64 28 53 51 4c 49 54 45 5f 44  defined(SQLITE_D
3bf0: 45 42 55 47 29 20 0a 23 20 64 65 66 69 6e 65 20  EBUG) .# define 
3c00: 4e 44 45 42 55 47 20 31 0a 23 65 6e 64 69 66 0a  NDEBUG 1.#endif.
3c10: 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74 65 73 74 63  ./*.** The testc
3c20: 61 73 65 28 29 20 6d 61 63 72 6f 20 69 73 20 75  ase() macro is u
3c30: 73 65 64 20 74 6f 20 61 69 64 20 69 6e 20 63 6f  sed to aid in co
3c40: 76 65 72 61 67 65 20 74 65 73 74 69 6e 67 2e 20  verage testing. 
3c50: 20 57 68 65 6e 20 0a 2a 2a 20 64 6f 69 6e 67 20   When .** doing 
3c60: 63 6f 76 65 72 61 67 65 20 74 65 73 74 69 6e 67  coverage testing
3c70: 2c 20 74 68 65 20 63 6f 6e 64 69 74 69 6f 6e 20  , the condition 
3c80: 69 6e 73 69 64 65 20 74 68 65 20 61 72 67 75 6d  inside the argum
3c90: 65 6e 74 20 74 6f 0a 2a 2a 20 74 65 73 74 63 61  ent to.** testca
3ca0: 73 65 28 29 20 6d 75 73 74 20 62 65 20 65 76 61  se() must be eva
3cb0: 6c 75 61 74 65 64 20 62 6f 74 68 20 74 72 75 65  luated both true
3cc0: 20 61 6e 64 20 66 61 6c 73 65 20 69 6e 20 6f 72   and false in or
3cd0: 64 65 72 20 74 6f 0a 2a 2a 20 67 65 74 20 66 75  der to.** get fu
3ce0: 6c 6c 20 62 72 61 6e 63 68 20 63 6f 76 65 72 61  ll branch covera
3cf0: 67 65 2e 20 20 54 68 65 20 74 65 73 74 63 61 73  ge.  The testcas
3d00: 65 28 29 20 6d 61 63 72 6f 20 69 73 20 69 6e 73  e() macro is ins
3d10: 65 72 74 65 64 0a 2a 2a 20 74 6f 20 68 65 6c 70  erted.** to help
3d20: 20 65 6e 73 75 72 65 20 61 64 65 71 75 61 74 65   ensure adequate
3d30: 20 74 65 73 74 20 63 6f 76 65 72 61 67 65 20 69   test coverage i
3d40: 6e 20 70 6c 61 63 65 73 20 77 68 65 72 65 20 73  n places where s
3d50: 69 6d 70 6c 65 0a 2a 2a 20 63 6f 6e 64 69 74 69  imple.** conditi
3d60: 6f 6e 2f 64 65 63 69 73 69 6f 6e 20 63 6f 76 65  on/decision cove
3d70: 72 61 67 65 20 69 73 20 69 6e 61 64 65 71 75 61  rage is inadequa
3d80: 74 65 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65  te.  For example
3d90: 2c 20 74 65 73 74 63 61 73 65 28 29 0a 2a 2a 20  , testcase().** 
3da0: 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6d  can be used to m
3db0: 61 6b 65 20 73 75 72 65 20 62 6f 75 6e 64 61 72  ake sure boundar
3dc0: 79 20 76 61 6c 75 65 73 20 61 72 65 20 74 65 73  y values are tes
3dd0: 74 65 64 2e 20 20 46 6f 72 0a 2a 2a 20 62 69 74  ted.  For.** bit
3de0: 6d 61 73 6b 20 74 65 73 74 73 2c 20 74 65 73 74  mask tests, test
3df0: 63 61 73 65 28 29 20 63 61 6e 20 62 65 20 75 73  case() can be us
3e00: 65 64 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20  ed to make sure 
3e10: 65 61 63 68 20 62 69 74 0a 2a 2a 20 69 73 20 73  each bit.** is s
3e20: 69 67 6e 69 66 69 63 61 6e 74 20 61 6e 64 20 75  ignificant and u
3e30: 73 65 64 20 61 74 20 6c 65 61 73 74 20 6f 6e 63  sed at least onc
3e40: 65 2e 20 20 4f 6e 20 73 77 69 74 63 68 20 73 74  e.  On switch st
3e50: 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 77 68 65 72  atements.** wher
3e60: 65 20 6d 75 6c 74 69 70 6c 65 20 63 61 73 65 73  e multiple cases
3e70: 20 67 6f 20 74 6f 20 74 68 65 20 73 61 6d 65 20   go to the same 
3e80: 62 6c 6f 63 6b 20 6f 66 20 63 6f 64 65 2c 20 74  block of code, t
3e90: 65 73 74 63 61 73 65 28 29 0a 2a 2a 20 63 61 6e  estcase().** can
3ea0: 20 69 6e 73 75 72 65 20 74 68 61 74 20 61 6c 6c   insure that all
3eb0: 20 63 61 73 65 73 20 61 72 65 20 65 76 61 6c 75   cases are evalu
3ec0: 61 74 65 64 2e 0a 2a 2a 0a 2a 2f 0a 23 69 66 64  ated..**.*/.#ifd
3ed0: 65 66 20 53 51 4c 49 54 45 5f 43 4f 56 45 52 41  ef SQLITE_COVERA
3ee0: 47 45 5f 54 45 53 54 0a 53 51 4c 49 54 45 5f 50  GE_TEST.SQLITE_P
3ef0: 52 49 56 41 54 45 20 20 20 76 6f 69 64 20 73 71  RIVATE   void sq
3f00: 6c 69 74 65 33 43 6f 76 65 72 61 67 65 28 69 6e  lite3Coverage(in
3f10: 74 29 3b 0a 23 20 64 65 66 69 6e 65 20 74 65 73  t);.# define tes
3f20: 74 63 61 73 65 28 58 29 20 20 69 66 28 20 58 20  tcase(X)  if( X 
3f30: 29 7b 20 73 71 6c 69 74 65 33 43 6f 76 65 72 61  ){ sqlite3Covera
3f40: 67 65 28 5f 5f 4c 49 4e 45 5f 5f 29 3b 20 7d 0a  ge(__LINE__); }.
3f50: 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65 20 74  #else.# define t
3f60: 65 73 74 63 61 73 65 28 58 29 0a 23 65 6e 64 69  estcase(X).#endi
3f70: 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 54 45 53  f../*.** The TES
3f80: 54 4f 4e 4c 59 20 6d 61 63 72 6f 20 69 73 20 75  TONLY macro is u
3f90: 73 65 64 20 74 6f 20 65 6e 63 6c 6f 73 65 20 76  sed to enclose v
3fa0: 61 72 69 61 62 6c 65 20 64 65 63 6c 61 72 61 74  ariable declarat
3fb0: 69 6f 6e 73 20 6f 72 0a 2a 2a 20 6f 74 68 65 72  ions or.** other
3fc0: 20 62 69 74 73 20 6f 66 20 63 6f 64 65 20 74 68   bits of code th
3fd0: 61 74 20 61 72 65 20 6e 65 65 64 65 64 20 74 6f  at are needed to
3fe0: 20 73 75 70 70 6f 72 74 20 74 68 65 20 61 72 67   support the arg
3ff0: 75 6d 65 6e 74 73 0a 2a 2a 20 77 69 74 68 69 6e  uments.** within
4000: 20 74 65 73 74 63 61 73 65 28 29 20 61 6e 64 20   testcase() and 
4010: 61 73 73 65 72 74 28 29 20 6d 61 63 72 6f 73 2e  assert() macros.
4020: 0a 2a 2f 0a 23 69 66 20 21 64 65 66 69 6e 65 64  .*/.#if !defined
4030: 28 4e 44 45 42 55 47 29 20 7c 7c 20 64 65 66 69  (NDEBUG) || defi
4040: 6e 65 64 28 53 51 4c 49 54 45 5f 43 4f 56 45 52  ned(SQLITE_COVER
4050: 41 47 45 5f 54 45 53 54 29 0a 23 20 64 65 66 69  AGE_TEST).# defi
4060: 6e 65 20 54 45 53 54 4f 4e 4c 59 28 58 29 20 20  ne TESTONLY(X)  
4070: 58 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65  X.#else.# define
4080: 20 54 45 53 54 4f 4e 4c 59 28 58 29 0a 23 65 6e   TESTONLY(X).#en
4090: 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 53 6f 6d 65 74  dif../*.** Somet
40a0: 69 6d 65 73 20 77 65 20 6e 65 65 64 20 61 20 73  imes we need a s
40b0: 6d 61 6c 6c 20 61 6d 6f 75 6e 74 20 6f 66 20 63  mall amount of c
40c0: 6f 64 65 20 73 75 63 68 20 61 73 20 61 20 76 61  ode such as a va
40d0: 72 69 61 62 6c 65 20 69 6e 69 74 69 61 6c 69 7a  riable initializ
40e0: 61 74 69 6f 6e 0a 2a 2a 20 74 6f 20 73 65 74 75  ation.** to setu
40f0: 70 20 66 6f 72 20 61 20 6c 61 74 65 72 20 61 73  p for a later as
4100: 73 65 72 74 28 29 20 73 74 61 74 65 6d 65 6e 74  sert() statement
4110: 2e 20 20 57 65 20 64 6f 20 6e 6f 74 20 77 61 6e  .  We do not wan
4120: 74 20 74 68 69 73 20 63 6f 64 65 20 74 6f 0a 2a  t this code to.*
4130: 2a 20 61 70 70 65 61 72 20 77 68 65 6e 20 61 73  * appear when as
4140: 73 65 72 74 28 29 20 69 73 20 64 69 73 61 62 6c  sert() is disabl
4150: 65 64 2e 20 20 54 68 65 20 66 6f 6c 6c 6f 77 69  ed.  The followi
4160: 6e 67 20 6d 61 63 72 6f 20 69 73 20 74 68 65 72  ng macro is ther
4170: 65 66 6f 72 65 0a 2a 2a 20 75 73 65 64 20 74 6f  efore.** used to
4180: 20 63 6f 6e 74 61 69 6e 20 74 68 61 74 20 73 65   contain that se
4190: 74 75 70 20 63 6f 64 65 2e 20 20 54 68 65 20 22  tup code.  The "
41a0: 56 56 41 22 20 61 63 72 6f 6e 79 6d 20 73 74 61  VVA" acronym sta
41b0: 6e 64 73 20 66 6f 72 0a 2a 2a 20 22 56 65 72 69  nds for.** "Veri
41c0: 66 69 63 61 74 69 6f 6e 2c 20 56 61 6c 69 64 61  fication, Valida
41d0: 74 69 6f 6e 2c 20 61 6e 64 20 41 63 63 72 65 64  tion, and Accred
41e0: 69 74 61 74 69 6f 6e 22 2e 20 20 49 6e 20 6f 74  itation".  In ot
41f0: 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 0a 2a  her words, the.*
4200: 2a 20 63 6f 64 65 20 77 69 74 68 69 6e 20 56 56  * code within VV
4210: 41 5f 4f 4e 4c 59 28 29 20 77 69 6c 6c 20 6f 6e  A_ONLY() will on
4220: 6c 79 20 72 75 6e 20 64 75 72 69 6e 67 20 76 65  ly run during ve
4230: 72 69 66 69 63 61 74 69 6f 6e 20 70 72 6f 63 65  rification proce
4240: 73 73 65 73 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66  sses..*/.#ifndef
4250: 20 4e 44 45 42 55 47 0a 23 20 64 65 66 69 6e 65   NDEBUG.# define
4260: 20 56 56 41 5f 4f 4e 4c 59 28 58 29 20 20 58 0a   VVA_ONLY(X)  X.
4270: 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65 20 56  #else.# define V
4280: 56 41 5f 4f 4e 4c 59 28 58 29 0a 23 65 6e 64 69  VA_ONLY(X).#endi
4290: 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 41 4c 57  f../*.** The ALW
42a0: 41 59 53 20 61 6e 64 20 4e 45 56 45 52 20 6d 61  AYS and NEVER ma
42b0: 63 72 6f 73 20 73 75 72 72 6f 75 6e 64 20 62 6f  cros surround bo
42c0: 6f 6c 65 61 6e 20 65 78 70 72 65 73 73 69 6f 6e  olean expression
42d0: 73 20 77 68 69 63 68 20 0a 2a 2a 20 61 72 65 20  s which .** are 
42e0: 69 6e 74 65 6e 64 65 64 20 74 6f 20 61 6c 77 61  intended to alwa
42f0: 79 73 20 62 65 20 74 72 75 65 20 6f 72 20 66 61  ys be true or fa
4300: 6c 73 65 2c 20 72 65 73 70 65 63 74 69 76 65 6c  lse, respectivel
4310: 79 2e 20 20 53 75 63 68 0a 2a 2a 20 65 78 70 72  y.  Such.** expr
4320: 65 73 73 69 6f 6e 73 20 63 6f 75 6c 64 20 62 65  essions could be
4330: 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68   omitted from th
4340: 65 20 63 6f 64 65 20 63 6f 6d 70 6c 65 74 65 6c  e code completel
4350: 79 2e 20 20 42 75 74 20 74 68 65 79 0a 2a 2a 20  y.  But they.** 
4360: 61 72 65 20 69 6e 63 6c 75 64 65 64 20 69 6e 20  are included in 
4370: 61 20 66 65 77 20 63 61 73 65 73 20 69 6e 20 6f  a few cases in o
4380: 72 64 65 72 20 74 6f 20 65 6e 68 61 6e 63 65 20  rder to enhance 
4390: 74 68 65 20 72 65 73 69 6c 69 65 6e 63 65 0a 2a  the resilience.*
43a0: 2a 20 6f 66 20 53 51 4c 69 74 65 20 74 6f 20 75  * of SQLite to u
43b0: 6e 65 78 70 65 63 74 65 64 20 62 65 68 61 76 69  nexpected behavi
43c0: 6f 72 20 2d 20 74 6f 20 6d 61 6b 65 20 74 68 65  or - to make the
43d0: 20 63 6f 64 65 20 22 73 65 6c 66 2d 68 65 61 6c   code "self-heal
43e0: 69 6e 67 22 0a 2a 2a 20 6f 72 20 22 64 75 63 74  ing".** or "duct
43f0: 69 6c 65 22 20 72 61 74 68 65 72 20 74 68 61 6e  ile" rather than
4400: 20 62 65 69 6e 67 20 22 62 72 69 74 74 6c 65 22   being "brittle"
4410: 20 61 6e 64 20 63 72 61 73 68 69 6e 67 20 61 74   and crashing at
4420: 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 68 69   the first.** hi
4430: 6e 74 20 6f 66 20 75 6e 70 6c 61 6e 6e 65 64 20  nt of unplanned 
4440: 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20  behavior..**.** 
4450: 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
4460: 41 4c 57 41 59 53 20 61 6e 64 20 4e 45 56 45 52  ALWAYS and NEVER
4470: 20 61 72 65 20 61 64 64 65 64 20 66 6f 72 20 64   are added for d
4480: 65 66 65 6e 73 69 76 65 20 63 6f 64 65 2e 0a 2a  efensive code..*
4490: 2a 0a 2a 2a 20 57 68 65 6e 20 64 6f 69 6e 67 20  *.** When doing 
44a0: 63 6f 76 65 72 61 67 65 20 74 65 73 74 69 6e 67  coverage testing
44b0: 20 41 4c 57 41 59 53 20 61 6e 64 20 4e 45 56 45   ALWAYS and NEVE
44c0: 52 20 61 72 65 20 68 61 72 64 2d 63 6f 64 65 64  R are hard-coded
44d0: 20 74 6f 0a 2a 2a 20 62 65 20 74 72 75 65 20 61   to.** be true a
44e0: 6e 64 20 66 61 6c 73 65 20 73 6f 20 74 68 61 74  nd false so that
44f0: 20 74 68 65 20 75 6e 72 65 61 63 68 61 62 6c 65   the unreachable
4500: 20 63 6f 64 65 20 74 68 65 6e 20 73 70 65 63 69   code then speci
4510: 66 79 20 77 69 6c 6c 0a 2a 2a 20 6e 6f 74 20 62  fy will.** not b
4520: 65 20 63 6f 75 6e 74 65 64 20 61 73 20 75 6e 74  e counted as unt
4530: 65 73 74 65 64 20 63 6f 64 65 2e 0a 2a 2f 0a 23  ested code..*/.#
4540: 69 66 20 64 65 66 69 6e 65 64 28 53 51 4c 49 54  if defined(SQLIT
4550: 45 5f 43 4f 56 45 52 41 47 45 5f 54 45 53 54 29  E_COVERAGE_TEST)
4560: 0a 23 20 64 65 66 69 6e 65 20 41 4c 57 41 59 53  .# define ALWAYS
4570: 28 58 29 20 20 20 20 20 20 28 31 29 0a 23 20 64  (X)      (1).# d
4580: 65 66 69 6e 65 20 4e 45 56 45 52 28 58 29 20 20  efine NEVER(X)  
4590: 20 20 20 20 20 28 30 29 0a 23 65 6c 69 66 20 21       (0).#elif !
45a0: 64 65 66 69 6e 65 64 28 4e 44 45 42 55 47 29 0a  defined(NDEBUG).
45b0: 23 20 64 65 66 69 6e 65 20 41 4c 57 41 59 53 28  # define ALWAYS(
45c0: 58 29 20 20 20 20 20 20 28 28 58 29 3f 31 3a 28  X)      ((X)?1:(
45d0: 61 73 73 65 72 74 28 30 29 2c 30 29 29 0a 23 20  assert(0),0)).# 
45e0: 64 65 66 69 6e 65 20 4e 45 56 45 52 28 58 29 20  define NEVER(X) 
45f0: 20 20 20 20 20 20 28 28 58 29 3f 28 61 73 73 65        ((X)?(asse
4600: 72 74 28 30 29 2c 31 29 3a 30 29 0a 23 65 6c 73  rt(0),1):0).#els
4610: 65 0a 23 20 64 65 66 69 6e 65 20 41 4c 57 41 59  e.# define ALWAY
4620: 53 28 58 29 20 20 20 20 20 20 28 58 29 0a 23 20  S(X)      (X).# 
4630: 64 65 66 69 6e 65 20 4e 45 56 45 52 28 58 29 20  define NEVER(X) 
4640: 20 20 20 20 20 20 28 58 29 0a 23 65 6e 64 69 66        (X).#endif
4650: 0a 0a 2f 2a 0a 2a 2a 20 52 65 74 75 72 6e 20 74  ../*.** Return t
4660: 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69  rue (non-zero) i
4670: 66 20 74 68 65 20 69 6e 70 75 74 20 69 73 20 61  f the input is a
4680: 20 69 6e 74 65 67 65 72 20 74 68 61 74 20 69 73   integer that is
4690: 20 74 6f 6f 20 6c 61 72 67 65 0a 2a 2a 20 74 6f   too large.** to
46a0: 20 66 69 74 20 69 6e 20 33 32 2d 62 69 74 73 2e   fit in 32-bits.
46b0: 20 20 54 68 69 73 20 6d 61 63 72 6f 20 69 73 20    This macro is 
46c0: 75 73 65 64 20 69 6e 73 69 64 65 20 6f 66 20 76  used inside of v
46d0: 61 72 69 6f 75 73 20 74 65 73 74 63 61 73 65 28  arious testcase(
46e0: 29 0a 2a 2a 20 6d 61 63 72 6f 73 20 74 6f 20 76  ).** macros to v
46f0: 65 72 69 66 79 20 74 68 61 74 20 77 65 20 68 61  erify that we ha
4700: 76 65 20 74 65 73 74 65 64 20 53 51 4c 69 74 65  ve tested SQLite
4710: 20 66 6f 72 20 6c 61 72 67 65 2d 66 69 6c 65 20   for large-file 
4720: 73 75 70 70 6f 72 74 2e 0a 2a 2f 0a 23 64 65 66  support..*/.#def
4730: 69 6e 65 20 49 53 5f 42 49 47 5f 49 4e 54 28 58  ine IS_BIG_INT(X
4740: 29 20 20 28 28 28 58 29 26 7e 28 69 36 34 29 30  )  (((X)&~(i64)0
4750: 78 66 66 66 66 66 66 66 66 29 21 3d 30 29 0a 0a  xffffffff)!=0)..
4760: 2f 2a 0a 2a 2a 20 54 68 65 20 6d 61 63 72 6f 20  /*.** The macro 
4770: 75 6e 6c 69 6b 65 6c 79 28 29 20 69 73 20 61 20  unlikely() is a 
4780: 68 69 6e 74 20 74 68 61 74 20 73 75 72 72 6f 75  hint that surrou
4790: 6e 64 73 20 61 20 62 6f 6f 6c 65 61 6e 0a 2a 2a  nds a boolean.**
47a0: 20 65 78 70 72 65 73 73 69 6f 6e 20 74 68 61 74   expression that
47b0: 20 69 73 20 75 73 75 61 6c 6c 79 20 66 61 6c 73   is usually fals
47c0: 65 2e 20 20 4d 61 63 72 6f 20 6c 69 6b 65 6c 79  e.  Macro likely
47d0: 28 29 20 73 75 72 72 6f 75 6e 64 73 0a 2a 2a 20  () surrounds.** 
47e0: 61 20 62 6f 6f 6c 65 61 6e 20 65 78 70 72 65 73  a boolean expres
47f0: 73 69 6f 6e 20 74 68 61 74 20 69 73 20 75 73 75  sion that is usu
4800: 61 6c 6c 79 20 74 72 75 65 2e 20 20 47 43 43 20  ally true.  GCC 
4810: 69 73 20 61 62 6c 65 20 74 6f 0a 2a 2a 20 75 73  is able to.** us
4820: 65 20 74 68 65 73 65 20 68 69 6e 74 73 20 74 6f  e these hints to
4830: 20 67 65 6e 65 72 61 74 65 20 62 65 74 74 65 72   generate better
4840: 20 63 6f 64 65 2c 20 73 6f 6d 65 74 69 6d 65 73   code, sometimes
4850: 2e 0a 2a 2f 0a 23 69 66 20 64 65 66 69 6e 65 64  ..*/.#if defined
4860: 28 5f 5f 47 4e 55 43 5f 5f 29 20 26 26 20 30 0a  (__GNUC__) && 0.
4870: 23 20 64 65 66 69 6e 65 20 6c 69 6b 65 6c 79 28  # define likely(
4880: 58 29 20 20 20 20 5f 5f 62 75 69 6c 74 69 6e 5f  X)    __builtin_
4890: 65 78 70 65 63 74 28 28 58 29 2c 31 29 0a 23 20  expect((X),1).# 
48a0: 64 65 66 69 6e 65 20 75 6e 6c 69 6b 65 6c 79 28  define unlikely(
48b0: 58 29 20 20 5f 5f 62 75 69 6c 74 69 6e 5f 65 78  X)  __builtin_ex
48c0: 70 65 63 74 28 28 58 29 2c 30 29 0a 23 65 6c 73  pect((X),0).#els
48d0: 65 0a 23 20 64 65 66 69 6e 65 20 6c 69 6b 65 6c  e.# define likel
48e0: 79 28 58 29 20 20 20 20 21 21 28 58 29 0a 23 20  y(X)    !!(X).# 
48f0: 64 65 66 69 6e 65 20 75 6e 6c 69 6b 65 6c 79 28  define unlikely(
4900: 58 29 20 20 21 21 28 58 29 0a 23 65 6e 64 69 66  X)  !!(X).#endif
4910: 0a 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ../*************
4920: 2a 20 49 6e 63 6c 75 64 65 20 73 71 6c 69 74 65  * Include sqlite
4930: 33 2e 68 20 69 6e 20 74 68 65 20 6d 69 64 64 6c  3.h in the middl
4940: 65 20 6f 66 20 73 71 6c 69 74 65 49 6e 74 2e 68  e of sqliteInt.h
4950: 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a   ***************
4960: 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  /./*************
4970: 2a 20 42 65 67 69 6e 20 66 69 6c 65 20 73 71 6c  * Begin file sql
4980: 69 74 65 33 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a  ite3.h *********
4990: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
49a0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
49b0: 2f 0a 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70  /./*.** 2001 Sep
49c0: 74 65 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20  tember 15.**.** 
49d0: 54 68 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c  The author discl
49e0: 61 69 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74  aims copyright t
49f0: 6f 20 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f  o this source co
4a00: 64 65 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66  de.  In place of
4a10: 0a 2a 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69  .** a legal noti
4a20: 63 65 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c  ce, here is a bl
4a30: 65 73 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20  essing:.**.**   
4a40: 20 4d 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64   May you do good
4a50: 20 61 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a   and not evil..*
4a60: 2a 20 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e  *    May you fin
4a70: 64 20 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f  d forgiveness fo
4a80: 72 20 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66  r yourself and f
4a90: 6f 72 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a  orgive others..*
4aa0: 2a 20 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61  *    May you sha
4ab0: 72 65 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72  re freely, never
4ac0: 20 74 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61   taking more tha
4ad0: 6e 20 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a  n you give..**.*
4ae0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
4af0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
4b00: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
4b10: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
4b20: 2a 2a 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73  ********.** This
4b30: 20 68 65 61 64 65 72 20 66 69 6c 65 20 64 65 66   header file def
4b40: 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66 61  ines the interfa
4b50: 63 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 69  ce that the SQLi
4b60: 74 65 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72  te library.** pr
4b70: 65 73 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74  esents to client
4b80: 20 70 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61   programs.  If a
4b90: 20 43 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72   C-function, str
4ba0: 75 63 74 75 72 65 2c 20 64 61 74 61 74 79 70 65  ucture, datatype
4bb0: 2c 0a 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74  ,.** or constant
4bc0: 20 64 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73   definition does
4bd0: 20 6e 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74   not appear in t
4be0: 68 69 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69  his file, then i
4bf0: 74 20 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75  t is.** not a pu
4c00: 62 6c 69 73 68 65 64 20 41 50 49 20 6f 66 20 53  blished API of S
4c10: 51 4c 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63  QLite, is subjec
4c20: 74 20 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68  t to change with
4c30: 6f 75 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61  out.** notice, a
4c40: 6e 64 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65  nd should not be
4c50: 20 72 65 66 65 72 65 6e 63 65 64 20 62 79 20 70   referenced by p
4c60: 72 6f 67 72 61 6d 73 20 74 68 61 74 20 75 73 65  rograms that use
4c70: 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53   SQLite..**.** S
4c80: 6f 6d 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e  ome of the defin
4c90: 69 74 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20  itions that are 
4ca0: 69 6e 20 74 68 69 73 20 66 69 6c 65 20 61 72 65  in this file are
4cb0: 20 6d 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65   marked as.** "e
4cc0: 78 70 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45  xperimental".  E
4cd0: 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65  xperimental inte
4ce0: 72 66 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61  rfaces are norma
4cf0: 6c 6c 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75  lly new.** featu
4d00: 72 65 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64  res recently add
4d10: 65 64 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57  ed to SQLite.  W
4d20: 65 20 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70  e do not anticip
4d30: 61 74 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74  ate changes.** t
4d40: 6f 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69  o experimental i
4d50: 6e 74 65 72 66 61 63 65 73 20 62 75 74 20 72 65  nterfaces but re
4d60: 73 65 72 76 65 20 74 68 65 20 72 69 67 68 74 20  serve the right 
4d70: 74 6f 20 6d 61 6b 65 20 6d 69 6e 6f 72 20 63 68  to make minor ch
4d80: 61 6e 67 65 73 0a 2a 2a 20 69 66 20 65 78 70 65  anges.** if expe
4d90: 72 69 65 6e 63 65 20 66 72 6f 6d 20 75 73 65 20  rience from use 
4da0: 22 69 6e 20 74 68 65 20 77 69 6c 64 22 20 73 75  "in the wild" su
4db0: 67 67 65 73 74 20 73 75 63 68 20 63 68 61 6e 67  ggest such chang
4dc0: 65 73 20 61 72 65 20 70 72 75 64 65 6e 74 2e 0a  es are prudent..
4dd0: 2a 2a 0a 2a 2a 20 54 68 65 20 6f 66 66 69 63 69  **.** The offici
4de0: 61 6c 20 43 2d 6c 61 6e 67 75 61 67 65 20 41 50  al C-language AP
4df0: 49 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20  I documentation 
4e00: 66 6f 72 20 53 51 4c 69 74 65 20 69 73 20 64 65  for SQLite is de
4e10: 72 69 76 65 64 0a 2a 2a 20 66 72 6f 6d 20 63 6f  rived.** from co
4e20: 6d 6d 65 6e 74 73 20 69 6e 20 74 68 69 73 20 66  mments in this f
4e30: 69 6c 65 2e 20 20 54 68 69 73 20 66 69 6c 65 20  ile.  This file 
4e40: 69 73 20 74 68 65 20 61 75 74 68 6f 72 69 74 61  is the authorita
4e50: 74 69 76 65 20 73 6f 75 72 63 65 0a 2a 2a 20 6f  tive source.** o
4e60: 6e 20 68 6f 77 20 53 51 4c 69 74 65 20 69 6e 74  n how SQLite int
4e70: 65 72 66 61 63 65 73 20 61 72 65 20 73 75 70 70  erfaces are supp
4e80: 6f 73 65 20 74 6f 20 6f 70 65 72 61 74 65 2e 0a  ose to operate..
4e90: 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f  **.** The name o
4ea0: 66 20 74 68 69 73 20 66 69 6c 65 20 75 6e 64 65  f this file unde
4eb0: 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  r configuration 
4ec0: 6d 61 6e 61 67 65 6d 65 6e 74 20 69 73 20 22 73  management is "s
4ed0: 71 6c 69 74 65 2e 68 2e 69 6e 22 2e 0a 2a 2a 20  qlite.h.in"..** 
4ee0: 54 68 65 20 6d 61 6b 65 66 69 6c 65 20 6d 61 6b  The makefile mak
4ef0: 65 73 20 73 6f 6d 65 20 6d 69 6e 6f 72 20 63 68  es some minor ch
4f00: 61 6e 67 65 73 20 74 6f 20 74 68 69 73 20 66 69  anges to this fi
4f10: 6c 65 20 28 73 75 63 68 20 61 73 20 69 6e 73 65  le (such as inse
4f20: 72 74 69 6e 67 0a 2a 2a 20 74 68 65 20 76 65 72  rting.** the ver
4f30: 73 69 6f 6e 20 6e 75 6d 62 65 72 29 20 61 6e 64  sion number) and
4f40: 20 63 68 61 6e 67 65 73 20 69 74 73 20 6e 61 6d   changes its nam
4f50: 65 20 74 6f 20 22 73 71 6c 69 74 65 33 2e 68 22  e to "sqlite3.h"
4f60: 20 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74   as.** part of t
4f70: 68 65 20 62 75 69 6c 64 20 70 72 6f 63 65 73 73  he build process
4f80: 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53 51  ..*/.#ifndef _SQ
4f90: 4c 49 54 45 33 5f 48 5f 0a 23 64 65 66 69 6e 65  LITE3_H_.#define
4fa0: 20 5f 53 51 4c 49 54 45 33 5f 48 5f 0a 23 69 6e   _SQLITE3_H_.#in
4fb0: 63 6c 75 64 65 20 3c 73 74 64 61 72 67 2e 68 3e  clude <stdarg.h>
4fc0: 20 20 20 20 20 2f 2a 20 4e 65 65 64 65 64 20 66       /* Needed f
4fd0: 6f 72 20 74 68 65 20 64 65 66 69 6e 69 74 69 6f  or the definitio
4fe0: 6e 20 6f 66 20 76 61 5f 6c 69 73 74 20 2a 2f 0a  n of va_list */.
4ff0: 0a 2f 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75 72 65  ./*.** Make sure
5000: 20 77 65 20 63 61 6e 20 63 61 6c 6c 20 74 68 69   we can call thi
5010: 73 20 73 74 75 66 66 20 66 72 6f 6d 20 43 2b 2b  s stuff from C++
5020: 2e 0a 2a 2f 0a 23 69 66 20 30 0a 65 78 74 65 72  ..*/.#if 0.exter
5030: 6e 20 22 43 22 20 7b 0a 23 65 6e 64 69 66 0a 0a  n "C" {.#endif..
5040: 0a 2f 2a 0a 2a 2a 20 41 64 64 20 74 68 65 20 61  ./*.** Add the a
5050: 62 69 6c 69 74 79 20 74 6f 20 6f 76 65 72 72 69  bility to overri
5060: 64 65 20 27 65 78 74 65 72 6e 27 0a 2a 2f 0a 23  de 'extern'.*/.#
5070: 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 45 58  ifndef SQLITE_EX
5080: 54 45 52 4e 0a 23 20 64 65 66 69 6e 65 20 53 51  TERN.# define SQ
5090: 4c 49 54 45 5f 45 58 54 45 52 4e 20 65 78 74 65  LITE_EXTERN exte
50a0: 72 6e 0a 23 65 6e 64 69 66 0a 0a 23 69 66 6e 64  rn.#endif..#ifnd
50b0: 65 66 20 53 51 4c 49 54 45 5f 41 50 49 0a 23 20  ef SQLITE_API.# 
50c0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 50  define SQLITE_AP
50d0: 49 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a 2a  I.#endif.../*.**
50e0: 20 54 68 65 73 65 20 6e 6f 2d 6f 70 20 6d 61 63   These no-op mac
50f0: 72 6f 73 20 61 72 65 20 75 73 65 64 20 69 6e 20  ros are used in 
5100: 66 72 6f 6e 74 20 6f 66 20 69 6e 74 65 72 66 61  front of interfa
5110: 63 65 73 20 74 6f 20 6d 61 72 6b 20 74 68 6f 73  ces to mark thos
5120: 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  e.** interfaces 
5130: 61 73 20 65 69 74 68 65 72 20 64 65 70 72 65 63  as either deprec
5140: 61 74 65 64 20 6f 72 20 65 78 70 65 72 69 6d 65  ated or experime
5150: 6e 74 61 6c 2e 20 20 4e 65 77 20 61 70 70 6c 69  ntal.  New appli
5160: 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c  cations.** shoul
5170: 64 20 6e 6f 74 20 75 73 65 20 64 65 70 72 65 63  d not use deprec
5180: 61 74 65 64 20 69 6e 74 65 72 66 61 63 65 73 20  ated interfaces 
5190: 2d 20 74 68 65 79 20 61 72 65 20 73 75 70 70 6f  - they are suppo
51a0: 72 74 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73  rt for backwards
51b0: 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  .** compatibilit
51c0: 79 20 6f 6e 6c 79 2e 20 20 41 70 70 6c 69 63 61  y only.  Applica
51d0: 74 69 6f 6e 20 77 72 69 74 65 72 73 20 73 68 6f  tion writers sho
51e0: 75 6c 64 20 62 65 20 61 77 61 72 65 20 74 68 61  uld be aware tha
51f0: 74 0a 2a 2a 20 65 78 70 65 72 69 6d 65 6e 74 61  t.** experimenta
5200: 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  l interfaces are
5210: 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e   subject to chan
5220: 67 65 20 69 6e 20 70 6f 69 6e 74 20 72 65 6c 65  ge in point rele
5230: 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ases..**.** Thes
5240: 65 20 6d 61 63 72 6f 73 20 75 73 65 64 20 74 6f  e macros used to
5250: 20 72 65 73 6f 6c 76 65 20 74 6f 20 76 61 72 69   resolve to vari
5260: 6f 75 73 20 6b 69 6e 64 73 20 6f 66 20 63 6f 6d  ous kinds of com
5270: 70 69 6c 65 72 20 6d 61 67 69 63 20 74 68 61 74  piler magic that
5280: 0a 2a 2a 20 77 6f 75 6c 64 20 67 65 6e 65 72 61  .** would genera
5290: 74 65 20 77 61 72 6e 69 6e 67 20 6d 65 73 73 61  te warning messa
52a0: 67 65 73 20 77 68 65 6e 20 74 68 65 79 20 77 65  ges when they we
52b0: 72 65 20 75 73 65 64 2e 20 20 42 75 74 20 74 68  re used.  But th
52c0: 61 74 0a 2a 2a 20 63 6f 6d 70 69 6c 65 72 20 6d  at.** compiler m
52d0: 61 67 69 63 20 65 6e 64 65 64 20 75 70 20 67 65  agic ended up ge
52e0: 6e 65 72 61 74 69 6e 67 20 73 75 63 68 20 61 20  nerating such a 
52f0: 66 6c 75 72 72 79 20 6f 66 20 62 75 67 20 72 65  flurry of bug re
5300: 70 6f 72 74 73 0a 2a 2a 20 74 68 61 74 20 77 65  ports.** that we
5310: 20 68 61 76 65 20 74 61 6b 65 6e 20 69 74 20 61   have taken it a
5320: 6c 6c 20 6f 75 74 20 61 6e 64 20 67 6f 6e 65 20  ll out and gone 
5330: 62 61 63 6b 20 74 6f 20 75 73 69 6e 67 20 73 69  back to using si
5340: 6d 70 6c 65 0a 2a 2a 20 6e 6f 6f 70 20 6d 61 63  mple.** noop mac
5350: 72 6f 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ros..*/.#define 
5360: 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
5370: 44 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  D.#define SQLITE
5380: 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 0a 2f  _EXPERIMENTAL../
5390: 2a 0a 2a 2a 20 45 6e 73 75 72 65 20 74 68 65 73  *.** Ensure thes
53a0: 65 20 73 79 6d 62 6f 6c 73 20 77 65 72 65 20 6e  e symbols were n
53b0: 6f 74 20 64 65 66 69 6e 65 64 20 62 79 20 73 6f  ot defined by so
53c0: 6d 65 20 70 72 65 76 69 6f 75 73 20 68 65 61 64  me previous head
53d0: 65 72 20 66 69 6c 65 2e 0a 2a 2f 0a 23 69 66 64  er file..*/.#ifd
53e0: 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  ef SQLITE_VERSIO
53f0: 4e 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45  N.# undef SQLITE
5400: 5f 56 45 52 53 49 4f 4e 0a 23 65 6e 64 69 66 0a  _VERSION.#endif.
5410: 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 56 45  #ifdef SQLITE_VE
5420: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23 20 75  RSION_NUMBER.# u
5430: 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53  ndef SQLITE_VERS
5440: 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23 65 6e 64 69  ION_NUMBER.#endi
5450: 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  f../*.** CAPI3RE
5460: 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20  F: Compile-Time 
5470: 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f 6e 20  Library Version 
5480: 4e 75 6d 62 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 28  Numbers.**.** ^(
5490: 54 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  The [SQLITE_VERS
54a0: 49 4f 4e 5d 20 43 20 70 72 65 70 72 6f 63 65 73  ION] C preproces
54b0: 73 6f 72 20 6d 61 63 72 6f 20 69 6e 20 74 68 65  sor macro in the
54c0: 20 73 71 6c 69 74 65 33 2e 68 20 68 65 61 64 65   sqlite3.h heade
54d0: 72 0a 2a 2a 20 65 76 61 6c 75 61 74 65 73 20 74  r.** evaluates t
54e0: 6f 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72  o a string liter
54f0: 61 6c 20 74 68 61 74 20 69 73 20 74 68 65 20 53  al that is the S
5500: 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 69 6e  QLite version in
5510: 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 61 74 20 22   the.** format "
5520: 58 2e 59 2e 5a 22 20 77 68 65 72 65 20 58 20 69  X.Y.Z" where X i
5530: 73 20 74 68 65 20 6d 61 6a 6f 72 20 76 65 72 73  s the major vers
5540: 69 6f 6e 20 6e 75 6d 62 65 72 20 28 61 6c 77 61  ion number (alwa
5550: 79 73 20 33 20 66 6f 72 0a 2a 2a 20 53 51 4c 69  ys 3 for.** SQLi
5560: 74 65 33 29 20 61 6e 64 20 59 20 69 73 20 74 68  te3) and Y is th
5570: 65 20 6d 69 6e 6f 72 20 76 65 72 73 69 6f 6e 20  e minor version 
5580: 6e 75 6d 62 65 72 20 61 6e 64 20 5a 20 69 73 20  number and Z is 
5590: 74 68 65 20 72 65 6c 65 61 73 65 20 6e 75 6d 62  the release numb
55a0: 65 72 2e 29 5e 0a 2a 2a 20 5e 28 54 68 65 20 5b  er.)^.** ^(The [
55b0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
55c0: 55 4d 42 45 52 5d 20 43 20 70 72 65 70 72 6f 63  UMBER] C preproc
55d0: 65 73 73 6f 72 20 6d 61 63 72 6f 20 72 65 73 6f  essor macro reso
55e0: 6c 76 65 73 20 74 6f 20 61 6e 20 69 6e 74 65 67  lves to an integ
55f0: 65 72 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 76  er.** with the v
5600: 61 6c 75 65 20 28 58 2a 31 30 30 30 30 30 30 20  alue (X*1000000 
5610: 2b 20 59 2a 31 30 30 30 20 2b 20 5a 29 20 77 68  + Y*1000 + Z) wh
5620: 65 72 65 20 58 2c 20 59 2c 20 61 6e 64 20 5a 20  ere X, Y, and Z 
5630: 61 72 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20  are the same.** 
5640: 6e 75 6d 62 65 72 73 20 75 73 65 64 20 69 6e 20  numbers used in 
5650: 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d  [SQLITE_VERSION]
5660: 2e 29 5e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54  .)^.** The SQLIT
5670: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
5680: 20 66 6f 72 20 61 6e 79 20 67 69 76 65 6e 20 72   for any given r
5690: 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65  elease of SQLite
56a0: 20 77 69 6c 6c 20 61 6c 73 6f 0a 2a 2a 20 62 65   will also.** be
56b0: 20 6c 61 72 67 65 72 20 74 68 61 6e 20 74 68 65   larger than the
56c0: 20 72 65 6c 65 61 73 65 20 66 72 6f 6d 20 77 68   release from wh
56d0: 69 63 68 20 69 74 20 69 73 20 64 65 72 69 76 65  ich it is derive
56e0: 64 2e 20 20 45 69 74 68 65 72 20 59 20 77 69 6c  d.  Either Y wil
56f0: 6c 0a 2a 2a 20 62 65 20 68 65 6c 64 20 63 6f 6e  l.** be held con
5700: 73 74 61 6e 74 20 61 6e 64 20 5a 20 77 69 6c 6c  stant and Z will
5710: 20 62 65 20 69 6e 63 72 65 6d 65 6e 74 65 64 20   be incremented 
5720: 6f 72 20 65 6c 73 65 20 59 20 77 69 6c 6c 20 62  or else Y will b
5730: 65 20 69 6e 63 72 65 6d 65 6e 74 65 64 0a 2a 2a  e incremented.**
5740: 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65 20 72   and Z will be r
5750: 65 73 65 74 20 74 6f 20 7a 65 72 6f 2e 0a 2a 2a  eset to zero..**
5760: 0a 2a 2a 20 53 69 6e 63 65 20 76 65 72 73 69 6f  .** Since versio
5770: 6e 20 33 2e 36 2e 31 38 2c 20 53 51 4c 69 74 65  n 3.6.18, SQLite
5780: 20 73 6f 75 72 63 65 20 63 6f 64 65 20 68 61 73   source code has
5790: 20 62 65 65 6e 20 73 74 6f 72 65 64 20 69 6e 20   been stored in 
57a0: 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22  the.** <a href="
57b0: 68 74 74 70 3a 2f 2f 77 77 77 2e 66 6f 73 73 69  http://www.fossi
57c0: 6c 2d 73 63 6d 2e 6f 72 67 2f 22 3e 46 6f 73 73  l-scm.org/">Foss
57d0: 69 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  il configuration
57e0: 20 6d 61 6e 61 67 65 6d 65 6e 74 0a 2a 2a 20 73   management.** s
57f0: 79 73 74 65 6d 3c 2f 61 3e 2e 20 20 5e 54 68 65  ystem</a>.  ^The
5800: 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49   SQLITE_SOURCE_I
5810: 44 20 6d 61 63 72 6f 20 65 76 61 6c 75 61 74 65  D macro evaluate
5820: 73 20 74 6f 0a 2a 2a 20 61 20 73 74 72 69 6e 67  s to.** a string
5830: 20 77 68 69 63 68 20 69 64 65 6e 74 69 66 69 65   which identifie
5840: 73 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 63  s a particular c
5850: 68 65 63 6b 2d 69 6e 20 6f 66 20 53 51 4c 69 74  heck-in of SQLit
5860: 65 0a 2a 2a 20 77 69 74 68 69 6e 20 69 74 73 20  e.** within its 
5870: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61  configuration ma
5880: 6e 61 67 65 6d 65 6e 74 20 73 79 73 74 65 6d 2e  nagement system.
5890: 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 53 4f    ^The SQLITE_SO
58a0: 55 52 43 45 5f 49 44 0a 2a 2a 20 73 74 72 69 6e  URCE_ID.** strin
58b0: 67 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 64  g contains the d
58c0: 61 74 65 20 61 6e 64 20 74 69 6d 65 20 6f 66 20  ate and time of 
58d0: 74 68 65 20 63 68 65 63 6b 2d 69 6e 20 28 55 54  the check-in (UT
58e0: 43 29 20 61 6e 64 20 61 6e 20 53 48 41 31 0a 2a  C) and an SHA1.*
58f0: 2a 20 68 61 73 68 20 6f 66 20 74 68 65 20 65 6e  * hash of the en
5900: 74 69 72 65 20 73 6f 75 72 63 65 20 74 72 65 65  tire source tree
5910: 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
5920: 3a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62 76 65  : [sqlite3_libve
5930: 72 73 69 6f 6e 28 29 5d 2c 0a 2a 2a 20 5b 73 71  rsion()],.** [sq
5940: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
5950: 5f 6e 75 6d 62 65 72 28 29 5d 2c 20 5b 73 71 6c  _number()], [sql
5960: 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29 5d  ite3_sourceid()]
5970: 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 76 65 72  ,.** [sqlite_ver
5980: 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c  sion()] and [sql
5990: 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29 5d  ite_source_id()]
59a0: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
59b0: 49 54 45 5f 56 45 52 53 49 4f 4e 20 20 20 20 20  ITE_VERSION     
59c0: 20 20 20 22 33 2e 37 2e 37 22 0a 23 64 65 66 69     "3.7.7".#defi
59d0: 6e 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  ne SQLITE_VERSIO
59e0: 4e 5f 4e 55 4d 42 45 52 20 33 30 30 37 30 30 37  N_NUMBER 3007007
59f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5a00: 53 4f 55 52 43 45 5f 49 44 20 20 20 20 20 20 22  SOURCE_ID      "
5a10: 32 30 31 31 2d 30 37 2d 31 31 20 31 38 3a 31 37  2011-07-11 18:17
5a20: 3a 35 36 20 63 32 30 61 63 61 30 36 36 31 30 34  :56 c20aca066104
5a30: 30 37 63 31 39 37 65 61 35 30 65 61 37 37 63 32  07c197ea50ea77c2
5a40: 35 39 31 61 61 63 66 32 32 35 32 61 22 0a 0a 2f  591aacf2252a"../
5a50: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
5a60: 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20  un-Time Library 
5a70: 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73 0a  Version Numbers.
5a80: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c  ** KEYWORDS: sql
5a90: 69 74 65 33 5f 76 65 72 73 69 6f 6e 2c 20 73 71  ite3_version, sq
5aa0: 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 0a 2a  lite3_sourceid.*
5ab0: 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 72  *.** These inter
5ac0: 66 61 63 65 73 20 70 72 6f 76 69 64 65 20 74 68  faces provide th
5ad0: 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69  e same informati
5ae0: 6f 6e 20 61 73 20 74 68 65 20 5b 53 51 4c 49 54  on as the [SQLIT
5af0: 45 5f 56 45 52 53 49 4f 4e 5d 2c 0a 2a 2a 20 5b  E_VERSION],.** [
5b00: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
5b10: 55 4d 42 45 52 5d 2c 20 61 6e 64 20 5b 53 51 4c  UMBER], and [SQL
5b20: 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20 43  ITE_SOURCE_ID] C
5b30: 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61   preprocessor ma
5b40: 63 72 6f 73 0a 2a 2a 20 62 75 74 20 61 72 65 20  cros.** but are 
5b50: 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
5b60: 74 68 65 20 6c 69 62 72 61 72 79 20 69 6e 73 74  the library inst
5b70: 65 61 64 20 6f 66 20 74 68 65 20 68 65 61 64 65  ead of the heade
5b80: 72 20 66 69 6c 65 2e 20 20 5e 28 43 61 75 74 69  r file.  ^(Cauti
5b90: 6f 75 73 0a 2a 2a 20 70 72 6f 67 72 61 6d 6d 65  ous.** programme
5ba0: 72 73 20 6d 69 67 68 74 20 69 6e 63 6c 75 64 65  rs might include
5bb0: 20 61 73 73 65 72 74 28 29 20 73 74 61 74 65 6d   assert() statem
5bc0: 65 6e 74 73 20 69 6e 20 74 68 65 69 72 20 61 70  ents in their ap
5bd0: 70 6c 69 63 61 74 69 6f 6e 20 74 6f 0a 2a 2a 20  plication to.** 
5be0: 76 65 72 69 66 79 20 74 68 61 74 20 76 61 6c 75  verify that valu
5bf0: 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  es returned by t
5c00: 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20  hese interfaces 
5c10: 6d 61 74 63 68 20 74 68 65 20 6d 61 63 72 6f 73  match the macros
5c20: 20 69 6e 0a 2a 2a 20 74 68 65 20 68 65 61 64 65   in.** the heade
5c30: 72 2c 20 61 6e 64 20 74 68 75 73 20 69 6e 73 75  r, and thus insu
5c40: 72 65 20 74 68 61 74 20 74 68 65 20 61 70 70 6c  re that the appl
5c50: 69 63 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 63 6f  ication is.** co
5c60: 6d 70 69 6c 65 64 20 77 69 74 68 20 6d 61 74 63  mpiled with matc
5c70: 68 69 6e 67 20 6c 69 62 72 61 72 79 20 61 6e 64  hing library and
5c80: 20 68 65 61 64 65 72 20 66 69 6c 65 73 2e 0a 2a   header files..*
5c90: 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
5ca0: 3e 3c 70 72 65 3e 0a 2a 2a 20 61 73 73 65 72 74  ><pre>.** assert
5cb0: 28 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72  ( sqlite3_libver
5cc0: 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 3d 3d 53  sion_number()==S
5cd0: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
5ce0: 4d 42 45 52 20 29 3b 0a 2a 2a 20 61 73 73 65 72  MBER );.** asser
5cf0: 74 28 20 73 74 72 63 6d 70 28 73 71 6c 69 74 65  t( strcmp(sqlite
5d00: 33 5f 73 6f 75 72 63 65 69 64 28 29 2c 53 51 4c  3_sourceid(),SQL
5d10: 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 29 3d 3d  ITE_SOURCE_ID)==
5d20: 30 20 29 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20  0 );.** assert( 
5d30: 73 74 72 63 6d 70 28 73 71 6c 69 74 65 33 5f 6c  strcmp(sqlite3_l
5d40: 69 62 76 65 72 73 69 6f 6e 28 29 2c 53 51 4c 49  ibversion(),SQLI
5d50: 54 45 5f 56 45 52 53 49 4f 4e 29 3d 3d 30 20 29  TE_VERSION)==0 )
5d60: 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
5d70: 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a  ckquote>)^.**.**
5d80: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 65   ^The sqlite3_ve
5d90: 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e 67 20 63  rsion[] string c
5da0: 6f 6e 73 74 61 6e 74 20 63 6f 6e 74 61 69 6e 73  onstant contains
5db0: 20 74 68 65 20 74 65 78 74 20 6f 66 20 5b 53 51   the text of [SQ
5dc0: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 0a 2a 2a  LITE_VERSION].**
5dd0: 20 6d 61 63 72 6f 2e 20 20 5e 54 68 65 20 73 71   macro.  ^The sq
5de0: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
5df0: 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  () function retu
5e00: 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
5e10: 20 74 68 65 0a 2a 2a 20 74 6f 20 74 68 65 20 73   the.** to the s
5e20: 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d  qlite3_version[]
5e30: 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74   string constant
5e40: 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6c  .  The sqlite3_l
5e50: 69 62 76 65 72 73 69 6f 6e 28 29 0a 2a 2a 20 66  ibversion().** f
5e60: 75 6e 63 74 69 6f 6e 20 69 73 20 70 72 6f 76 69  unction is provi
5e70: 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20 44  ded for use in D
5e80: 4c 4c 73 20 73 69 6e 63 65 20 44 4c 4c 20 75 73  LLs since DLL us
5e90: 65 72 73 20 75 73 75 61 6c 6c 79 20 64 6f 20 6e  ers usually do n
5ea0: 6f 74 20 68 61 76 65 0a 2a 2a 20 64 69 72 65 63  ot have.** direc
5eb0: 74 20 61 63 63 65 73 73 20 74 6f 20 73 74 72 69  t access to stri
5ec0: 6e 67 20 63 6f 6e 73 74 61 6e 74 73 20 77 69 74  ng constants wit
5ed0: 68 69 6e 20 74 68 65 20 44 4c 4c 2e 20 20 5e 54  hin the DLL.  ^T
5ee0: 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6c 69  he.** sqlite3_li
5ef0: 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28  bversion_number(
5f00: 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  ) function retur
5f10: 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20 65 71  ns an integer eq
5f20: 75 61 6c 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54  ual to.** [SQLIT
5f30: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
5f40: 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33  ].  ^The sqlite3
5f50: 5f 73 6f 75 72 63 65 69 64 28 29 20 66 75 6e 63  _sourceid() func
5f60: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 0a 2a 2a  tion returns .**
5f70: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
5f80: 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 20  string constant 
5f90: 77 68 6f 73 65 20 76 61 6c 75 65 20 69 73 20 74  whose value is t
5fa0: 68 65 20 73 61 6d 65 20 61 73 20 74 68 65 20 0a  he same as the .
5fb0: 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 4f 55 52 43  ** [SQLITE_SOURC
5fc0: 45 5f 49 44 5d 20 43 20 70 72 65 70 72 6f 63 65  E_ID] C preproce
5fd0: 73 73 6f 72 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a  ssor macro..**.*
5fe0: 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
5ff0: 69 74 65 5f 76 65 72 73 69 6f 6e 28 29 5d 20 61  ite_version()] a
6000: 6e 64 20 5b 73 71 6c 69 74 65 5f 73 6f 75 72 63  nd [sqlite_sourc
6010: 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49  e_id()]..*/.SQLI
6020: 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61  TE_API const cha
6030: 72 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f  r sqlite3_versio
6040: 6e 5b 5d 20 3d 20 53 51 4c 49 54 45 5f 56 45 52  n[] = SQLITE_VER
6050: 53 49 4f 4e 3b 0a 53 51 4c 49 54 45 5f 41 50 49  SION;.SQLITE_API
6060: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c   const char *sql
6070: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28  ite3_libversion(
6080: 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50  void);.SQLITE_AP
6090: 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  I const char *sq
60a0: 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 76  lite3_sourceid(v
60b0: 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  oid);.SQLITE_API
60c0: 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69 62   int sqlite3_lib
60d0: 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 76  version_number(v
60e0: 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  oid);../*.** CAP
60f0: 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20  I3REF: Run-Time 
6100: 4c 69 62 72 61 72 79 20 43 6f 6d 70 69 6c 61 74  Library Compilat
6110: 69 6f 6e 20 4f 70 74 69 6f 6e 73 20 44 69 61 67  ion Options Diag
6120: 6e 6f 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 5e 54  nostics.**.** ^T
6130: 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69  he sqlite3_compi
6140: 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 20  leoption_used() 
6150: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
6160: 20 30 20 6f 72 20 31 20 0a 2a 2a 20 69 6e 64 69   0 or 1 .** indi
6170: 63 61 74 69 6e 67 20 77 68 65 74 68 65 72 20 74  cating whether t
6180: 68 65 20 73 70 65 63 69 66 69 65 64 20 6f 70 74  he specified opt
6190: 69 6f 6e 20 77 61 73 20 64 65 66 69 6e 65 64 20  ion was defined 
61a0: 61 74 20 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74  at .** compile t
61b0: 69 6d 65 2e 20 20 5e 54 68 65 20 53 51 4c 49 54  ime.  ^The SQLIT
61c0: 45 5f 20 70 72 65 66 69 78 20 6d 61 79 20 62 65  E_ prefix may be
61d0: 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68   omitted from th
61e0: 65 20 0a 2a 2a 20 6f 70 74 69 6f 6e 20 6e 61 6d  e .** option nam
61f0: 65 20 70 61 73 73 65 64 20 74 6f 20 73 71 6c 69  e passed to sqli
6200: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
6210: 6e 5f 75 73 65 64 28 29 2e 20 20 0a 2a 2a 0a 2a  n_used().  .**.*
6220: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63  * ^The sqlite3_c
6230: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74  ompileoption_get
6240: 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 6c 6c 6f  () function allo
6250: 77 73 20 69 74 65 72 61 74 69 6e 67 0a 2a 2a 20  ws iterating.** 
6260: 6f 76 65 72 20 74 68 65 20 6c 69 73 74 20 6f 66  over the list of
6270: 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20 77 65   options that we
6280: 72 65 20 64 65 66 69 6e 65 64 20 61 74 20 63 6f  re defined at co
6290: 6d 70 69 6c 65 20 74 69 6d 65 20 62 79 0a 2a 2a  mpile time by.**
62a0: 20 72 65 74 75 72 6e 69 6e 67 20 74 68 65 20 4e   returning the N
62b0: 2d 74 68 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65  -th compile time
62c0: 20 6f 70 74 69 6f 6e 20 73 74 72 69 6e 67 2e 20   option string. 
62d0: 20 5e 49 66 20 4e 20 69 73 20 6f 75 74 20 6f 66   ^If N is out of
62e0: 20 72 61 6e 67 65 2c 0a 2a 2a 20 73 71 6c 69 74   range,.** sqlit
62f0: 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e  e3_compileoption
6300: 5f 67 65 74 28 29 20 72 65 74 75 72 6e 73 20 61  _get() returns a
6310: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20   NULL pointer.  
6320: 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 0a 2a 2a  ^The SQLITE_ .**
6330: 20 70 72 65 66 69 78 20 69 73 20 6f 6d 69 74 74   prefix is omitt
6340: 65 64 20 66 72 6f 6d 20 61 6e 79 20 73 74 72 69  ed from any stri
6350: 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ngs returned by 
6360: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  .** sqlite3_comp
6370: 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 2e  ileoption_get().
6380: 0a 2a 2a 0a 2a 2a 20 5e 53 75 70 70 6f 72 74 20  .**.** ^Support 
6390: 66 6f 72 20 74 68 65 20 64 69 61 67 6e 6f 73 74  for the diagnost
63a0: 69 63 20 66 75 6e 63 74 69 6f 6e 73 20 73 71 6c  ic functions sql
63b0: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
63c0: 6f 6e 5f 75 73 65 64 28 29 0a 2a 2a 20 61 6e 64  on_used().** and
63d0: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65   sqlite3_compile
63e0: 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 6d 61 79  option_get() may
63f0: 20 62 65 20 6f 6d 69 74 74 65 64 20 62 79 20 73   be omitted by s
6400: 70 65 63 69 66 79 69 6e 67 20 74 68 65 20 0a 2a  pecifying the .*
6410: 2a 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43  * [SQLITE_OMIT_C
6420: 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41  OMPILEOPTION_DIA
6430: 47 53 5d 20 6f 70 74 69 6f 6e 20 61 74 20 63 6f  GS] option at co
6440: 6d 70 69 6c 65 20 74 69 6d 65 2e 0a 2a 2a 0a 2a  mpile time..**.*
6450: 2a 20 53 65 65 20 61 6c 73 6f 3a 20 53 51 4c 20  * See also: SQL 
6460: 66 75 6e 63 74 69 6f 6e 73 20 5b 73 71 6c 69 74  functions [sqlit
6470: 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  e_compileoption_
6480: 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b  used()] and.** [
6490: 73 71 6c 69 74 65 5f 63 6f 6d 70 69 6c 65 6f 70  sqlite_compileop
64a0: 74 69 6f 6e 5f 67 65 74 28 29 5d 20 61 6e 64 20  tion_get()] and 
64b0: 74 68 65 20 5b 63 6f 6d 70 69 6c 65 5f 6f 70 74  the [compile_opt
64c0: 69 6f 6e 73 20 70 72 61 67 6d 61 5d 2e 0a 2a 2f  ions pragma]..*/
64d0: 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f  .#ifndef SQLITE_
64e0: 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45 4f 50 54 49  OMIT_COMPILEOPTI
64f0: 4f 4e 5f 44 49 41 47 53 0a 53 51 4c 49 54 45 5f  ON_DIAGS.SQLITE_
6500: 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
6510: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
6520: 65 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  ed(const char *z
6530: 4f 70 74 4e 61 6d 65 29 3b 0a 53 51 4c 49 54 45  OptName);.SQLITE
6540: 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20  _API const char 
6550: 2a 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65  *sqlite3_compile
6560: 6f 70 74 69 6f 6e 5f 67 65 74 28 69 6e 74 20 4e  option_get(int N
6570: 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a  );.#endif../*.**
6580: 20 43 41 50 49 33 52 45 46 3a 20 54 65 73 74 20   CAPI3REF: Test 
6590: 54 6f 20 53 65 65 20 49 66 20 54 68 65 20 4c 69  To See If The Li
65a0: 62 72 61 72 79 20 49 73 20 54 68 72 65 61 64 73  brary Is Threads
65b0: 61 66 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  afe.**.** ^The s
65c0: 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66  qlite3_threadsaf
65d0: 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  e() function ret
65e0: 75 72 6e 73 20 7a 65 72 6f 20 69 66 20 61 6e 64  urns zero if and
65f0: 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 53 51 4c 69   only if.** SQLi
6600: 74 65 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20  te was compiled 
6610: 6d 75 74 65 78 69 6e 67 20 63 6f 64 65 20 6f 6d  mutexing code om
6620: 69 74 74 65 64 20 64 75 65 20 74 6f 20 74 68 65  itted due to the
6630: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  .** [SQLITE_THRE
6640: 41 44 53 41 46 45 5d 20 63 6f 6d 70 69 6c 65 2d  ADSAFE] compile-
6650: 74 69 6d 65 20 6f 70 74 69 6f 6e 20 62 65 69 6e  time option bein
6660: 67 20 73 65 74 20 74 6f 20 30 2e 0a 2a 2a 0a 2a  g set to 0..**.*
6670: 2a 20 53 51 4c 69 74 65 20 63 61 6e 20 62 65 20  * SQLite can be 
6680: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6f 72  compiled with or
6690: 20 77 69 74 68 6f 75 74 20 6d 75 74 65 78 65 73   without mutexes
66a0: 2e 20 20 57 68 65 6e 0a 2a 2a 20 74 68 65 20 5b  .  When.** the [
66b0: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
66c0: 45 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f  E] C preprocesso
66d0: 72 20 6d 61 63 72 6f 20 69 73 20 31 20 6f 72 20  r macro is 1 or 
66e0: 32 2c 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72  2, mutexes.** ar
66f0: 65 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 53 51  e enabled and SQ
6700: 4c 69 74 65 20 69 73 20 74 68 72 65 61 64 73 61  Lite is threadsa
6710: 66 65 2e 20 20 57 68 65 6e 20 74 68 65 0a 2a 2a  fe.  When the.**
6720: 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
6730: 41 46 45 5d 20 6d 61 63 72 6f 20 69 73 20 30 2c  AFE] macro is 0,
6740: 20 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65 73   .** the mutexes
6750: 20 61 72 65 20 6f 6d 69 74 74 65 64 2e 20 20 57   are omitted.  W
6760: 69 74 68 6f 75 74 20 74 68 65 20 6d 75 74 65 78  ithout the mutex
6770: 65 73 2c 20 69 74 20 69 73 20 6e 6f 74 20 73 61  es, it is not sa
6780: 66 65 0a 2a 2a 20 74 6f 20 75 73 65 20 53 51 4c  fe.** to use SQL
6790: 69 74 65 20 63 6f 6e 63 75 72 72 65 6e 74 6c 79  ite concurrently
67a0: 20 66 72 6f 6d 20 6d 6f 72 65 20 74 68 61 6e 20   from more than 
67b0: 6f 6e 65 20 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a  one thread..**.*
67c0: 2a 20 45 6e 61 62 6c 69 6e 67 20 6d 75 74 65 78  * Enabling mutex
67d0: 65 73 20 69 6e 63 75 72 73 20 61 20 6d 65 61 73  es incurs a meas
67e0: 75 72 61 62 6c 65 20 70 65 72 66 6f 72 6d 61 6e  urable performan
67f0: 63 65 20 70 65 6e 61 6c 74 79 2e 0a 2a 2a 20 53  ce penalty..** S
6800: 6f 20 69 66 20 73 70 65 65 64 20 69 73 20 6f 66  o if speed is of
6810: 20 75 74 6d 6f 73 74 20 69 6d 70 6f 72 74 61 6e   utmost importan
6820: 63 65 2c 20 69 74 20 6d 61 6b 65 73 20 73 65 6e  ce, it makes sen
6830: 73 65 20 74 6f 20 64 69 73 61 62 6c 65 0a 2a 2a  se to disable.**
6840: 20 74 68 65 20 6d 75 74 65 78 65 73 2e 20 20 42   the mutexes.  B
6850: 75 74 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 73  ut for maximum s
6860: 61 66 65 74 79 2c 20 6d 75 74 65 78 65 73 20 73  afety, mutexes s
6870: 68 6f 75 6c 64 20 62 65 20 65 6e 61 62 6c 65 64  hould be enabled
6880: 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c  ..** ^The defaul
6890: 74 20 62 65 68 61 76 69 6f 72 20 69 73 20 66 6f  t behavior is fo
68a0: 72 20 6d 75 74 65 78 65 73 20 74 6f 20 62 65 20  r mutexes to be 
68b0: 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  enabled..**.** T
68c0: 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61  his interface ca
68d0: 6e 20 62 65 20 75 73 65 64 20 62 79 20 61 6e 20  n be used by an 
68e0: 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 6d  application to m
68f0: 61 6b 65 20 73 75 72 65 20 74 68 61 74 20 74 68  ake sure that th
6900: 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66 20  e.** version of 
6910: 53 51 4c 69 74 65 20 74 68 61 74 20 69 74 20 69  SQLite that it i
6920: 73 20 6c 69 6e 6b 69 6e 67 20 61 67 61 69 6e 73  s linking agains
6930: 74 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77  t was compiled w
6940: 69 74 68 0a 2a 2a 20 74 68 65 20 64 65 73 69 72  ith.** the desir
6950: 65 64 20 73 65 74 74 69 6e 67 20 6f 66 20 74 68  ed setting of th
6960: 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
6970: 53 41 46 45 5d 20 6d 61 63 72 6f 2e 0a 2a 2a 0a  SAFE] macro..**.
6980: 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  ** This interfac
6990: 65 20 6f 6e 6c 79 20 72 65 70 6f 72 74 73 20 6f  e only reports o
69a0: 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69  n the compile-ti
69b0: 6d 65 20 6d 75 74 65 78 20 73 65 74 74 69 6e 67  me mutex setting
69c0: 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c 49  .** of the [SQLI
69d0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 66  TE_THREADSAFE] f
69e0: 6c 61 67 2e 20 20 49 66 20 53 51 4c 69 74 65 20  lag.  If SQLite 
69f0: 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
6a00: 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 48 52 45 41  .** SQLITE_THREA
6a10: 44 53 41 46 45 3d 31 20 6f 72 20 3d 32 20 74 68  DSAFE=1 or =2 th
6a20: 65 6e 20 6d 75 74 65 78 65 73 20 61 72 65 20 65  en mutexes are e
6a30: 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  nabled by defaul
6a40: 74 20 62 75 74 0a 2a 2a 20 63 61 6e 20 62 65 20  t but.** can be 
6a50: 66 75 6c 6c 79 20 6f 72 20 70 61 72 74 69 61 6c  fully or partial
6a60: 6c 79 20 64 69 73 61 62 6c 65 64 20 75 73 69 6e  ly disabled usin
6a70: 67 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  g a call to [sql
6a80: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 0a 2a  ite3_config()].*
6a90: 2a 20 77 69 74 68 20 74 68 65 20 76 65 72 62 73  * with the verbs
6aa0: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
6ab0: 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 2c 20 5b  SINGLETHREAD], [
6ac0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
6ad0: 4c 54 49 54 48 52 45 41 44 5d 2c 0a 2a 2a 20 6f  LTITHREAD],.** o
6ae0: 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  r [SQLITE_CONFIG
6af0: 5f 4d 55 54 45 58 5d 2e 20 20 5e 28 54 68 65 20  _MUTEX].  ^(The 
6b00: 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
6b10: 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 74  the.** sqlite3_t
6b20: 68 72 65 61 64 73 61 66 65 28 29 20 66 75 6e 63  hreadsafe() func
6b30: 74 69 6f 6e 20 73 68 6f 77 73 20 6f 6e 6c 79 20  tion shows only 
6b40: 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  the compile-time
6b50: 20 73 65 74 74 69 6e 67 20 6f 66 0a 2a 2a 20 74   setting of.** t
6b60: 68 72 65 61 64 20 73 61 66 65 74 79 2c 20 6e 6f  hread safety, no
6b70: 74 20 61 6e 79 20 72 75 6e 2d 74 69 6d 65 20 63  t any run-time c
6b80: 68 61 6e 67 65 73 20 74 6f 20 74 68 61 74 20 73  hanges to that s
6b90: 65 74 74 69 6e 67 20 6d 61 64 65 20 62 79 0a 2a  etting made by.*
6ba0: 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  * sqlite3_config
6bb0: 28 29 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  (). In other wor
6bc0: 64 73 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76  ds, the return v
6bd0: 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65  alue from sqlite
6be0: 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 0a 2a  3_threadsafe().*
6bf0: 2a 20 69 73 20 75 6e 63 68 61 6e 67 65 64 20 62  * is unchanged b
6c00: 79 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  y calls to sqlit
6c10: 65 33 5f 63 6f 6e 66 69 67 28 29 2e 29 5e 0a 2a  e3_config().)^.*
6c20: 2a 0a 2a 2a 20 53 65 65 20 74 68 65 20 5b 74 68  *.** See the [th
6c30: 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 64 6f  reading mode] do
6c40: 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20  cumentation for 
6c50: 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  additional infor
6c60: 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49 54  mation..*/.SQLIT
6c70: 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
6c80: 33 5f 74 68 72 65 61 64 73 61 66 65 28 76 6f 69  3_threadsafe(voi
6c90: 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  d);../*.** CAPI3
6ca0: 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f  REF: Database Co
6cb0: 6e 6e 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65 0a  nnection Handle.
6cc0: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 64 61  ** KEYWORDS: {da
6cd0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
6ce0: 6e 7d 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e  n} {database con
6cf0: 6e 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20  nections}.**.** 
6d00: 45 61 63 68 20 6f 70 65 6e 20 53 51 4c 69 74 65  Each open SQLite
6d10: 20 64 61 74 61 62 61 73 65 20 69 73 20 72 65 70   database is rep
6d20: 72 65 73 65 6e 74 65 64 20 62 79 20 61 20 70 6f  resented by a po
6d30: 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74  inter to an inst
6d40: 61 6e 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6f  ance of.** the o
6d50: 70 61 71 75 65 20 73 74 72 75 63 74 75 72 65 20  paque structure 
6d60: 6e 61 6d 65 64 20 22 73 71 6c 69 74 65 33 22 2e  named "sqlite3".
6d70: 20 20 49 74 20 69 73 20 75 73 65 66 75 6c 20 74    It is useful t
6d80: 6f 20 74 68 69 6e 6b 20 6f 66 20 61 6e 20 73 71  o think of an sq
6d90: 6c 69 74 65 33 0a 2a 2a 20 70 6f 69 6e 74 65 72  lite3.** pointer
6da0: 20 61 73 20 61 6e 20 6f 62 6a 65 63 74 2e 20 20   as an object.  
6db0: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  The [sqlite3_ope
6dc0: 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f  n()], [sqlite3_o
6dd0: 70 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a  pen16()], and.**
6de0: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
6df0: 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20  2()] interfaces 
6e00: 61 72 65 20 69 74 73 20 63 6f 6e 73 74 72 75 63  are its construc
6e10: 74 6f 72 73 2c 20 61 6e 64 20 5b 73 71 6c 69 74  tors, and [sqlit
6e20: 65 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20 69  e3_close()].** i
6e30: 73 20 69 74 73 20 64 65 73 74 72 75 63 74 6f 72  s its destructor
6e40: 2e 20 20 54 68 65 72 65 20 61 72 65 20 6d 61 6e  .  There are man
6e50: 79 20 6f 74 68 65 72 20 69 6e 74 65 72 66 61 63  y other interfac
6e60: 65 73 20 28 73 75 63 68 20 61 73 0a 2a 2a 20 5b  es (such as.** [
6e70: 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
6e80: 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  v2()], [sqlite3_
6e90: 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
6ea0: 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
6eb0: 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74  te3_busy_timeout
6ec0: 28 29 5d 20 74 6f 20 6e 61 6d 65 20 62 75 74 20  ()] to name but 
6ed0: 74 68 72 65 65 29 20 74 68 61 74 20 61 72 65 20  three) that are 
6ee0: 6d 65 74 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a 2a  methods on an.**
6ef0: 20 73 71 6c 69 74 65 33 20 6f 62 6a 65 63 74 2e   sqlite3 object.
6f00: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
6f10: 63 74 20 73 71 6c 69 74 65 33 20 73 71 6c 69 74  ct sqlite3 sqlit
6f20: 65 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  e3;../*.** CAPI3
6f30: 52 45 46 3a 20 36 34 2d 42 69 74 20 49 6e 74 65  REF: 64-Bit Inte
6f40: 67 65 72 20 54 79 70 65 73 0a 2a 2a 20 4b 45 59  ger Types.** KEY
6f50: 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 5f 69 6e  WORDS: sqlite_in
6f60: 74 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74 36  t64 sqlite_uint6
6f70: 34 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20  4.**.** Because 
6f80: 74 68 65 72 65 20 69 73 20 6e 6f 20 63 72 6f 73  there is no cros
6f90: 73 2d 70 6c 61 74 66 6f 72 6d 20 77 61 79 20 74  s-platform way t
6fa0: 6f 20 73 70 65 63 69 66 79 20 36 34 2d 62 69 74  o specify 64-bit
6fb0: 20 69 6e 74 65 67 65 72 20 74 79 70 65 73 0a 2a   integer types.*
6fc0: 2a 20 53 51 4c 69 74 65 20 69 6e 63 6c 75 64 65  * SQLite include
6fd0: 73 20 74 79 70 65 64 65 66 73 20 66 6f 72 20 36  s typedefs for 6
6fe0: 34 2d 62 69 74 20 73 69 67 6e 65 64 20 61 6e 64  4-bit signed and
6ff0: 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65   unsigned intege
7000: 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  rs..**.** The sq
7010: 6c 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 20  lite3_int64 and 
7020: 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 61  sqlite3_uint64 a
7030: 72 65 20 74 68 65 20 70 72 65 66 65 72 72 65 64  re the preferred
7040: 20 74 79 70 65 20 64 65 66 69 6e 69 74 69 6f 6e   type definition
7050: 73 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  s..** The sqlite
7060: 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74  _int64 and sqlit
7070: 65 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20 61  e_uint64 types a
7080: 72 65 20 73 75 70 70 6f 72 74 65 64 20 66 6f 72  re supported for
7090: 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f   backwards.** co
70a0: 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79  mpatibility only
70b0: 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
70c0: 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73  ite3_int64 and s
70d0: 71 6c 69 74 65 5f 69 6e 74 36 34 20 74 79 70 65  qlite_int64 type
70e0: 73 20 63 61 6e 20 73 74 6f 72 65 20 69 6e 74 65  s can store inte
70f0: 67 65 72 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65  ger values.** be
7100: 74 77 65 65 6e 20 2d 39 32 32 33 33 37 32 30 33  tween -922337203
7110: 36 38 35 34 37 37 35 38 30 38 20 61 6e 64 20 2b  6854775808 and +
7120: 39 32 32 33 33 37 32 30 33 36 38 35 34 37 37 35  9223372036854775
7130: 38 30 37 20 69 6e 63 6c 75 73 69 76 65 2e 20 20  807 inclusive.  
7140: 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ^The.** sqlite3_
7150: 75 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74  uint64 and sqlit
7160: 65 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20 63  e_uint64 types c
7170: 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65 72  an store integer
7180: 20 76 61 6c 75 65 73 20 0a 2a 2a 20 62 65 74 77   values .** betw
7190: 65 65 6e 20 30 20 61 6e 64 20 2b 31 38 34 34 36  een 0 and +18446
71a0: 37 34 34 30 37 33 37 30 39 35 35 31 36 31 35 20  744073709551615 
71b0: 69 6e 63 6c 75 73 69 76 65 2e 0a 2a 2f 0a 23 69  inclusive..*/.#i
71c0: 66 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36  fdef SQLITE_INT6
71d0: 34 5f 54 59 50 45 0a 20 20 74 79 70 65 64 65 66  4_TYPE.  typedef
71e0: 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59   SQLITE_INT64_TY
71f0: 50 45 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b  PE sqlite_int64;
7200: 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67  .  typedef unsig
7210: 6e 65 64 20 53 51 4c 49 54 45 5f 49 4e 54 36 34  ned SQLITE_INT64
7220: 5f 54 59 50 45 20 73 71 6c 69 74 65 5f 75 69 6e  _TYPE sqlite_uin
7230: 74 36 34 3b 0a 23 65 6c 69 66 20 64 65 66 69 6e  t64;.#elif defin
7240: 65 64 28 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20  ed(_MSC_VER) || 
7250: 64 65 66 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e  defined(__BORLAN
7260: 44 43 5f 5f 29 0a 20 20 74 79 70 65 64 65 66 20  DC__).  typedef 
7270: 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 69  __int64 sqlite_i
7280: 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20  nt64;.  typedef 
7290: 75 6e 73 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34  unsigned __int64
72a0: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a   sqlite_uint64;.
72b0: 23 65 6c 73 65 0a 20 20 74 79 70 65 64 65 66 20  #else.  typedef 
72c0: 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71  long long int sq
72d0: 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79  lite_int64;.  ty
72e0: 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 6c  pedef unsigned l
72f0: 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c  ong long int sql
7300: 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64  ite_uint64;.#end
7310: 69 66 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74  if.typedef sqlit
7320: 65 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  e_int64 sqlite3_
7330: 69 6e 74 36 34 3b 0a 74 79 70 65 64 65 66 20 73  int64;.typedef s
7340: 71 6c 69 74 65 5f 75 69 6e 74 36 34 20 73 71 6c  qlite_uint64 sql
7350: 69 74 65 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a  ite3_uint64;../*
7360: 0a 2a 2a 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67  .** If compiling
7370: 20 66 6f 72 20 61 20 70 72 6f 63 65 73 73 6f 72   for a processor
7380: 20 74 68 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61   that lacks floa
7390: 74 69 6e 67 20 70 6f 69 6e 74 20 73 75 70 70 6f  ting point suppo
73a0: 72 74 2c 0a 2a 2a 20 73 75 62 73 74 69 74 75 74  rt,.** substitut
73b0: 65 20 69 6e 74 65 67 65 72 20 66 6f 72 20 66 6c  e integer for fl
73c0: 6f 61 74 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f  oating-point..*/
73d0: 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 4f  .#ifdef SQLITE_O
73e0: 4d 49 54 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49  MIT_FLOATING_POI
73f0: 4e 54 0a 23 20 64 65 66 69 6e 65 20 64 6f 75 62  NT.# define doub
7400: 6c 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  le sqlite3_int64
7410: 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43  .#endif../*.** C
7420: 41 50 49 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67  API3REF: Closing
7430: 20 41 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e   A Database Conn
7440: 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ection.**.** ^Th
7450: 65 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28  e sqlite3_close(
7460: 29 20 72 6f 75 74 69 6e 65 20 69 73 20 74 68 65  ) routine is the
7470: 20 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72 20   destructor for 
7480: 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62  the [sqlite3] ob
7490: 6a 65 63 74 2e 0a 2a 2a 20 5e 43 61 6c 6c 73 20  ject..** ^Calls 
74a0: 74 6f 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  to sqlite3_close
74b0: 28 29 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45  () return SQLITE
74c0: 5f 4f 4b 20 69 66 20 74 68 65 20 5b 73 71 6c 69  _OK if the [sqli
74d0: 74 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 0a 2a  te3] object is.*
74e0: 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 20 64  * successfully d
74f0: 65 73 74 72 6f 79 65 64 20 61 6e 64 20 61 6c 6c  estroyed and all
7500: 20 61 73 73 6f 63 69 61 74 65 64 20 72 65 73 6f   associated reso
7510: 75 72 63 65 73 20 61 72 65 20 64 65 61 6c 6c 6f  urces are deallo
7520: 63 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 70 70  cated..**.** App
7530: 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73 74 20 5b  lications must [
7540: 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
7550: 20 7c 20 66 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c   | finalize] all
7560: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
7570: 6d 65 6e 74 73 5d 0a 2a 2a 20 61 6e 64 20 5b 73  ments].** and [s
7580: 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73  qlite3_blob_clos
7590: 65 20 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b  e | close] all [
75a0: 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 20 61 73  BLOB handles] as
75b0: 73 6f 63 69 61 74 65 64 20 77 69 74 68 0a 2a 2a  sociated with.**
75c0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f   the [sqlite3] o
75d0: 62 6a 65 63 74 20 70 72 69 6f 72 20 74 6f 20 61  bject prior to a
75e0: 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 63 6c 6f  ttempting to clo
75f0: 73 65 20 74 68 65 20 6f 62 6a 65 63 74 2e 20 20  se the object.  
7600: 5e 49 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63  ^If.** sqlite3_c
7610: 6c 6f 73 65 28 29 20 69 73 20 63 61 6c 6c 65 64  lose() is called
7620: 20 6f 6e 20 61 20 5b 64 61 74 61 62 61 73 65 20   on a [database 
7630: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74  connection] that
7640: 20 73 74 69 6c 6c 20 68 61 73 0a 2a 2a 20 6f 75   still has.** ou
7650: 74 73 74 61 6e 64 69 6e 67 20 5b 70 72 65 70 61  tstanding [prepa
7660: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20  red statements] 
7670: 6f 72 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73  or [BLOB handles
7680: 5d 2c 20 74 68 65 6e 20 69 74 20 72 65 74 75 72  ], then it retur
7690: 6e 73 0a 2a 2a 20 53 51 4c 49 54 45 5f 42 55 53  ns.** SQLITE_BUS
76a0: 59 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 73 71  Y..**.** ^If [sq
76b0: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 69  lite3_close()] i
76c0: 73 20 69 6e 76 6f 6b 65 64 20 77 68 69 6c 65 20  s invoked while 
76d0: 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73  a transaction is
76e0: 20 6f 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72   open,.** the tr
76f0: 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74  ansaction is aut
7700: 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65  omatically rolle
7710: 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68  d back..**.** Th
7720: 65 20 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f  e C parameter to
7730: 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28   [sqlite3_close(
7740: 43 29 5d 20 6d 75 73 74 20 62 65 20 65 69 74 68  C)] must be eith
7750: 65 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69  er a NULL.** poi
7760: 6e 74 65 72 20 6f 72 20 61 6e 20 5b 73 71 6c 69  nter or an [sqli
7770: 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 6f 69 6e  te3] object poin
7780: 74 65 72 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20  ter obtained.** 
7790: 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6f 70  from [sqlite3_op
77a0: 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  en()], [sqlite3_
77b0: 6f 70 65 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a  open16()], or.**
77c0: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
77d0: 32 28 29 5d 2c 20 61 6e 64 20 6e 6f 74 20 70 72  2()], and not pr
77e0: 65 76 69 6f 75 73 6c 79 20 63 6c 6f 73 65 64 2e  eviously closed.
77f0: 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c  .** ^Calling sql
7800: 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 77 69 74  ite3_close() wit
7810: 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  h a NULL pointer
7820: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 0a   argument is a .
7830: 2a 2a 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f  ** harmless no-o
7840: 70 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  p..*/.SQLITE_API
7850: 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f   int sqlite3_clo
7860: 73 65 28 73 71 6c 69 74 65 33 20 2a 29 3b 0a 0a  se(sqlite3 *);..
7870: 2f 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 20 66  /*.** The type f
7880: 6f 72 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75  or a callback fu
7890: 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20  nction..** This 
78a0: 69 73 20 6c 65 67 61 63 79 20 61 6e 64 20 64 65  is legacy and de
78b0: 70 72 65 63 61 74 65 64 2e 20 20 49 74 20 69 73  precated.  It is
78c0: 20 69 6e 63 6c 75 64 65 64 20 66 6f 72 20 68 69   included for hi
78d0: 73 74 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70  storical.** comp
78e0: 61 74 69 62 69 6c 69 74 79 20 61 6e 64 20 69 73  atibility and is
78f0: 20 6e 6f 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e   not documented.
7900: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 69 6e 74 20  .*/.typedef int 
7910: 28 2a 73 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61  (*sqlite3_callba
7920: 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68  ck)(void*,int,ch
7930: 61 72 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a  ar**, char**);..
7940: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
7950: 4f 6e 65 2d 53 74 65 70 20 51 75 65 72 79 20 45  One-Step Query E
7960: 78 65 63 75 74 69 6f 6e 20 49 6e 74 65 72 66 61  xecution Interfa
7970: 63 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  ce.**.** The sql
7980: 69 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65  ite3_exec() inte
7990: 72 66 61 63 65 20 69 73 20 61 20 63 6f 6e 76 65  rface is a conve
79a0: 6e 69 65 6e 63 65 20 77 72 61 70 70 65 72 20 61  nience wrapper a
79b0: 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  round.** [sqlite
79c0: 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c  3_prepare_v2()],
79d0: 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
79e0: 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ], and [sqlite3_
79f0: 66 69 6e 61 6c 69 7a 65 28 29 5d 2c 0a 2a 2a 20  finalize()],.** 
7a00: 74 68 61 74 20 61 6c 6c 6f 77 73 20 61 6e 20 61  that allows an a
7a10: 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 72 75  pplication to ru
7a20: 6e 20 6d 75 6c 74 69 70 6c 65 20 73 74 61 74 65  n multiple state
7a30: 6d 65 6e 74 73 20 6f 66 20 53 51 4c 0a 2a 2a 20  ments of SQL.** 
7a40: 77 69 74 68 6f 75 74 20 68 61 76 69 6e 67 20 74  without having t
7a50: 6f 20 75 73 65 20 61 20 6c 6f 74 20 6f 66 20 43  o use a lot of C
7a60: 20 63 6f 64 65 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54   code. .**.** ^T
7a70: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  he sqlite3_exec(
7a80: 29 20 69 6e 74 65 72 66 61 63 65 20 72 75 6e 73  ) interface runs
7a90: 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 55 54   zero or more UT
7aa0: 46 2d 38 20 65 6e 63 6f 64 65 64 2c 0a 2a 2a 20  F-8 encoded,.** 
7ab0: 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61  semicolon-separa
7ac0: 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  te SQL statement
7ad0: 73 20 70 61 73 73 65 64 20 69 6e 74 6f 20 69 74  s passed into it
7ae0: 73 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2c 0a  s 2nd argument,.
7af0: 2a 2a 20 69 6e 20 74 68 65 20 63 6f 6e 74 65 78  ** in the contex
7b00: 74 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61  t of the [databa
7b10: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70  se connection] p
7b20: 61 73 73 65 64 20 69 6e 20 61 73 20 69 74 73 20  assed in as its 
7b30: 31 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e  1st.** argument.
7b40: 20 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61    ^If the callba
7b50: 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74  ck function of t
7b60: 68 65 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20  he 3rd argument 
7b70: 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78  to.** sqlite3_ex
7b80: 65 63 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  ec() is not NULL
7b90: 2c 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e 76  , then it is inv
7ba0: 6f 6b 65 64 20 66 6f 72 20 65 61 63 68 20 72 65  oked for each re
7bb0: 73 75 6c 74 20 72 6f 77 0a 2a 2a 20 63 6f 6d 69  sult row.** comi
7bc0: 6e 67 20 6f 75 74 20 6f 66 20 74 68 65 20 65 76  ng out of the ev
7bd0: 61 6c 75 61 74 65 64 20 53 51 4c 20 73 74 61 74  aluated SQL stat
7be0: 65 6d 65 6e 74 73 2e 20 20 5e 54 68 65 20 34 74  ements.  ^The 4t
7bf0: 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  h argument to.**
7c00: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
7c10: 69 73 20 72 65 6c 61 79 65 64 20 74 68 72 6f 75  is relayed throu
7c20: 67 68 20 74 6f 20 74 68 65 20 31 73 74 20 61 72  gh to the 1st ar
7c30: 67 75 6d 65 6e 74 20 6f 66 20 65 61 63 68 0a 2a  gument of each.*
7c40: 2a 20 63 61 6c 6c 62 61 63 6b 20 69 6e 76 6f 63  * callback invoc
7c50: 61 74 69 6f 6e 2e 20 20 5e 49 66 20 74 68 65 20  ation.  ^If the 
7c60: 63 61 6c 6c 62 61 63 6b 20 70 6f 69 6e 74 65 72  callback pointer
7c70: 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63   to sqlite3_exec
7c80: 28 29 0a 2a 2a 20 69 73 20 4e 55 4c 4c 2c 20 74  ().** is NULL, t
7c90: 68 65 6e 20 6e 6f 20 63 61 6c 6c 62 61 63 6b 20  hen no callback 
7ca0: 69 73 20 65 76 65 72 20 69 6e 76 6f 6b 65 64 20  is ever invoked 
7cb0: 61 6e 64 20 72 65 73 75 6c 74 20 72 6f 77 73 20  and result rows 
7cc0: 61 72 65 0a 2a 2a 20 69 67 6e 6f 72 65 64 2e 0a  are.** ignored..
7cd0: 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 65 72 72  **.** ^If an err
7ce0: 6f 72 20 6f 63 63 75 72 73 20 77 68 69 6c 65 20  or occurs while 
7cf0: 65 76 61 6c 75 61 74 69 6e 67 20 74 68 65 20 53  evaluating the S
7d00: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 70 61  QL statements pa
7d10: 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c  ssed into.** sql
7d20: 69 74 65 33 5f 65 78 65 63 28 29 2c 20 74 68 65  ite3_exec(), the
7d30: 6e 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74  n execution of t
7d40: 68 65 20 63 75 72 72 65 6e 74 20 73 74 61 74 65  he current state
7d50: 6d 65 6e 74 20 73 74 6f 70 73 20 61 6e 64 0a 2a  ment stops and.*
7d60: 2a 20 73 75 62 73 65 71 75 65 6e 74 20 73 74 61  * subsequent sta
7d70: 74 65 6d 65 6e 74 73 20 61 72 65 20 73 6b 69 70  tements are skip
7d80: 70 65 64 2e 20 20 5e 49 66 20 74 68 65 20 35 74  ped.  ^If the 5t
7d90: 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
7da0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a  qlite3_exec().**
7db0: 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65   is not NULL the
7dc0: 6e 20 61 6e 79 20 65 72 72 6f 72 20 6d 65 73 73  n any error mess
7dd0: 61 67 65 20 69 73 20 77 72 69 74 74 65 6e 20 69  age is written i
7de0: 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69  nto memory obtai
7df0: 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  ned.** from [sql
7e00: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61  ite3_malloc()] a
7e10: 6e 64 20 70 61 73 73 65 64 20 62 61 63 6b 20 74  nd passed back t
7e20: 68 72 6f 75 67 68 20 74 68 65 20 35 74 68 20 70  hrough the 5th p
7e30: 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 54 6f 20  arameter..** To 
7e40: 61 76 6f 69 64 20 6d 65 6d 6f 72 79 20 6c 65 61  avoid memory lea
7e50: 6b 73 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74  ks, the applicat
7e60: 69 6f 6e 20 73 68 6f 75 6c 64 20 69 6e 76 6f 6b  ion should invok
7e70: 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  e [sqlite3_free(
7e80: 29 5d 0a 2a 2a 20 6f 6e 20 65 72 72 6f 72 20 6d  )].** on error m
7e90: 65 73 73 61 67 65 20 73 74 72 69 6e 67 73 20 72  essage strings r
7ea0: 65 74 75 72 6e 65 64 20 74 68 72 6f 75 67 68 20  eturned through 
7eb0: 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65  the 5th paramete
7ec0: 72 20 6f 66 0a 2a 2a 20 6f 66 20 73 71 6c 69 74  r of.** of sqlit
7ed0: 65 33 5f 65 78 65 63 28 29 20 61 66 74 65 72 20  e3_exec() after 
7ee0: 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
7ef0: 65 20 73 74 72 69 6e 67 20 69 73 20 6e 6f 20 6c  e string is no l
7f00: 6f 6e 67 65 72 20 6e 65 65 64 65 64 2e 0a 2a 2a  onger needed..**
7f10: 20 5e 49 66 20 74 68 65 20 35 74 68 20 70 61 72   ^If the 5th par
7f20: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
7f30: 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f 74 20  3_exec() is not 
7f40: 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20 65 72 72 6f  NULL and no erro
7f50: 72 73 0a 2a 2a 20 6f 63 63 75 72 2c 20 74 68 65  rs.** occur, the
7f60: 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  n sqlite3_exec()
7f70: 20 73 65 74 73 20 74 68 65 20 70 6f 69 6e 74 65   sets the pointe
7f80: 72 20 69 6e 20 69 74 73 20 35 74 68 20 70 61 72  r in its 5th par
7f90: 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 4e 55 4c  ameter to.** NUL
7fa0: 4c 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69  L before returni
7fb0: 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e  ng..**.** ^If an
7fc0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
7fd0: 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
7fe0: 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 73   non-zero, the s
7ff0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a  qlite3_exec().**
8000: 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
8010: 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 77 69   SQLITE_ABORT wi
8020: 74 68 6f 75 74 20 69 6e 76 6f 6b 69 6e 67 20 74  thout invoking t
8030: 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 67 61 69  he callback agai
8040: 6e 20 61 6e 64 0a 2a 2a 20 77 69 74 68 6f 75 74  n and.** without
8050: 20 72 75 6e 6e 69 6e 67 20 61 6e 79 20 73 75 62   running any sub
8060: 73 65 71 75 65 6e 74 20 53 51 4c 20 73 74 61 74  sequent SQL stat
8070: 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ements..**.** ^T
8080: 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 20  he 2nd argument 
8090: 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65  to the sqlite3_e
80a0: 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 66  xec() callback f
80b0: 75 6e 63 74 69 6f 6e 20 69 73 20 74 68 65 0a 2a  unction is the.*
80c0: 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  * number of colu
80d0: 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c  mns in the resul
80e0: 74 2e 20 20 5e 54 68 65 20 33 72 64 20 61 72 67  t.  ^The 3rd arg
80f0: 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c  ument to the sql
8100: 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 63  ite3_exec().** c
8110: 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 61 72  allback is an ar
8120: 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20  ray of pointers 
8130: 74 6f 20 73 74 72 69 6e 67 73 20 6f 62 74 61 69  to strings obtai
8140: 6e 65 64 20 61 73 20 69 66 20 66 72 6f 6d 0a 2a  ned as if from.*
8150: 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
8160: 6e 5f 74 65 78 74 28 29 5d 2c 20 6f 6e 65 20 66  n_text()], one f
8170: 6f 72 20 65 61 63 68 20 63 6f 6c 75 6d 6e 2e 20  or each column. 
8180: 20 5e 49 66 20 61 6e 20 65 6c 65 6d 65 6e 74 20   ^If an element 
8190: 6f 66 20 61 0a 2a 2a 20 72 65 73 75 6c 74 20 72  of a.** result r
81a0: 6f 77 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20  ow is NULL then 
81b0: 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
81c0: 67 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72  g string pointer
81d0: 20 66 6f 72 20 74 68 65 0a 2a 2a 20 73 71 6c 69   for the.** sqli
81e0: 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62  te3_exec() callb
81f0: 61 63 6b 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  ack is a NULL po
8200: 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 34 74 68  inter.  ^The 4th
8210: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
8220: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63  .** sqlite3_exec
8230: 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  () callback is a
8240: 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
8250: 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 77  ers to strings w
8260: 68 65 72 65 20 65 61 63 68 0a 2a 2a 20 65 6e 74  here each.** ent
8270: 72 79 20 72 65 70 72 65 73 65 6e 74 73 20 74 68  ry represents th
8280: 65 20 6e 61 6d 65 20 6f 66 20 63 6f 72 72 65 73  e name of corres
8290: 70 6f 6e 64 69 6e 67 20 72 65 73 75 6c 74 20 63  ponding result c
82a0: 6f 6c 75 6d 6e 20 61 73 20 6f 62 74 61 69 6e 65  olumn as obtaine
82b0: 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74  d.** from [sqlit
82c0: 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29  e3_column_name()
82d0: 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  ]..**.** ^If the
82e0: 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74   2nd parameter t
82f0: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  o sqlite3_exec()
8300: 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
8310: 65 72 2c 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a  er, a pointer.**
8320: 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 74 72   to an empty str
8330: 69 6e 67 2c 20 6f 72 20 61 20 70 6f 69 6e 74 65  ing, or a pointe
8340: 72 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 73 20  r that contains 
8350: 6f 6e 6c 79 20 77 68 69 74 65 73 70 61 63 65 20  only whitespace 
8360: 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53 51 4c 20 63  and/or .** SQL c
8370: 6f 6d 6d 65 6e 74 73 2c 20 74 68 65 6e 20 6e 6f  omments, then no
8380: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
8390: 61 72 65 20 65 76 61 6c 75 61 74 65 64 20 61 6e  are evaluated an
83a0: 64 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  d the database.*
83b0: 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64  * is not changed
83c0: 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74 72 69 63 74  ..**.** Restrict
83d0: 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ions:.**.** <ul>
83e0: 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70  .** <li> The app
83f0: 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 69 6e  lication must in
8400: 73 75 72 65 20 74 68 61 74 20 74 68 65 20 31 73  sure that the 1s
8410: 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  t parameter to s
8420: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a  qlite3_exec().**
8430: 20 20 20 20 20 20 69 73 20 61 20 76 61 6c 69 64        is a valid
8440: 20 61 6e 64 20 6f 70 65 6e 20 5b 64 61 74 61 62   and open [datab
8450: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e  ase connection].
8460: 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70  .** <li> The app
8470: 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  lication must no
8480: 74 20 63 6c 6f 73 65 20 5b 64 61 74 61 62 61 73  t close [databas
8490: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70  e connection] sp
84a0: 65 63 69 66 69 65 64 20 62 79 0a 2a 2a 20 20 20  ecified by.**   
84b0: 20 20 20 74 68 65 20 31 73 74 20 70 61 72 61 6d     the 1st param
84c0: 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
84d0: 65 78 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c  exec() while sql
84e0: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 72  ite3_exec() is r
84f0: 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 6c 69 3e 20  unning..** <li> 
8500: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
8510: 6d 75 73 74 20 6e 6f 74 20 6d 6f 64 69 66 79 20  must not modify 
8520: 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
8530: 74 20 74 65 78 74 20 70 61 73 73 65 64 20 69 6e  t text passed in
8540: 74 6f 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 32  to.**      the 2
8550: 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  nd parameter of 
8560: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77  sqlite3_exec() w
8570: 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65  hile sqlite3_exe
8580: 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  c() is running..
8590: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 53 51 4c 49  ** </ul>.*/.SQLI
85a0: 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
85b0: 65 33 5f 65 78 65 63 28 0a 20 20 73 71 6c 69 74  e3_exec(.  sqlit
85c0: 65 33 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20  e3*,            
85d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
85e0: 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e        /* An open
85f0: 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63   database */.  c
8600: 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 2c 20  onst char *sql, 
8610: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
8620: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c            /* SQL
8630: 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64   to be evaluated
8640: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c   */.  int (*call
8650: 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c  back)(void*,int,
8660: 63 68 61 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20  char**,char**), 
8670: 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e   /* Callback fun
8680: 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20  ction */.  void 
8690: 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  *,              
86a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
86b0: 20 20 20 20 20 20 2f 2a 20 31 73 74 20 61 72 67        /* 1st arg
86c0: 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63  ument to callbac
86d0: 6b 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72  k */.  char **er
86e0: 72 6d 73 67 20 20 20 20 20 20 20 20 20 20 20 20  rmsg            
86f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
8700: 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77    /* Error msg w
8710: 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29  ritten here */.)
8720: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
8730: 46 3a 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a  F: Result Codes.
8740: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c  ** KEYWORDS: SQL
8750: 49 54 45 5f 4f 4b 20 7b 65 72 72 6f 72 20 63 6f  ITE_OK {error co
8760: 64 65 7d 20 7b 65 72 72 6f 72 20 63 6f 64 65 73  de} {error codes
8770: 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  }.** KEYWORDS: {
8780: 72 65 73 75 6c 74 20 63 6f 64 65 7d 20 7b 72 65  result code} {re
8790: 73 75 6c 74 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a  sult codes}.**.*
87a0: 2a 20 4d 61 6e 79 20 53 51 4c 69 74 65 20 66 75  * Many SQLite fu
87b0: 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 61  nctions return a
87c0: 6e 20 69 6e 74 65 67 65 72 20 72 65 73 75 6c 74  n integer result
87d0: 20 63 6f 64 65 20 66 72 6f 6d 20 74 68 65 20 73   code from the s
87e0: 65 74 20 73 68 6f 77 6e 0a 2a 2a 20 68 65 72 65  et shown.** here
87f0: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e 64   in order to ind
8800: 69 63 61 74 65 73 20 73 75 63 63 65 73 73 20 6f  icates success o
8810: 72 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a  r failure..**.**
8820: 20 4e 65 77 20 65 72 72 6f 72 20 63 6f 64 65 73   New error codes
8830: 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
8840: 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   future versions
8850: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a   of SQLite..**.*
8860: 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c  * See also: [SQL
8870: 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c  ITE_IOERR_READ |
8880: 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
8890: 20 63 6f 64 65 73 5d 2c 0a 2a 2a 20 5b 73 71 6c   codes],.** [sql
88a0: 69 74 65 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e  ite3_vtab_on_con
88b0: 66 6c 69 63 74 28 29 5d 20 5b 53 51 4c 49 54 45  flict()] [SQLITE
88c0: 5f 52 4f 4c 4c 42 41 43 4b 20 7c 20 72 65 73 75  _ROLLBACK | resu
88d0: 6c 74 20 63 6f 64 65 73 5d 2e 0a 2a 2f 0a 23 64  lt codes]..*/.#d
88e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 4b 20  efine SQLITE_OK 
88f0: 20 20 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a            0   /*
8900: 20 53 75 63 63 65 73 73 66 75 6c 20 72 65 73 75   Successful resu
8910: 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67 69 6e 6e 69  lt */./* beginni
8920: 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65  ng-of-error-code
8930: 73 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  s */.#define SQL
8940: 49 54 45 5f 45 52 52 4f 52 20 20 20 20 20 20 20  ITE_ERROR       
8950: 20 31 20 20 20 2f 2a 20 53 51 4c 20 65 72 72 6f   1   /* SQL erro
8960: 72 20 6f 72 20 6d 69 73 73 69 6e 67 20 64 61 74  r or missing dat
8970: 61 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65  abase */.#define
8980: 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 4e 41 4c   SQLITE_INTERNAL
8990: 20 20 20 20 20 32 20 20 20 2f 2a 20 49 6e 74 65       2   /* Inte
89a0: 72 6e 61 6c 20 6c 6f 67 69 63 20 65 72 72 6f 72  rnal logic error
89b0: 20 69 6e 20 53 51 4c 69 74 65 20 2a 2f 0a 23 64   in SQLite */.#d
89c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 45 52  efine SQLITE_PER
89d0: 4d 20 20 20 20 20 20 20 20 20 33 20 20 20 2f 2a  M         3   /*
89e0: 20 41 63 63 65 73 73 20 70 65 72 6d 69 73 73 69   Access permissi
89f0: 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65  on denied */.#de
8a00: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 42 4f 52  fine SQLITE_ABOR
8a10: 54 20 20 20 20 20 20 20 20 34 20 20 20 2f 2a 20  T        4   /* 
8a20: 43 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65  Callback routine
8a30: 20 72 65 71 75 65 73 74 65 64 20 61 6e 20 61 62   requested an ab
8a40: 6f 72 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ort */.#define S
8a50: 51 4c 49 54 45 5f 42 55 53 59 20 20 20 20 20 20  QLITE_BUSY      
8a60: 20 20 20 35 20 20 20 2f 2a 20 54 68 65 20 64 61     5   /* The da
8a70: 74 61 62 61 73 65 20 66 69 6c 65 20 69 73 20 6c  tabase file is l
8a80: 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  ocked */.#define
8a90: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 20   SQLITE_LOCKED  
8aa0: 20 20 20 20 20 36 20 20 20 2f 2a 20 41 20 74 61       6   /* A ta
8ab0: 62 6c 65 20 69 6e 20 74 68 65 20 64 61 74 61 62  ble in the datab
8ac0: 61 73 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f  ase is locked */
8ad0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
8ae0: 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 37 20 20  NOMEM        7  
8af0: 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63 28 29 20 66   /* A malloc() f
8b00: 61 69 6c 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  ailed */.#define
8b10: 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59   SQLITE_READONLY
8b20: 20 20 20 20 20 38 20 20 20 2f 2a 20 41 74 74 65       8   /* Atte
8b30: 6d 70 74 20 74 6f 20 77 72 69 74 65 20 61 20 72  mpt to write a r
8b40: 65 61 64 6f 6e 6c 79 20 64 61 74 61 62 61 73 65  eadonly database
8b50: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
8b60: 54 45 5f 49 4e 54 45 52 52 55 50 54 20 20 20 20  TE_INTERRUPT    
8b70: 39 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e  9   /* Operation
8b80: 20 74 65 72 6d 69 6e 61 74 65 64 20 62 79 20 73   terminated by s
8b90: 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
8ba0: 28 29 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ()*/.#define SQL
8bb0: 49 54 45 5f 49 4f 45 52 52 20 20 20 20 20 20 20  ITE_IOERR       
8bc0: 31 30 20 20 20 2f 2a 20 53 6f 6d 65 20 6b 69 6e  10   /* Some kin
8bd0: 64 20 6f 66 20 64 69 73 6b 20 49 2f 4f 20 65 72  d of disk I/O er
8be0: 72 6f 72 20 6f 63 63 75 72 72 65 64 20 2a 2f 0a  ror occurred */.
8bf0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
8c00: 4f 52 52 55 50 54 20 20 20 20 20 31 31 20 20 20  ORRUPT     11   
8c10: 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20  /* The database 
8c20: 64 69 73 6b 20 69 6d 61 67 65 20 69 73 20 6d 61  disk image is ma
8c30: 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23 64 65 66 69  lformed */.#defi
8c40: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55  ne SQLITE_NOTFOU
8c50: 4e 44 20 20 20 20 31 32 20 20 20 2f 2a 20 55 6e  ND    12   /* Un
8c60: 6b 6e 6f 77 6e 20 6f 70 63 6f 64 65 20 69 6e 20  known opcode in 
8c70: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
8c80: 74 72 6f 6c 28 29 20 2a 2f 0a 23 64 65 66 69 6e  trol() */.#defin
8c90: 65 20 53 51 4c 49 54 45 5f 46 55 4c 4c 20 20 20  e SQLITE_FULL   
8ca0: 20 20 20 20 20 31 33 20 20 20 2f 2a 20 49 6e 73       13   /* Ins
8cb0: 65 72 74 69 6f 6e 20 66 61 69 6c 65 64 20 62 65  ertion failed be
8cc0: 63 61 75 73 65 20 64 61 74 61 62 61 73 65 20 69  cause database i
8cd0: 73 20 66 75 6c 6c 20 2a 2f 0a 23 64 65 66 69 6e  s full */.#defin
8ce0: 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45  e SQLITE_CANTOPE
8cf0: 4e 20 20 20 20 31 34 20 20 20 2f 2a 20 55 6e 61  N    14   /* Una
8d00: 62 6c 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 20  ble to open the 
8d10: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f  database file */
8d20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
8d30: 50 52 4f 54 4f 43 4f 4c 20 20 20 20 31 35 20 20  PROTOCOL    15  
8d40: 20 2f 2a 20 44 61 74 61 62 61 73 65 20 6c 6f 63   /* Database loc
8d50: 6b 20 70 72 6f 74 6f 63 6f 6c 20 65 72 72 6f 72  k protocol error
8d60: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
8d70: 54 45 5f 45 4d 50 54 59 20 20 20 20 20 20 20 31  TE_EMPTY       1
8d80: 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  6   /* Database 
8d90: 69 73 20 65 6d 70 74 79 20 2a 2f 0a 23 64 65 66  is empty */.#def
8da0: 69 6e 65 20 53 51 4c 49 54 45 5f 53 43 48 45 4d  ine SQLITE_SCHEM
8db0: 41 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20 54  A      17   /* T
8dc0: 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65  he database sche
8dd0: 6d 61 20 63 68 61 6e 67 65 64 20 2a 2f 0a 23 64  ma changed */.#d
8de0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 4f 4f  efine SQLITE_TOO
8df0: 42 49 47 20 20 20 20 20 20 31 38 20 20 20 2f 2a  BIG      18   /*
8e00: 20 53 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20   String or BLOB 
8e10: 65 78 63 65 65 64 73 20 73 69 7a 65 20 6c 69 6d  exceeds size lim
8e20: 69 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  it */.#define SQ
8e30: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
8e40: 20 31 39 20 20 20 2f 2a 20 41 62 6f 72 74 20 64   19   /* Abort d
8e50: 75 65 20 74 6f 20 63 6f 6e 73 74 72 61 69 6e 74  ue to constraint
8e60: 20 76 69 6f 6c 61 74 69 6f 6e 20 2a 2f 0a 23 64   violation */.#d
8e70: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53  efine SQLITE_MIS
8e80: 4d 41 54 43 48 20 20 20 20 32 30 20 20 20 2f 2a  MATCH    20   /*
8e90: 20 44 61 74 61 20 74 79 70 65 20 6d 69 73 6d 61   Data type misma
8ea0: 74 63 68 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  tch */.#define S
8eb0: 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 20 20 20  QLITE_MISUSE    
8ec0: 20 20 32 31 20 20 20 2f 2a 20 4c 69 62 72 61 72    21   /* Librar
8ed0: 79 20 75 73 65 64 20 69 6e 63 6f 72 72 65 63 74  y used incorrect
8ee0: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
8ef0: 4c 49 54 45 5f 4e 4f 4c 46 53 20 20 20 20 20 20  LITE_NOLFS      
8f00: 20 32 32 20 20 20 2f 2a 20 55 73 65 73 20 4f 53   22   /* Uses OS
8f10: 20 66 65 61 74 75 72 65 73 20 6e 6f 74 20 73 75   features not su
8f20: 70 70 6f 72 74 65 64 20 6f 6e 20 68 6f 73 74 20  pported on host 
8f30: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
8f40: 45 5f 41 55 54 48 20 20 20 20 20 20 20 20 32 33  E_AUTH        23
8f50: 20 20 20 2f 2a 20 41 75 74 68 6f 72 69 7a 61 74     /* Authorizat
8f60: 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64  ion denied */.#d
8f70: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4f 52  efine SQLITE_FOR
8f80: 4d 41 54 20 20 20 20 20 20 32 34 20 20 20 2f 2a  MAT      24   /*
8f90: 20 41 75 78 69 6c 69 61 72 79 20 64 61 74 61 62   Auxiliary datab
8fa0: 61 73 65 20 66 6f 72 6d 61 74 20 65 72 72 6f 72  ase format error
8fb0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
8fc0: 54 45 5f 52 41 4e 47 45 20 20 20 20 20 20 20 32  TE_RANGE       2
8fd0: 35 20 20 20 2f 2a 20 32 6e 64 20 70 61 72 61 6d  5   /* 2nd param
8fe0: 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
8ff0: 62 69 6e 64 20 6f 75 74 20 6f 66 20 72 61 6e 67  bind out of rang
9000: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
9010: 49 54 45 5f 4e 4f 54 41 44 42 20 20 20 20 20 20  ITE_NOTADB      
9020: 32 36 20 20 20 2f 2a 20 46 69 6c 65 20 6f 70 65  26   /* File ope
9030: 6e 65 64 20 74 68 61 74 20 69 73 20 6e 6f 74 20  ned that is not 
9040: 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  a database file 
9050: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
9060: 45 5f 52 4f 57 20 20 20 20 20 20 20 20 20 31 30  E_ROW         10
9070: 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74  0  /* sqlite3_st
9080: 65 70 28 29 20 68 61 73 20 61 6e 6f 74 68 65 72  ep() has another
9090: 20 72 6f 77 20 72 65 61 64 79 20 2a 2f 0a 23 64   row ready */.#d
90a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 4f 4e  efine SQLITE_DON
90b0: 45 20 20 20 20 20 20 20 20 31 30 31 20 20 2f 2a  E        101  /*
90c0: 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
90d0: 68 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 65  has finished exe
90e0: 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64  cuting */./* end
90f0: 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20  -of-error-codes 
9100: 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
9110: 45 46 3a 20 45 78 74 65 6e 64 65 64 20 52 65 73  EF: Extended Res
9120: 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59  ult Codes.** KEY
9130: 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64 65 64  WORDS: {extended
9140: 20 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65 78   error code} {ex
9150: 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64  tended error cod
9160: 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  es}.** KEYWORDS:
9170: 20 7b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   {extended resul
9180: 74 20 63 6f 64 65 7d 20 7b 65 78 74 65 6e 64 65  t code} {extende
9190: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 7d 0a  d result codes}.
91a0: 2a 2a 0a 2a 2a 20 49 6e 20 69 74 73 20 64 65 66  **.** In its def
91b0: 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69  ault configurati
91c0: 6f 6e 2c 20 53 51 4c 69 74 65 20 41 50 49 20 72  on, SQLite API r
91d0: 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 6f  outines return o
91e0: 6e 65 20 6f 66 20 32 36 20 69 6e 74 65 67 65 72  ne of 26 integer
91f0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 20 7c  .** [SQLITE_OK |
9200: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 2e 20   result codes]. 
9210: 20 48 6f 77 65 76 65 72 2c 20 65 78 70 65 72 69   However, experi
9220: 65 6e 63 65 20 68 61 73 20 73 68 6f 77 6e 20 74  ence has shown t
9230: 68 61 74 20 6d 61 6e 79 20 6f 66 0a 2a 2a 20 74  hat many of.** t
9240: 68 65 73 65 20 72 65 73 75 6c 74 20 63 6f 64 65  hese result code
9250: 73 20 61 72 65 20 74 6f 6f 20 63 6f 61 72 73 65  s are too coarse
9260: 2d 67 72 61 69 6e 65 64 2e 20 20 54 68 65 79 20  -grained.  They 
9270: 64 6f 20 6e 6f 74 20 70 72 6f 76 69 64 65 20 61  do not provide a
9280: 73 0a 2a 2a 20 6d 75 63 68 20 69 6e 66 6f 72 6d  s.** much inform
9290: 61 74 69 6f 6e 20 61 62 6f 75 74 20 70 72 6f 62  ation about prob
92a0: 6c 65 6d 73 20 61 73 20 70 72 6f 67 72 61 6d 6d  lems as programm
92b0: 65 72 73 20 6d 69 67 68 74 20 6c 69 6b 65 2e 20  ers might like. 
92c0: 20 49 6e 20 61 6e 20 65 66 66 6f 72 74 20 74 6f   In an effort to
92d0: 0a 2a 2a 20 61 64 64 72 65 73 73 20 74 68 69 73  .** address this
92e0: 2c 20 6e 65 77 65 72 20 76 65 72 73 69 6f 6e 73  , newer versions
92f0: 20 6f 66 20 53 51 4c 69 74 65 20 28 76 65 72 73   of SQLite (vers
9300: 69 6f 6e 20 33 2e 33 2e 38 20 61 6e 64 20 6c 61  ion 3.3.8 and la
9310: 74 65 72 29 20 69 6e 63 6c 75 64 65 0a 2a 2a 20  ter) include.** 
9320: 73 75 70 70 6f 72 74 20 66 6f 72 20 61 64 64 69  support for addi
9330: 74 69 6f 6e 61 6c 20 72 65 73 75 6c 74 20 63 6f  tional result co
9340: 64 65 73 20 74 68 61 74 20 70 72 6f 76 69 64 65  des that provide
9350: 20 6d 6f 72 65 20 64 65 74 61 69 6c 65 64 20 69   more detailed i
9360: 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62  nformation.** ab
9370: 6f 75 74 20 65 72 72 6f 72 73 2e 20 54 68 65 20  out errors. The 
9380: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
9390: 63 6f 64 65 73 20 61 72 65 20 65 6e 61 62 6c 65  codes are enable
93a0: 64 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a  d or disabled.**
93b0: 20 6f 6e 20 61 20 70 65 72 20 64 61 74 61 62 61   on a per databa
93c0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61  se connection ba
93d0: 73 69 73 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a  sis using the.**
93e0: 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64   [sqlite3_extend
93f0: 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28  ed_result_codes(
9400: 29 5d 20 41 50 49 2e 0a 2a 2a 0a 2a 2a 20 53 6f  )] API..**.** So
9410: 6d 65 20 6f 66 20 74 68 65 20 61 76 61 69 6c 61  me of the availa
9420: 62 6c 65 20 65 78 74 65 6e 64 65 64 20 72 65 73  ble extended res
9430: 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 6c 69  ult codes are li
9440: 73 74 65 64 20 68 65 72 65 2e 0a 2a 2a 20 4f 6e  sted here..** On
9450: 65 20 6d 61 79 20 65 78 70 65 63 74 20 74 68 65  e may expect the
9460: 20 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 65 6e   number of exten
9470: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
9480: 20 77 69 6c 6c 20 62 65 20 65 78 70 61 6e 64 0a   will be expand.
9490: 2a 2a 20 6f 76 65 72 20 74 69 6d 65 2e 20 20 53  ** over time.  S
94a0: 6f 66 74 77 61 72 65 20 74 68 61 74 20 75 73 65  oftware that use
94b0: 73 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c  s extended resul
94c0: 74 20 63 6f 64 65 73 20 73 68 6f 75 6c 64 20 65  t codes should e
94d0: 78 70 65 63 74 0a 2a 2a 20 74 6f 20 73 65 65 20  xpect.** to see 
94e0: 6e 65 77 20 72 65 73 75 6c 74 20 63 6f 64 65 73  new result codes
94f0: 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
9500: 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ses of SQLite..*
9510: 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f  *.** The SQLITE_
9520: 4f 4b 20 72 65 73 75 6c 74 20 63 6f 64 65 20 77  OK result code w
9530: 69 6c 6c 20 6e 65 76 65 72 20 62 65 20 65 78 74  ill never be ext
9540: 65 6e 64 65 64 2e 20 20 49 74 20 77 69 6c 6c 20  ended.  It will 
9550: 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20 65 78 61  always.** be exa
9560: 63 74 6c 79 20 7a 65 72 6f 2e 0a 2a 2f 0a 23 64  ctly zero..*/.#d
9570: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
9580: 52 52 5f 52 45 41 44 20 20 20 20 20 20 20 20 20  RR_READ         
9590: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
95a0: 52 52 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65  RR | (1<<8)).#de
95b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
95c0: 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 20 20 20  R_SHORT_READ    
95d0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
95e0: 52 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66  R | (2<<8)).#def
95f0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
9600: 5f 57 52 49 54 45 20 20 20 20 20 20 20 20 20 20  _WRITE          
9610: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
9620: 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69   | (3<<8)).#defi
9630: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
9640: 46 53 59 4e 43 20 20 20 20 20 20 20 20 20 20 20  FSYNC           
9650: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
9660: 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (4<<8)).#defin
9670: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44  e SQLITE_IOERR_D
9680: 49 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20  IR_FSYNC        
9690: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
96a0: 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (5<<8)).#define
96b0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 54 52   SQLITE_IOERR_TR
96c0: 55 4e 43 41 54 45 20 20 20 20 20 20 20 20 20 20  UNCATE          
96d0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
96e0: 28 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (6<<8)).#define 
96f0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 54  SQLITE_IOERR_FST
9700: 41 54 20 20 20 20 20 20 20 20 20 20 20 20 20 28  AT             (
9710: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
9720: 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  7<<8)).#define S
9730: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 55 4e 4c 4f  QLITE_IOERR_UNLO
9740: 43 4b 20 20 20 20 20 20 20 20 20 20 20 20 28 53  CK            (S
9750: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 38  QLITE_IOERR | (8
9760: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
9770: 4c 49 54 45 5f 49 4f 45 52 52 5f 52 44 4c 4f 43  LITE_IOERR_RDLOC
9780: 4b 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51  K            (SQ
9790: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 39 3c  LITE_IOERR | (9<
97a0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
97b0: 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45  ITE_IOERR_DELETE
97c0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
97d0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 30 3c  ITE_IOERR | (10<
97e0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
97f0: 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45  ITE_IOERR_BLOCKE
9800: 44 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  D           (SQL
9810: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 31 3c  ITE_IOERR | (11<
9820: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
9830: 49 54 45 5f 49 4f 45 52 52 5f 4e 4f 4d 45 4d 20  ITE_IOERR_NOMEM 
9840: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
9850: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 32 3c  ITE_IOERR | (12<
9860: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
9870: 49 54 45 5f 49 4f 45 52 52 5f 41 43 43 45 53 53  ITE_IOERR_ACCESS
9880: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
9890: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 33 3c  ITE_IOERR | (13<
98a0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
98b0: 49 54 45 5f 49 4f 45 52 52 5f 43 48 45 43 4b 52  ITE_IOERR_CHECKR
98c0: 45 53 45 52 56 45 44 4c 4f 43 4b 20 28 53 51 4c  ESERVEDLOCK (SQL
98d0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 34 3c  ITE_IOERR | (14<
98e0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
98f0: 49 54 45 5f 49 4f 45 52 52 5f 4c 4f 43 4b 20 20  ITE_IOERR_LOCK  
9900: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
9910: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 35 3c  ITE_IOERR | (15<
9920: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
9930: 49 54 45 5f 49 4f 45 52 52 5f 43 4c 4f 53 45 20  ITE_IOERR_CLOSE 
9940: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
9950: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 36 3c  ITE_IOERR | (16<
9960: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
9970: 49 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f 43 4c  ITE_IOERR_DIR_CL
9980: 4f 53 45 20 20 20 20 20 20 20 20 20 28 53 51 4c  OSE         (SQL
9990: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 37 3c  ITE_IOERR | (17<
99a0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
99b0: 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4f 50 45  ITE_IOERR_SHMOPE
99c0: 4e 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  N           (SQL
99d0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 38 3c  ITE_IOERR | (18<
99e0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
99f0: 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 53 49 5a  ITE_IOERR_SHMSIZ
9a00: 45 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  E           (SQL
9a10: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 39 3c  ITE_IOERR | (19<
9a20: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
9a30: 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4c 4f 43  ITE_IOERR_SHMLOC
9a40: 4b 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  K           (SQL
9a50: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 30 3c  ITE_IOERR | (20<
9a60: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
9a70: 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4d 41 50  ITE_IOERR_SHMMAP
9a80: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
9a90: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 31 3c  ITE_IOERR | (21<
9aa0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
9ab0: 49 54 45 5f 49 4f 45 52 52 5f 53 45 45 4b 20 20  ITE_IOERR_SEEK  
9ac0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
9ad0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 32 3c  ITE_IOERR | (22<
9ae0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
9af0: 49 54 45 5f 4c 4f 43 4b 45 44 5f 53 48 41 52 45  ITE_LOCKED_SHARE
9b00: 44 43 41 43 48 45 20 20 20 20 20 20 28 53 51 4c  DCACHE      (SQL
9b10: 49 54 45 5f 4c 4f 43 4b 45 44 20 7c 20 20 28 31  ITE_LOCKED |  (1
9b20: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
9b30: 4c 49 54 45 5f 42 55 53 59 5f 52 45 43 4f 56 45  LITE_BUSY_RECOVE
9b40: 52 59 20 20 20 20 20 20 20 20 20 20 20 28 53 51  RY           (SQ
9b50: 4c 49 54 45 5f 42 55 53 59 20 20 20 7c 20 20 28  LITE_BUSY   |  (
9b60: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
9b70: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 4e  QLITE_CANTOPEN_N
9b80: 4f 54 45 4d 50 44 49 52 20 20 20 20 20 20 28 53  OTEMPDIR      (S
9b90: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c  QLITE_CANTOPEN |
9ba0: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (1<<8)).#define
9bb0: 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5f   SQLITE_CORRUPT_
9bc0: 56 54 41 42 20 20 20 20 20 20 20 20 20 20 20 20  VTAB            
9bd0: 28 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20  (SQLITE_CORRUPT 
9be0: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
9bf0: 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c  e SQLITE_READONL
9c00: 59 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20  Y_RECOVERY      
9c10: 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c   (SQLITE_READONL
9c20: 59 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66  Y | (1<<8)).#def
9c30: 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f  ine SQLITE_READO
9c40: 4e 4c 59 5f 43 41 4e 54 4c 4f 43 4b 20 20 20 20  NLY_CANTLOCK    
9c50: 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f     (SQLITE_READO
9c60: 4e 4c 59 20 7c 20 28 32 3c 3c 38 29 29 0a 0a 2f  NLY | (2<<8))../
9c70: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
9c80: 6c 61 67 73 20 46 6f 72 20 46 69 6c 65 20 4f 70  lags For File Op
9c90: 65 6e 20 4f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a  en Operations.**
9ca0: 0a 2a 2a 20 54 68 65 73 65 20 62 69 74 20 76 61  .** These bit va
9cb0: 6c 75 65 73 20 61 72 65 20 69 6e 74 65 6e 64 65  lues are intende
9cc0: 64 20 66 6f 72 20 75 73 65 20 69 6e 20 74 68 65  d for use in the
9cd0: 0a 2a 2a 20 33 72 64 20 70 61 72 61 6d 65 74 65  .** 3rd paramete
9ce0: 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  r to the [sqlite
9cf0: 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74  3_open_v2()] int
9d00: 65 72 66 61 63 65 20 61 6e 64 0a 2a 2a 20 69 6e  erface and.** in
9d10: 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74   the 4th paramet
9d20: 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  er to the [sqlit
9d30: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65  e3_vfs.xOpen] me
9d40: 74 68 6f 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  thod..*/.#define
9d50: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41   SQLITE_OPEN_REA
9d60: 44 4f 4e 4c 59 20 20 20 20 20 20 20 20 20 30 78  DONLY         0x
9d70: 30 30 30 30 30 30 30 31 20 20 2f 2a 20 4f 6b 20  00000001  /* Ok 
9d80: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
9d90: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
9da0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41   SQLITE_OPEN_REA
9db0: 44 57 52 49 54 45 20 20 20 20 20 20 20 20 30 78  DWRITE        0x
9dc0: 30 30 30 30 30 30 30 32 20 20 2f 2a 20 4f 6b 20  00000002  /* Ok 
9dd0: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
9de0: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
9df0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45   SQLITE_OPEN_CRE
9e00: 41 54 45 20 20 20 20 20 20 20 20 20 20 20 30 78  ATE           0x
9e10: 30 30 30 30 30 30 30 34 20 20 2f 2a 20 4f 6b 20  00000004  /* Ok 
9e20: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
9e30: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
9e40: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c   SQLITE_OPEN_DEL
9e50: 45 54 45 4f 4e 43 4c 4f 53 45 20 20 20 20 30 78  ETEONCLOSE    0x
9e60: 30 30 30 30 30 30 30 38 20 20 2f 2a 20 56 46 53  00000008  /* VFS
9e70: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
9e80: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43   SQLITE_OPEN_EXC
9e90: 4c 55 53 49 56 45 20 20 20 20 20 20 20 20 30 78  LUSIVE        0x
9ea0: 30 30 30 30 30 30 31 30 20 20 2f 2a 20 56 46 53  00000010  /* VFS
9eb0: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
9ec0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 41 55 54   SQLITE_OPEN_AUT
9ed0: 4f 50 52 4f 58 59 20 20 20 20 20 20 20 20 30 78  OPROXY        0x
9ee0: 30 30 30 30 30 30 32 30 20 20 2f 2a 20 56 46 53  00000020  /* VFS
9ef0: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
9f00: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49   SQLITE_OPEN_URI
9f10: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
9f20: 30 30 30 30 30 30 34 30 20 20 2f 2a 20 4f 6b 20  00000040  /* Ok 
9f30: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
9f40: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
9f50: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49   SQLITE_OPEN_MAI
9f60: 4e 5f 44 42 20 20 20 20 20 20 20 20 20 20 30 78  N_DB          0x
9f70: 30 30 30 30 30 31 30 30 20 20 2f 2a 20 56 46 53  00000100  /* VFS
9f80: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
9f90: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d   SQLITE_OPEN_TEM
9fa0: 50 5f 44 42 20 20 20 20 20 20 20 20 20 20 30 78  P_DB          0x
9fb0: 30 30 30 30 30 32 30 30 20 20 2f 2a 20 56 46 53  00000200  /* VFS
9fc0: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
9fd0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41   SQLITE_OPEN_TRA
9fe0: 4e 53 49 45 4e 54 5f 44 42 20 20 20 20 20 30 78  NSIENT_DB     0x
9ff0: 30 30 30 30 30 34 30 30 20 20 2f 2a 20 56 46 53  00000400  /* VFS
a000: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
a010: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49   SQLITE_OPEN_MAI
a020: 4e 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78  N_JOURNAL     0x
a030: 30 30 30 30 30 38 30 30 20 20 2f 2a 20 56 46 53  00000800  /* VFS
a040: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
a050: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d   SQLITE_OPEN_TEM
a060: 50 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78  P_JOURNAL     0x
a070: 30 30 30 30 31 30 30 30 20 20 2f 2a 20 56 46 53  00001000  /* VFS
a080: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
a090: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42   SQLITE_OPEN_SUB
a0a0: 4a 4f 55 52 4e 41 4c 20 20 20 20 20 20 20 30 78  JOURNAL       0x
a0b0: 30 30 30 30 32 30 30 30 20 20 2f 2a 20 56 46 53  00002000  /* VFS
a0c0: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
a0d0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53   SQLITE_OPEN_MAS
a0e0: 54 45 52 5f 4a 4f 55 52 4e 41 4c 20 20 20 30 78  TER_JOURNAL   0x
a0f0: 30 30 30 30 34 30 30 30 20 20 2f 2a 20 56 46 53  00004000  /* VFS
a100: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
a110: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d   SQLITE_OPEN_NOM
a120: 55 54 45 58 20 20 20 20 20 20 20 20 20 20 30 78  UTEX          0x
a130: 30 30 30 30 38 30 30 30 20 20 2f 2a 20 4f 6b 20  00008000  /* Ok 
a140: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
a150: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
a160: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c   SQLITE_OPEN_FUL
a170: 4c 4d 55 54 45 58 20 20 20 20 20 20 20 20 30 78  LMUTEX        0x
a180: 30 30 30 31 30 30 30 30 20 20 2f 2a 20 4f 6b 20  00010000  /* Ok 
a190: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
a1a0: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
a1b0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41   SQLITE_OPEN_SHA
a1c0: 52 45 44 43 41 43 48 45 20 20 20 20 20 20 30 78  REDCACHE      0x
a1d0: 30 30 30 32 30 30 30 30 20 20 2f 2a 20 4f 6b 20  00020000  /* Ok 
a1e0: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
a1f0: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
a200: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49   SQLITE_OPEN_PRI
a210: 56 41 54 45 43 41 43 48 45 20 20 20 20 20 30 78  VATECACHE     0x
a220: 30 30 30 34 30 30 30 30 20 20 2f 2a 20 4f 6b 20  00040000  /* Ok 
a230: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
a240: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
a250: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c   SQLITE_OPEN_WAL
a260: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
a270: 30 30 30 38 30 30 30 30 20 20 2f 2a 20 56 46 53  00080000  /* VFS
a280: 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 20 52 65 73   only */../* Res
a290: 65 72 76 65 64 3a 20 20 20 20 20 20 20 20 20 20  erved:          
a2a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
a2b0: 78 30 30 46 30 30 30 30 30 20 2a 2f 0a 0a 2f 2a  x00F00000 */../*
a2c0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
a2d0: 76 69 63 65 20 43 68 61 72 61 63 74 65 72 69 73  vice Characteris
a2e0: 74 69 63 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  tics.**.** The x
a2f0: 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69  DeviceCharacteri
a300: 73 74 69 63 73 20 6d 65 74 68 6f 64 20 6f 66 20  stics method of 
a310: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  the [sqlite3_io_
a320: 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65  methods].** obje
a330: 63 74 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e  ct returns an in
a340: 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20 61  teger which is a
a350: 20 76 65 63 74 6f 72 20 6f 66 20 74 68 65 20 74   vector of the t
a360: 68 65 73 65 0a 2a 2a 20 62 69 74 20 76 61 6c 75  hese.** bit valu
a370: 65 73 20 65 78 70 72 65 73 73 69 6e 67 20 49 2f  es expressing I/
a380: 4f 20 63 68 61 72 61 63 74 65 72 69 73 74 69 63  O characteristic
a390: 73 20 6f 66 20 74 68 65 20 6d 61 73 73 20 73 74  s of the mass st
a3a0: 6f 72 61 67 65 0a 2a 2a 20 64 65 76 69 63 65 20  orage.** device 
a3b0: 74 68 61 74 20 68 6f 6c 64 73 20 74 68 65 20 66  that holds the f
a3c0: 69 6c 65 20 74 68 61 74 20 74 68 65 20 5b 73 71  ile that the [sq
a3d0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
a3e0: 5d 0a 2a 2a 20 72 65 66 65 72 73 20 74 6f 2e 0a  ].** refers to..
a3f0: 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  **.** The SQLITE
a400: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72  _IOCAP_ATOMIC pr
a410: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61  operty means tha
a420: 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a  t all writes of.
a430: 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20  ** any size are 
a440: 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c  atomic.  The SQL
a450: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
a460: 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65  nnn values.** me
a470: 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 20 6f  an that writes o
a480: 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72  f blocks that ar
a490: 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73  e nnn bytes in s
a4a0: 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61  ize and.** are a
a4b0: 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64  ligned to an add
a4c0: 72 65 73 73 20 77 68 69 63 68 20 69 73 20 61 6e  ress which is an
a4d0: 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c   integer multipl
a4e0: 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20  e of.** nnn are 
a4f0: 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c  atomic.  The SQL
a500: 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41  ITE_IOCAP_SAFE_A
a510: 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e  PPEND value mean
a520: 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64  s.** that when d
a530: 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 20  ata is appended 
a540: 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64  to a file, the d
a550: 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a  ata is appended.
a560: 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74 68  ** first then th
a570: 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69  e size of the fi
a580: 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20  le is extended, 
a590: 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a  never the other.
a5a0: 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20  ** way around.  
a5b0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
a5c0: 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70  _SEQUENTIAL prop
a5d0: 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a  erty means that.
a5e0: 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  ** information i
a5f0: 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73  s written to dis
a600: 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72  k in the same or
a610: 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20  der as calls.** 
a620: 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a 2f 0a  to xWrite()..*/.
a630: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
a640: 4f 43 41 50 5f 41 54 4f 4d 49 43 20 20 20 20 20  OCAP_ATOMIC     
a650: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
a660: 30 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53  000001.#define S
a670: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
a680: 49 43 35 31 32 20 20 20 20 20 20 20 20 20 20 20  IC512           
a690: 20 20 20 30 78 30 30 30 30 30 30 30 32 0a 23 64     0x00000002.#d
a6a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
a6b0: 41 50 5f 41 54 4f 4d 49 43 31 4b 20 20 20 20 20  AP_ATOMIC1K     
a6c0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
a6d0: 30 30 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c  0004.#define SQL
a6e0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
a6f0: 32 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  2K              
a700: 20 30 78 30 30 30 30 30 30 30 38 0a 23 64 65 66   0x00000008.#def
a710: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
a720: 5f 41 54 4f 4d 49 43 34 4b 20 20 20 20 20 20 20  _ATOMIC4K       
a730: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
a740: 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  10.#define SQLIT
a750: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b  E_IOCAP_ATOMIC8K
a760: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
a770: 78 30 30 30 30 30 30 32 30 0a 23 64 65 66 69 6e  x00000020.#defin
a780: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
a790: 54 4f 4d 49 43 31 36 4b 20 20 20 20 20 20 20 20  TOMIC16K        
a7a0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 34 30        0x00000040
a7b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
a7c0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20  IOCAP_ATOMIC32K 
a7d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
a7e0: 30 30 30 30 30 38 30 0a 23 64 65 66 69 6e 65 20  0000080.#define 
a7f0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
a800: 4d 49 43 36 34 4b 20 20 20 20 20 20 20 20 20 20  MIC64K          
a810: 20 20 20 20 30 78 30 30 30 30 30 31 30 30 0a 23      0x00000100.#
a820: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
a830: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20  CAP_SAFE_APPEND 
a840: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
a850: 30 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00200.#define SQ
a860: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45  LITE_IOCAP_SEQUE
a870: 4e 54 49 41 4c 20 20 20 20 20 20 20 20 20 20 20  NTIAL           
a880: 20 20 30 78 30 30 30 30 30 34 30 30 0a 23 64 65    0x00000400.#de
a890: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
a8a0: 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48  P_UNDELETABLE_WH
a8b0: 45 4e 5f 4f 50 45 4e 20 20 30 78 30 30 30 30 30  EN_OPEN  0x00000
a8c0: 38 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  800../*.** CAPI3
a8d0: 52 45 46 3a 20 46 69 6c 65 20 4c 6f 63 6b 69 6e  REF: File Lockin
a8e0: 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a 2a 2a 20 53  g Levels.**.** S
a8f0: 51 4c 69 74 65 20 75 73 65 73 20 6f 6e 65 20 6f  QLite uses one o
a900: 66 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20  f these integer 
a910: 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 65  values as the se
a920: 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  cond.** argument
a930: 20 74 6f 20 63 61 6c 6c 73 20 69 74 20 6d 61 6b   to calls it mak
a940: 65 73 20 74 6f 20 74 68 65 20 78 4c 6f 63 6b 28  es to the xLock(
a950: 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20  ) and xUnlock() 
a960: 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e  methods.** of an
a970: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
a980: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f  hods] object..*/
a990: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
a9a0: 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 20 20  LOCK_NONE       
a9b0: 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c     0.#define SQL
a9c0: 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 20  ITE_LOCK_SHARED 
a9d0: 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65         1.#define
a9e0: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53   SQLITE_LOCK_RES
a9f0: 45 52 56 45 44 20 20 20 20 20 20 32 0a 23 64 65  ERVED      2.#de
aa00: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
aa10: 5f 50 45 4e 44 49 4e 47 20 20 20 20 20 20 20 33  _PENDING       3
aa20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
aa30: 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 20 20  LOCK_EXCLUSIVE  
aa40: 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49     4../*.** CAPI
aa50: 33 52 45 46 3a 20 53 79 6e 63 68 72 6f 6e 69 7a  3REF: Synchroniz
aa60: 61 74 69 6f 6e 20 54 79 70 65 20 46 6c 61 67 73  ation Type Flags
aa70: 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 4c 69  .**.** When SQLi
aa80: 74 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 20 78  te invokes the x
aa90: 53 79 6e 63 28 29 20 6d 65 74 68 6f 64 20 6f 66  Sync() method of
aaa0: 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   an.** [sqlite3_
aab0: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
aac0: 63 74 20 69 74 20 75 73 65 73 20 61 20 63 6f 6d  ct it uses a com
aad0: 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74  bination of.** t
aae0: 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c  hese integer val
aaf0: 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e  ues as the secon
ab00: 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  d argument..**.*
ab10: 2a 20 57 68 65 6e 20 74 68 65 20 53 51 4c 49 54  * When the SQLIT
ab20: 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20  E_SYNC_DATAONLY 
ab30: 66 6c 61 67 20 69 73 20 75 73 65 64 2c 20 69 74  flag is used, it
ab40: 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 0a   means that the.
ab50: 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f  ** sync operatio
ab60: 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20  n only needs to 
ab70: 66 6c 75 73 68 20 64 61 74 61 20 74 6f 20 6d 61  flush data to ma
ab80: 73 73 20 73 74 6f 72 61 67 65 2e 20 20 49 6e 6f  ss storage.  Ino
ab90: 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  de.** informatio
aba0: 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 66 6c  n need not be fl
abb0: 75 73 68 65 64 2e 20 49 66 20 74 68 65 20 6c 6f  ushed. If the lo
abc0: 77 65 72 20 66 6f 75 72 20 62 69 74 73 20 6f 66  wer four bits of
abd0: 20 74 68 65 20 66 6c 61 67 0a 2a 2a 20 65 71 75   the flag.** equ
abe0: 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  al SQLITE_SYNC_N
abf0: 4f 52 4d 41 4c 2c 20 74 68 61 74 20 6d 65 61 6e  ORMAL, that mean
ac00: 73 20 74 6f 20 75 73 65 20 6e 6f 72 6d 61 6c 20  s to use normal 
ac10: 66 73 79 6e 63 28 29 20 73 65 6d 61 6e 74 69 63  fsync() semantic
ac20: 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6c 6f 77  s..** If the low
ac30: 65 72 20 66 6f 75 72 20 62 69 74 73 20 65 71 75  er four bits equ
ac40: 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  al SQLITE_SYNC_F
ac50: 55 4c 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a  ULL, that means.
ac60: 2a 2a 20 74 6f 20 75 73 65 20 4d 61 63 20 4f 53  ** to use Mac OS
ac70: 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e   X style fullsyn
ac80: 63 20 69 6e 73 74 65 61 64 20 6f 66 20 66 73 79  c instead of fsy
ac90: 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 44 6f 20 6e  nc()..**.** Do n
aca0: 6f 74 20 63 6f 6e 66 75 73 65 20 74 68 65 20 53  ot confuse the S
acb0: 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41  QLITE_SYNC_NORMA
acc0: 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e  L and SQLITE_SYN
acd0: 43 5f 46 55 4c 4c 20 66 6c 61 67 73 0a 2a 2a 20  C_FULL flags.** 
ace0: 77 69 74 68 20 74 68 65 20 5b 50 52 41 47 4d 41  with the [PRAGMA
acf0: 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 4e 4f   synchronous]=NO
ad00: 52 4d 41 4c 20 61 6e 64 20 5b 50 52 41 47 4d 41  RMAL and [PRAGMA
ad10: 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 46 55   synchronous]=FU
ad20: 4c 4c 0a 2a 2a 20 73 65 74 74 69 6e 67 73 2e 20  LL.** settings. 
ad30: 20 54 68 65 20 5b 73 79 6e 63 68 72 6f 6e 6f 75   The [synchronou
ad40: 73 20 70 72 61 67 6d 61 5d 20 64 65 74 65 72 6d  s pragma] determ
ad50: 69 6e 65 73 20 77 68 65 6e 20 63 61 6c 6c 73 20  ines when calls 
ad60: 74 6f 20 74 68 65 0a 2a 2a 20 78 53 79 6e 63 20  to the.** xSync 
ad70: 56 46 53 20 6d 65 74 68 6f 64 20 6f 63 63 75 72  VFS method occur
ad80: 20 61 6e 64 20 61 70 70 6c 69 65 73 20 75 6e 69   and applies uni
ad90: 66 6f 72 6d 6c 79 20 61 63 72 6f 73 73 20 61 6c  formly across al
ada0: 6c 20 70 6c 61 74 66 6f 72 6d 73 2e 0a 2a 2a 20  l platforms..** 
adb0: 54 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  The SQLITE_SYNC_
adc0: 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54  NORMAL and SQLIT
add0: 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67  E_SYNC_FULL flag
ade0: 73 20 64 65 74 65 72 6d 69 6e 65 20 68 6f 77 0a  s determine how.
adf0: 2a 2a 20 65 6e 65 72 67 65 74 69 63 20 6f 72 20  ** energetic or 
ae00: 72 69 67 6f 72 6f 75 73 20 6f 72 20 66 6f 72 63  rigorous or forc
ae10: 65 66 75 6c 20 74 68 65 20 73 79 6e 63 20 6f 70  eful the sync op
ae20: 65 72 61 74 69 6f 6e 73 20 61 72 65 20 61 6e 64  erations are and
ae30: 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 6b 65 20 61 20  .** only make a 
ae40: 64 69 66 66 65 72 65 6e 63 65 20 6f 6e 20 4d 61  difference on Ma
ae50: 63 20 4f 53 58 20 66 6f 72 20 74 68 65 20 64 65  c OSX for the de
ae60: 66 61 75 6c 74 20 53 51 4c 69 74 65 20 63 6f 64  fault SQLite cod
ae70: 65 2e 0a 2a 2a 20 28 54 68 69 72 64 2d 70 61 72  e..** (Third-par
ae80: 74 79 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  ty VFS implement
ae90: 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 61 6c 73  ations might als
aea0: 6f 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69  o make the disti
aeb0: 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 74 77 65 65  nction.** betwee
aec0: 6e 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f  n SQLITE_SYNC_NO
aed0: 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f  RMAL and SQLITE_
aee0: 53 59 4e 43 5f 46 55 4c 4c 2c 20 62 75 74 20 61  SYNC_FULL, but a
aef0: 6d 6f 6e 67 20 74 68 65 0a 2a 2a 20 6f 70 65 72  mong the.** oper
af00: 61 74 69 6e 67 20 73 79 73 74 65 6d 73 20 6e 61  ating systems na
af10: 74 69 76 65 6c 79 20 73 75 70 70 6f 72 74 65 64  tively supported
af20: 20 62 79 20 53 51 4c 69 74 65 2c 20 6f 6e 6c 79   by SQLite, only
af30: 20 4d 61 63 20 4f 53 58 0a 2a 2a 20 63 61 72 65   Mac OSX.** care
af40: 73 20 61 62 6f 75 74 20 74 68 65 20 64 69 66 66  s about the diff
af50: 65 72 65 6e 63 65 2e 29 0a 2a 2f 0a 23 64 65 66  erence.).*/.#def
af60: 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  ine SQLITE_SYNC_
af70: 4e 4f 52 4d 41 4c 20 20 20 20 20 20 20 20 30 78  NORMAL        0x
af80: 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51  00002.#define SQ
af90: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 20  LITE_SYNC_FULL  
afa0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 33 0a          0x00003.
afb0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
afc0: 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 20 20 20  YNC_DATAONLY    
afd0: 20 20 30 78 30 30 30 31 30 0a 0a 2f 2a 0a 2a 2a    0x00010../*.**
afe0: 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e   CAPI3REF: OS In
aff0: 74 65 72 66 61 63 65 20 4f 70 65 6e 20 46 69 6c  terface Open Fil
b000: 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 41  e Handle.**.** A
b010: 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  n [sqlite3_file]
b020: 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e   object represen
b030: 74 73 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20  ts an open file 
b040: 69 6e 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69  in the .** [sqli
b050: 74 65 33 5f 76 66 73 20 7c 20 4f 53 20 69 6e 74  te3_vfs | OS int
b060: 65 72 66 61 63 65 20 6c 61 79 65 72 5d 2e 20 20  erface layer].  
b070: 49 6e 64 69 76 69 64 75 61 6c 20 4f 53 20 69 6e  Individual OS in
b080: 74 65 72 66 61 63 65 0a 2a 2a 20 69 6d 70 6c 65  terface.** imple
b090: 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 0a  mentations will.
b0a0: 2a 2a 20 77 61 6e 74 20 74 6f 20 73 75 62 63 6c  ** want to subcl
b0b0: 61 73 73 20 74 68 69 73 20 6f 62 6a 65 63 74 20  ass this object 
b0c0: 62 79 20 61 70 70 65 6e 64 69 6e 67 20 61 64 64  by appending add
b0d0: 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 0a 2a  itional fields.*
b0e0: 2a 20 66 6f 72 20 74 68 65 69 72 20 6f 77 6e 20  * for their own 
b0f0: 75 73 65 2e 20 20 54 68 65 20 70 4d 65 74 68 6f  use.  The pMetho
b100: 64 73 20 65 6e 74 72 79 20 69 73 20 61 20 70 6f  ds entry is a po
b110: 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b  inter to an.** [
b120: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
b130: 64 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20  ds] object that 
b140: 64 65 66 69 6e 65 73 20 6d 65 74 68 6f 64 73 20  defines methods 
b150: 66 6f 72 20 70 65 72 66 6f 72 6d 69 6e 67 0a 2a  for performing.*
b160: 2a 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73  * I/O operations
b170: 20 6f 6e 20 74 68 65 20 6f 70 65 6e 20 66 69 6c   on the open fil
b180: 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  e..*/.typedef st
b190: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c  ruct sqlite3_fil
b1a0: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 3b 0a  e sqlite3_file;.
b1b0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66  struct sqlite3_f
b1c0: 69 6c 65 20 7b 0a 20 20 63 6f 6e 73 74 20 73 74  ile {.  const st
b1d0: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f  ruct sqlite3_io_
b1e0: 6d 65 74 68 6f 64 73 20 2a 70 4d 65 74 68 6f 64  methods *pMethod
b1f0: 73 3b 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66  s;  /* Methods f
b200: 6f 72 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20  or an open file 
b210: 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
b220: 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66  I3REF: OS Interf
b230: 61 63 65 20 46 69 6c 65 20 56 69 72 74 75 61 6c  ace File Virtual
b240: 20 4d 65 74 68 6f 64 73 20 4f 62 6a 65 63 74 0a   Methods Object.
b250: 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 66 69 6c 65  **.** Every file
b260: 20 6f 70 65 6e 65 64 20 62 79 20 74 68 65 20 5b   opened by the [
b270: 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65  sqlite3_vfs.xOpe
b280: 6e 5d 20 6d 65 74 68 6f 64 20 70 6f 70 75 6c 61  n] method popula
b290: 74 65 73 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74  tes an.** [sqlit
b2a0: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20  e3_file] object 
b2b0: 28 6f 72 2c 20 6d 6f 72 65 20 63 6f 6d 6d 6f 6e  (or, more common
b2c0: 6c 79 2c 20 61 20 73 75 62 63 6c 61 73 73 20 6f  ly, a subclass o
b2d0: 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  f the.** [sqlite
b2e0: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 29 20  3_file] object) 
b2f0: 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20 74  with a pointer t
b300: 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  o an instance of
b310: 20 74 68 69 73 20 6f 62 6a 65 63 74 2e 0a 2a 2a   this object..**
b320: 20 54 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66   This object def
b330: 69 6e 65 73 20 74 68 65 20 6d 65 74 68 6f 64 73  ines the methods
b340: 20 75 73 65 64 20 74 6f 20 70 65 72 66 6f 72 6d   used to perform
b350: 20 76 61 72 69 6f 75 73 20 6f 70 65 72 61 74 69   various operati
b360: 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e 73 74 20 74  ons.** against t
b370: 68 65 20 6f 70 65 6e 20 66 69 6c 65 20 72 65 70  he open file rep
b380: 72 65 73 65 6e 74 65 64 20 62 79 20 74 68 65 20  resented by the 
b390: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f  [sqlite3_file] o
b3a0: 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  bject..**.** If 
b3b0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
b3c0: 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 73  .xOpen] method s
b3d0: 65 74 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ets the sqlite3_
b3e0: 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c  file.pMethods el
b3f0: 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f 20 61 20 6e  ement .** to a n
b400: 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c  on-NULL pointer,
b410: 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65   then the sqlite
b420: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 2e 78 43 6c  3_io_methods.xCl
b430: 6f 73 65 20 6d 65 74 68 6f 64 0a 2a 2a 20 6d 61  ose method.** ma
b440: 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 65 76 65  y be invoked eve
b450: 6e 20 69 66 20 74 68 65 20 5b 73 71 6c 69 74 65  n if the [sqlite
b460: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 72 65 70  3_vfs.xOpen] rep
b470: 6f 72 74 65 64 20 74 68 61 74 20 69 74 20 66 61  orted that it fa
b480: 69 6c 65 64 2e 20 20 54 68 65 0a 2a 2a 20 6f 6e  iled.  The.** on
b490: 6c 79 20 77 61 79 20 74 6f 20 70 72 65 76 65 6e  ly way to preven
b4a0: 74 20 61 20 63 61 6c 6c 20 74 6f 20 78 43 6c 6f  t a call to xClo
b4b0: 73 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66  se following a f
b4c0: 61 69 6c 65 64 20 5b 73 71 6c 69 74 65 33 5f 76  ailed [sqlite3_v
b4d0: 66 73 2e 78 4f 70 65 6e 5d 0a 2a 2a 20 69 73 20  fs.xOpen].** is 
b4e0: 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33  for the [sqlite3
b4f0: 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 74 6f 20 73  _vfs.xOpen] to s
b500: 65 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66  et the sqlite3_f
b510: 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65  ile.pMethods ele
b520: 6d 65 6e 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e  ment.** to NULL.
b530: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73  .**.** The flags
b540: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 53 79   argument to xSy
b550: 6e 63 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66  nc may be one of
b560: 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f   [SQLITE_SYNC_NO
b570: 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c  RMAL] or.** [SQL
b580: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d 2e 20  ITE_SYNC_FULL]. 
b590: 20 54 68 65 20 66 69 72 73 74 20 63 68 6f 69 63   The first choic
b5a0: 65 20 69 73 20 74 68 65 20 6e 6f 72 6d 61 6c 20  e is the normal 
b5b0: 66 73 79 6e 63 28 29 2e 0a 2a 2a 20 54 68 65 20  fsync()..** The 
b5c0: 73 65 63 6f 6e 64 20 63 68 6f 69 63 65 20 69 73  second choice is
b5d0: 20 61 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c   a Mac OS X styl
b5e0: 65 20 66 75 6c 6c 73 79 6e 63 2e 20 20 54 68 65  e fullsync.  The
b5f0: 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41   [SQLITE_SYNC_DA
b600: 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c 61 67 20  TAONLY].** flag 
b610: 6d 61 79 20 62 65 20 4f 52 65 64 20 69 6e 20 74  may be ORed in t
b620: 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 20  o indicate that 
b630: 6f 6e 6c 79 20 74 68 65 20 64 61 74 61 20 6f 66  only the data of
b640: 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20 61 6e 64   the file.** and
b650: 20 6e 6f 74 20 69 74 73 20 69 6e 6f 64 65 20 6e   not its inode n
b660: 65 65 64 73 20 74 6f 20 62 65 20 73 79 6e 63 65  eeds to be synce
b670: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 74  d..**.** The int
b680: 65 67 65 72 20 76 61 6c 75 65 73 20 74 6f 20 78  eger values to x
b690: 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f  Lock() and xUnlo
b6a0: 63 6b 28 29 20 61 72 65 20 6f 6e 65 20 6f 66 0a  ck() are one of.
b6b0: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
b6c0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e  [SQLITE_LOCK_NON
b6d0: 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  E],.** <li> [SQL
b6e0: 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d  ITE_LOCK_SHARED]
b6f0: 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ,.** <li> [SQLIT
b700: 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d  E_LOCK_RESERVED]
b710: 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ,.** <li> [SQLIT
b720: 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c  E_LOCK_PENDING],
b730: 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c   or.** <li> [SQL
b740: 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49  ITE_LOCK_EXCLUSI
b750: 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  VE]..** </ul>.**
b760: 20 78 4c 6f 63 6b 28 29 20 69 6e 63 72 65 61 73   xLock() increas
b770: 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20 78 55 6e  es the lock. xUn
b780: 6c 6f 63 6b 28 29 20 64 65 63 72 65 61 73 65 73  lock() decreases
b790: 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 54 68   the lock..** Th
b7a0: 65 20 78 43 68 65 63 6b 52 65 73 65 72 76 65 64  e xCheckReserved
b7b0: 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 20 63 68  Lock() method ch
b7c0: 65 63 6b 73 20 77 68 65 74 68 65 72 20 61 6e 79  ecks whether any
b7d0: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
b7e0: 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68 65 72 20  tion,.** either 
b7f0: 69 6e 20 74 68 69 73 20 70 72 6f 63 65 73 73 20  in this process 
b800: 6f 72 20 69 6e 20 73 6f 6d 65 20 6f 74 68 65 72  or in some other
b810: 20 70 72 6f 63 65 73 73 2c 20 69 73 20 68 6f 6c   process, is hol
b820: 64 69 6e 67 20 61 20 52 45 53 45 52 56 45 44 2c  ding a RESERVED,
b830: 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20 6f 72 20  .** PENDING, or 
b840: 45 58 43 4c 55 53 49 56 45 20 6c 6f 63 6b 20 6f  EXCLUSIVE lock o
b850: 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 49 74 20  n the file.  It 
b860: 72 65 74 75 72 6e 73 20 74 72 75 65 0a 2a 2a 20  returns true.** 
b870: 69 66 20 73 75 63 68 20 61 20 6c 6f 63 6b 20 65  if such a lock e
b880: 78 69 73 74 73 20 61 6e 64 20 66 61 6c 73 65 20  xists and false 
b890: 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a  otherwise..**.**
b8a0: 20 54 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f   The xFileContro
b8b0: 6c 28 29 20 6d 65 74 68 6f 64 20 69 73 20 61 20  l() method is a 
b8c0: 67 65 6e 65 72 69 63 20 69 6e 74 65 72 66 61 63  generic interfac
b8d0: 65 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 63 75  e that allows cu
b8e0: 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d 70 6c  stom.** VFS impl
b8f0: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74 6f 20 64  ementations to d
b900: 69 72 65 63 74 6c 79 20 63 6f 6e 74 72 6f 6c 20  irectly control 
b910: 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 75 73 69  an open file usi
b920: 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ng the.** [sqlit
b930: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
b940: 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20 54  )] interface.  T
b950: 68 65 20 73 65 63 6f 6e 64 20 22 6f 70 22 20 61  he second "op" a
b960: 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 0a 2a 2a  rgument is an.**
b970: 20 69 6e 74 65 67 65 72 20 6f 70 63 6f 64 65 2e   integer opcode.
b980: 20 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75    The third argu
b990: 6d 65 6e 74 20 69 73 20 61 20 67 65 6e 65 72 69  ment is a generi
b9a0: 63 20 70 6f 69 6e 74 65 72 20 69 6e 74 65 6e 64  c pointer intend
b9b0: 65 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e 74 20 74  ed to.** point t
b9c0: 6f 20 61 20 73 74 72 75 63 74 75 72 65 20 74 68  o a structure th
b9d0: 61 74 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 61  at may contain a
b9e0: 72 67 75 6d 65 6e 74 73 20 6f 72 20 73 70 61 63  rguments or spac
b9f0: 65 20 69 6e 20 77 68 69 63 68 20 74 6f 0a 2a 2a  e in which to.**
ba00: 20 77 72 69 74 65 20 72 65 74 75 72 6e 20 76 61   write return va
ba10: 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74 69 61 6c  lues.  Potential
ba20: 20 75 73 65 73 20 66 6f 72 20 78 46 69 6c 65 43   uses for xFileC
ba30: 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68 74 20 62  ontrol() might b
ba40: 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 74  e.** functions t
ba50: 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63 6b 69 6e  o enable blockin
ba60: 67 20 6c 6f 63 6b 73 20 77 69 74 68 20 74 69 6d  g locks with tim
ba70: 65 6f 75 74 73 2c 20 74 6f 20 63 68 61 6e 67 65  eouts, to change
ba80: 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e 67 20   the.** locking 
ba90: 73 74 72 61 74 65 67 79 20 28 66 6f 72 20 65 78  strategy (for ex
baa0: 61 6d 70 6c 65 20 74 6f 20 75 73 65 20 64 6f 74  ample to use dot
bab0: 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c 20 74 6f  -file locks), to
bac0: 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61 62 6f 75   inquire.** abou
bad0: 74 20 74 68 65 20 73 74 61 74 75 73 20 6f 66 20  t the status of 
bae0: 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20 62 72  a lock, or to br
baf0: 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63 6b 73 2e  eak stale locks.
bb00: 20 20 54 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20    The SQLite.** 
bb10: 63 6f 72 65 20 72 65 73 65 72 76 65 73 20 61 6c  core reserves al
bb20: 6c 20 6f 70 63 6f 64 65 73 20 6c 65 73 73 20 74  l opcodes less t
bb30: 68 61 6e 20 31 30 30 20 66 6f 72 20 69 74 73 20  han 100 for its 
bb40: 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20 41 20 5b 53  own use..** A [S
bb50: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b  QLITE_FCNTL_LOCK
bb60: 53 54 41 54 45 20 7c 20 6c 69 73 74 20 6f 66 20  STATE | list of 
bb70: 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73 20 74 68  opcodes] less th
bb80: 61 6e 20 31 30 30 20 69 73 20 61 76 61 69 6c 61  an 100 is availa
bb90: 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74  ble..** Applicat
bba0: 69 6f 6e 73 20 74 68 61 74 20 64 65 66 69 6e 65  ions that define
bbb0: 20 61 20 63 75 73 74 6f 6d 20 78 46 69 6c 65 43   a custom xFileC
bbc0: 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 73 68  ontrol method sh
bbd0: 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f 64 65 73  ould use opcodes
bbe0: 0a 2a 2a 20 67 72 65 61 74 65 72 20 74 68 61 6e  .** greater than
bbf0: 20 31 30 30 20 74 6f 20 61 76 6f 69 64 20 63 6f   100 to avoid co
bc00: 6e 66 6c 69 63 74 73 2e 20 20 56 46 53 20 69 6d  nflicts.  VFS im
bc10: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68  plementations sh
bc20: 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b  ould.** return [
bc30: 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d  SQLITE_NOTFOUND]
bc40: 20 66 6f 72 20 66 69 6c 65 20 63 6f 6e 74 72 6f   for file contro
bc50: 6c 20 6f 70 63 6f 64 65 73 20 74 68 61 74 20 74  l opcodes that t
bc60: 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 72 65  hey do not.** re
bc70: 63 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a 2a 20 54  cognize..**.** T
bc80: 68 65 20 78 53 65 63 74 6f 72 53 69 7a 65 28 29  he xSectorSize()
bc90: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20   method returns 
bca0: 74 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20  the sector size 
bcb0: 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76 69 63 65  of the.** device
bcc0: 20 74 68 61 74 20 75 6e 64 65 72 6c 69 65 73 20   that underlies 
bcd0: 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 73  the file.  The s
bce0: 65 63 74 6f 72 20 73 69 7a 65 20 69 73 20 74 68  ector size is th
bcf0: 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 72 69  e.** minimum wri
bd00: 74 65 20 74 68 61 74 20 63 61 6e 20 62 65 20 70  te that can be p
bd10: 65 72 66 6f 72 6d 65 64 20 77 69 74 68 6f 75 74  erformed without
bd20: 20 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a 20 6f   disturbing.** o
bd30: 74 68 65 72 20 62 79 74 65 73 20 69 6e 20 74 68  ther bytes in th
bd40: 65 20 66 69 6c 65 2e 20 20 54 68 65 20 78 44 65  e file.  The xDe
bd50: 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74  viceCharacterist
bd60: 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20  ics().** method 
bd70: 72 65 74 75 72 6e 73 20 61 20 62 69 74 20 76 65  returns a bit ve
bd80: 63 74 6f 72 20 64 65 73 63 72 69 62 69 6e 67 20  ctor describing 
bd90: 62 65 68 61 76 69 6f 72 73 20 6f 66 20 74 68 65  behaviors of the
bda0: 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 64  .** underlying d
bdb0: 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  evice:.**.** <ul
bdc0: 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  >.** <li> [SQLIT
bdd0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 5d 0a  E_IOCAP_ATOMIC].
bde0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
bdf0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 5d  IOCAP_ATOMIC512]
be00: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
be10: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 5d  _IOCAP_ATOMIC1K]
be20: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
be30: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 5d  _IOCAP_ATOMIC2K]
be40: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
be50: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 5d  _IOCAP_ATOMIC4K]
be60: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
be70: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 5d  _IOCAP_ATOMIC8K]
be80: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
be90: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b  _IOCAP_ATOMIC16K
bea0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
beb0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32  E_IOCAP_ATOMIC32
bec0: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
bed0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36  TE_IOCAP_ATOMIC6
bee0: 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  4K].** <li> [SQL
bef0: 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41  ITE_IOCAP_SAFE_A
bf00: 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  PPEND].** <li> [
bf10: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51  SQLITE_IOCAP_SEQ
bf20: 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c  UENTIAL].** </ul
bf30: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49  >.**.** The SQLI
bf40: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20  TE_IOCAP_ATOMIC 
bf50: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74  property means t
bf60: 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f  hat all writes o
bf70: 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72  f.** any size ar
bf80: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53  e atomic.  The S
bf90: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
bfa0: 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20  ICnnn values.** 
bfb0: 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73  mean that writes
bfc0: 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20   of blocks that 
bfd0: 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e  are nnn bytes in
bfe0: 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65   size and.** are
bff0: 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61   aligned to an a
c000: 64 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20  ddress which is 
c010: 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69  an integer multi
c020: 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72  ple of.** nnn ar
c030: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53  e atomic.  The S
c040: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45  QLITE_IOCAP_SAFE
c050: 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65  _APPEND value me
c060: 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e  ans.** that when
c070: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65   data is appende
c080: 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65  d to a file, the
c090: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65   data is appende
c0a0: 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20  d.** first then 
c0b0: 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
c0c0: 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64  file is extended
c0d0: 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65  , never the othe
c0e0: 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e  r.** way around.
c0f0: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
c100: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72  AP_SEQUENTIAL pr
c110: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61  operty means tha
c120: 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  t.** information
c130: 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64   is written to d
c140: 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20  isk in the same 
c150: 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a  order as calls.*
c160: 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a  * to xWrite()..*
c170: 2a 0a 2a 2a 20 49 66 20 78 52 65 61 64 28 29 20  *.** If xRead() 
c180: 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 49  returns SQLITE_I
c190: 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20  OERR_SHORT_READ 
c1a0: 69 74 20 6d 75 73 74 20 61 6c 73 6f 20 66 69 6c  it must also fil
c1b0: 6c 0a 2a 2a 20 69 6e 20 74 68 65 20 75 6e 72 65  l.** in the unre
c1c0: 61 64 20 70 6f 72 74 69 6f 6e 73 20 6f 66 20 74  ad portions of t
c1d0: 68 65 20 62 75 66 66 65 72 20 77 69 74 68 20 7a  he buffer with z
c1e0: 65 72 6f 73 2e 20 20 41 20 56 46 53 20 74 68 61  eros.  A VFS tha
c1f0: 74 0a 2a 2a 20 66 61 69 6c 73 20 74 6f 20 7a 65  t.** fails to ze
c200: 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65  ro-fill short re
c210: 61 64 73 20 6d 69 67 68 74 20 73 65 65 6d 20 74  ads might seem t
c220: 6f 20 77 6f 72 6b 2e 20 20 48 6f 77 65 76 65 72  o work.  However
c230: 2c 0a 2a 2a 20 66 61 69 6c 75 72 65 20 74 6f 20  ,.** failure to 
c240: 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20  zero-fill short 
c250: 72 65 61 64 73 20 77 69 6c 6c 20 65 76 65 6e 74  reads will event
c260: 75 61 6c 6c 79 20 6c 65 61 64 20 74 6f 0a 2a 2a  ually lead to.**
c270: 20 64 61 74 61 62 61 73 65 20 63 6f 72 72 75 70   database corrup
c280: 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  tion..*/.typedef
c290: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
c2a0: 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74  io_methods sqlit
c2b0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73  e3_io_methods;.s
c2c0: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f  truct sqlite3_io
c2d0: 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74  _methods {.  int
c2e0: 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74   iVersion;.  int
c2f0: 20 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 74   (*xClose)(sqlit
c300: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74  e3_file*);.  int
c310: 20 28 2a 78 52 65 61 64 29 28 73 71 6c 69 74 65   (*xRead)(sqlite
c320: 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20  3_file*, void*, 
c330: 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65  int iAmt, sqlite
c340: 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a  3_int64 iOfst);.
c350: 20 20 69 6e 74 20 28 2a 78 57 72 69 74 65 29 28    int (*xWrite)(
c360: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63  sqlite3_file*, c
c370: 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20  onst void*, int 
c380: 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e  iAmt, sqlite3_in
c390: 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e  t64 iOfst);.  in
c3a0: 74 20 28 2a 78 54 72 75 6e 63 61 74 65 29 28 73  t (*xTruncate)(s
c3b0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71  qlite3_file*, sq
c3c0: 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 69 7a 65  lite3_int64 size
c3d0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e 63  );.  int (*xSync
c3e0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
c3f0: 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 69   int flags);.  i
c400: 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a 65 29 28  nt (*xFileSize)(
c410: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73  sqlite3_file*, s
c420: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 53  qlite3_int64 *pS
c430: 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c  ize);.  int (*xL
c440: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ock)(sqlite3_fil
c450: 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20  e*, int);.  int 
c460: 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74  (*xUnlock)(sqlit
c470: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a  e3_file*, int);.
c480: 20 20 69 6e 74 20 28 2a 78 43 68 65 63 6b 52 65    int (*xCheckRe
c490: 73 65 72 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69  servedLock)(sqli
c4a0: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 2a  te3_file*, int *
c4b0: 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20  pResOut);.  int 
c4c0: 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 28  (*xFileControl)(
c4d0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
c4e0: 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70 41 72  nt op, void *pAr
c4f0: 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 65 63  g);.  int (*xSec
c500: 74 6f 72 53 69 7a 65 29 28 73 71 6c 69 74 65 33  torSize)(sqlite3
c510: 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28  _file*);.  int (
c520: 2a 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65  *xDeviceCharacte
c530: 72 69 73 74 69 63 73 29 28 73 71 6c 69 74 65 33  ristics)(sqlite3
c540: 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 4d 65  _file*);.  /* Me
c550: 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20  thods above are 
c560: 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f  valid for versio
c570: 6e 20 31 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  n 1 */.  int (*x
c580: 53 68 6d 4d 61 70 29 28 73 71 6c 69 74 65 33 5f  ShmMap)(sqlite3_
c590: 66 69 6c 65 2a 2c 20 69 6e 74 20 69 50 67 2c 20  file*, int iPg, 
c5a0: 69 6e 74 20 70 67 73 7a 2c 20 69 6e 74 2c 20 76  int pgsz, int, v
c5b0: 6f 69 64 20 76 6f 6c 61 74 69 6c 65 2a 2a 29 3b  oid volatile**);
c5c0: 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 4c 6f 63  .  int (*xShmLoc
c5d0: 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  k)(sqlite3_file*
c5e0: 2c 20 69 6e 74 20 6f 66 66 73 65 74 2c 20 69 6e  , int offset, in
c5f0: 74 20 6e 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b  t n, int flags);
c600: 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 6d 42 61  .  void (*xShmBa
c610: 72 72 69 65 72 29 28 73 71 6c 69 74 65 33 5f 66  rrier)(sqlite3_f
c620: 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  ile*);.  int (*x
c630: 53 68 6d 55 6e 6d 61 70 29 28 73 71 6c 69 74 65  ShmUnmap)(sqlite
c640: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 64 65 6c  3_file*, int del
c650: 65 74 65 46 6c 61 67 29 3b 0a 20 20 2f 2a 20 4d  eteFlag);.  /* M
c660: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65  ethods above are
c670: 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69   valid for versi
c680: 6f 6e 20 32 20 2a 2f 0a 20 20 2f 2a 20 41 64 64  on 2 */.  /* Add
c690: 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f 64 73 20  itional methods 
c6a0: 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
c6b0: 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
c6c0: 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
c6d0: 49 33 52 45 46 3a 20 53 74 61 6e 64 61 72 64 20  I3REF: Standard 
c6e0: 46 69 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f 70 63  File Control Opc
c6f0: 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  odes.**.** These
c700: 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e   integer constan
c710: 74 73 20 61 72 65 20 6f 70 63 6f 64 65 73 20 66  ts are opcodes f
c720: 6f 72 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74  or the xFileCont
c730: 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66  rol method.** of
c740: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f   the [sqlite3_io
c750: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
c760: 20 61 6e 64 20 66 6f 72 20 74 68 65 20 5b 73 71   and for the [sq
c770: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
c780: 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61  ol()].** interfa
c790: 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53  ce..**.** The [S
c7a0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b  QLITE_FCNTL_LOCK
c7b0: 53 54 41 54 45 5d 20 6f 70 63 6f 64 65 20 69 73  STATE] opcode is
c7c0: 20 75 73 65 64 20 66 6f 72 20 64 65 62 75 67 67   used for debugg
c7d0: 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70  ing.  This.** op
c7e0: 63 6f 64 65 20 63 61 75 73 65 73 20 74 68 65 20  code causes the 
c7f0: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74  xFileControl met
c800: 68 6f 64 20 74 6f 20 77 72 69 74 65 20 74 68 65  hod to write the
c810: 20 63 75 72 72 65 6e 74 20 73 74 61 74 65 20 6f   current state o
c820: 66 0a 2a 2a 20 74 68 65 20 6c 6f 63 6b 20 28 6f  f.** the lock (o
c830: 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4c 4f  ne of [SQLITE_LO
c840: 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54  CK_NONE], [SQLIT
c850: 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a  E_LOCK_SHARED],.
c860: 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ** [SQLITE_LOCK_
c870: 52 45 53 45 52 56 45 44 5d 2c 20 5b 53 51 4c 49  RESERVED], [SQLI
c880: 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d  TE_LOCK_PENDING]
c890: 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  , or [SQLITE_LOC
c8a0: 4b 5f 45 58 43 4c 55 53 49 56 45 5d 29 0a 2a 2a  K_EXCLUSIVE]).**
c8b0: 20 69 6e 74 6f 20 61 6e 20 69 6e 74 65 67 65 72   into an integer
c8c0: 20 74 68 61 74 20 74 68 65 20 70 41 72 67 20 61   that the pArg a
c8d0: 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74  rgument points t
c8e0: 6f 2e 20 54 68 69 73 20 63 61 70 61 62 69 6c 69  o. This capabili
c8f0: 74 79 0a 2a 2a 20 69 73 20 75 73 65 64 20 64 75  ty.** is used du
c900: 72 69 6e 67 20 74 65 73 74 69 6e 67 20 61 6e 64  ring testing and
c910: 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 62   only needs to b
c920: 65 20 73 75 70 70 6f 72 74 65 64 20 77 68 65 6e  e supported when
c930: 20 53 51 4c 49 54 45 5f 54 45 53 54 0a 2a 2a 20   SQLITE_TEST.** 
c940: 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a  is defined..**.*
c950: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
c960: 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 20 6f  NTL_SIZE_HINT] o
c970: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 62 79  pcode is used by
c980: 20 53 51 4c 69 74 65 20 74 6f 20 67 69 76 65 20   SQLite to give 
c990: 74 68 65 20 56 46 53 0a 2a 2a 20 6c 61 79 65 72  the VFS.** layer
c9a0: 20 61 20 68 69 6e 74 20 6f 66 20 68 6f 77 20 6c   a hint of how l
c9b0: 61 72 67 65 20 74 68 65 20 64 61 74 61 62 61 73  arge the databas
c9c0: 65 20 66 69 6c 65 20 77 69 6c 6c 20 67 72 6f 77  e file will grow
c9d0: 20 74 6f 20 62 65 20 64 75 72 69 6e 67 20 74 68   to be during th
c9e0: 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 74 72 61  e.** current tra
c9f0: 6e 73 61 63 74 69 6f 6e 2e 20 20 54 68 69 73 20  nsaction.  This 
ca00: 68 69 6e 74 20 69 73 20 6e 6f 74 20 67 75 61 72  hint is not guar
ca10: 61 6e 74 65 65 64 20 74 6f 20 62 65 20 61 63 63  anteed to be acc
ca20: 75 72 61 74 65 20 62 75 74 20 69 74 0a 2a 2a 20  urate but it.** 
ca30: 69 73 20 6f 66 74 65 6e 20 63 6c 6f 73 65 2e 20  is often close. 
ca40: 20 54 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20   The underlying 
ca50: 56 46 53 20 6d 69 67 68 74 20 63 68 6f 6f 73 65  VFS might choose
ca60: 20 74 6f 20 70 72 65 61 6c 6c 6f 63 61 74 65 20   to preallocate 
ca70: 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65  database.** file
ca80: 20 73 70 61 63 65 20 62 61 73 65 64 20 6f 6e 20   space based on 
ca90: 74 68 69 73 20 68 69 6e 74 20 69 6e 20 6f 72 64  this hint in ord
caa0: 65 72 20 74 6f 20 68 65 6c 70 20 77 72 69 74 65  er to help write
cab0: 73 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73  s to the databas
cac0: 65 0a 2a 2a 20 66 69 6c 65 20 72 75 6e 20 66 61  e.** file run fa
cad0: 73 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ster..**.** The 
cae0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48  [SQLITE_FCNTL_CH
caf0: 55 4e 4b 5f 53 49 5a 45 5d 20 6f 70 63 6f 64 65  UNK_SIZE] opcode
cb00: 20 69 73 20 75 73 65 64 20 74 6f 20 72 65 71 75   is used to requ
cb10: 65 73 74 20 74 68 61 74 20 74 68 65 20 56 46 53  est that the VFS
cb20: 0a 2a 2a 20 65 78 74 65 6e 64 73 20 61 6e 64 20  .** extends and 
cb30: 74 72 75 6e 63 61 74 65 73 20 74 68 65 20 64 61  truncates the da
cb40: 74 61 62 61 73 65 20 66 69 6c 65 20 69 6e 20 63  tabase file in c
cb50: 68 75 6e 6b 73 20 6f 66 20 61 20 73 69 7a 65 20  hunks of a size 
cb60: 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20  specified.** by 
cb70: 74 68 65 20 75 73 65 72 2e 20 54 68 65 20 66 6f  the user. The fo
cb80: 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f  urth argument to
cb90: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
cba0: 6f 6e 74 72 6f 6c 28 29 5d 20 73 68 6f 75 6c 64  ontrol()] should
cbb0: 20 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 6e   .** point to an
cbc0: 20 69 6e 74 65 67 65 72 20 28 74 79 70 65 20 69   integer (type i
cbd0: 6e 74 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  nt) containing t
cbe0: 68 65 20 6e 65 77 20 63 68 75 6e 6b 2d 73 69 7a  he new chunk-siz
cbf0: 65 20 74 6f 20 75 73 65 0a 2a 2a 20 66 6f 72 20  e to use.** for 
cc00: 74 68 65 20 6e 6f 6d 69 6e 61 74 65 64 20 64 61  the nominated da
cc10: 74 61 62 61 73 65 2e 20 41 6c 6c 6f 63 61 74 69  tabase. Allocati
cc20: 6e 67 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  ng database file
cc30: 20 73 70 61 63 65 20 69 6e 20 6c 61 72 67 65 0a   space in large.
cc40: 2a 2a 20 63 68 75 6e 6b 73 20 28 73 61 79 20 31  ** chunks (say 1
cc50: 4d 42 20 61 74 20 61 20 74 69 6d 65 29 2c 20 6d  MB at a time), m
cc60: 61 79 20 72 65 64 75 63 65 20 66 69 6c 65 2d 73  ay reduce file-s
cc70: 79 73 74 65 6d 20 66 72 61 67 6d 65 6e 74 61 74  ystem fragmentat
cc80: 69 6f 6e 20 61 6e 64 0a 2a 2a 20 69 6d 70 72 6f  ion and.** impro
cc90: 76 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6f  ve performance o
cca0: 6e 20 73 6f 6d 65 20 73 79 73 74 65 6d 73 2e 0a  n some systems..
ccb0: 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  **.** The [SQLIT
ccc0: 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49  E_FCNTL_FILE_POI
ccd0: 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20 69 73 20  NTER] opcode is 
cce0: 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 61  used to obtain a
ccf0: 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74   pointer.** to t
cd00: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  he [sqlite3_file
cd10: 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f 63 69 61  ] object associa
cd20: 74 65 64 20 77 69 74 68 20 61 20 70 61 72 74 69  ted with a parti
cd30: 63 75 6c 61 72 20 64 61 74 61 62 61 73 65 0a 2a  cular database.*
cd40: 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 53  * connection.  S
cd50: 65 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ee the [sqlite3_
cd60: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20  file_control()] 
cd70: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
cd80: 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20  r.** additional 
cd90: 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
cda0: 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c 49 54 45  ** ^(The [SQLITE
cdb0: 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54  _FCNTL_SYNC_OMIT
cdc0: 54 45 44 5d 20 6f 70 63 6f 64 65 20 69 73 20 67  TED] opcode is g
cdd0: 65 6e 65 72 61 74 65 64 20 69 6e 74 65 72 6e 61  enerated interna
cde0: 6c 6c 79 20 62 79 0a 2a 2a 20 53 51 4c 69 74 65  lly by.** SQLite
cdf0: 20 61 6e 64 20 73 65 6e 74 20 74 6f 20 61 6c 6c   and sent to all
ce00: 20 56 46 53 65 73 20 69 6e 20 70 6c 61 63 65 20   VFSes in place 
ce10: 6f 66 20 61 20 63 61 6c 6c 20 74 6f 20 74 68 65  of a call to the
ce20: 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 0a 2a 2a   xSync method.**
ce30: 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   when the databa
ce40: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 68 61  se connection ha
ce50: 73 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72  s [PRAGMA synchr
ce60: 6f 6e 6f 75 73 5d 20 73 65 74 20 74 6f 20 4f 46  onous] set to OF
ce70: 46 2e 29 5e 0a 2a 2a 20 53 6f 6d 65 20 73 70 65  F.)^.** Some spe
ce80: 63 69 61 6c 69 7a 65 64 20 56 46 53 65 73 20 6e  cialized VFSes n
ce90: 65 65 64 20 74 68 69 73 20 73 69 67 6e 61 6c 20  eed this signal 
cea0: 69 6e 20 6f 72 64 65 72 20 74 6f 20 6f 70 65 72  in order to oper
ceb0: 61 74 65 20 63 6f 72 72 65 63 74 6c 79 0a 2a 2a  ate correctly.**
cec0: 20 77 68 65 6e 20 5b 50 52 41 47 4d 41 20 73 79   when [PRAGMA sy
ced0: 6e 63 68 72 6f 6e 6f 75 73 20 7c 20 50 52 41 47  nchronous | PRAG
cee0: 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 3d 4f  MA synchronous=O
cef0: 46 46 5d 20 69 73 20 73 65 74 2c 20 62 75 74 20  FF] is set, but 
cf00: 6d 6f 73 74 20 0a 2a 2a 20 56 46 53 65 73 20 64  most .** VFSes d
cf10: 6f 20 6e 6f 74 20 6e 65 65 64 20 74 68 69 73 20  o not need this 
cf20: 73 69 67 6e 61 6c 20 61 6e 64 20 73 68 6f 75 6c  signal and shoul
cf30: 64 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72  d silently ignor
cf40: 65 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 0a 2a  e this opcode..*
cf50: 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73  * Applications s
cf60: 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c 20 5b  hould not call [
cf70: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
cf80: 74 72 6f 6c 28 29 5d 20 77 69 74 68 20 74 68 69  trol()] with thi
cf90: 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 61 73 20 64  s.** opcode as d
cfa0: 6f 69 6e 67 20 73 6f 20 6d 61 79 20 64 69 73 72  oing so may disr
cfb0: 75 70 74 20 74 68 65 20 6f 70 65 72 61 74 69 6f  upt the operatio
cfc0: 6e 20 6f 66 20 74 68 65 20 73 70 65 63 69 61 6c  n of the special
cfd0: 69 7a 65 64 20 56 46 53 65 73 0a 2a 2a 20 74 68  ized VFSes.** th
cfe0: 61 74 20 64 6f 20 72 65 71 75 69 72 65 20 69 74  at do require it
cff0: 2e 20 20 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  .  .*/.#define S
d000: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b  QLITE_FCNTL_LOCK
d010: 53 54 41 54 45 20 20 20 20 20 20 20 20 31 0a 23  STATE        1.#
d020: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 47 45  define SQLITE_GE
d030: 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20  T_LOCKPROXYFILE 
d040: 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
d050: 51 4c 49 54 45 5f 53 45 54 5f 4c 4f 43 4b 50 52  QLITE_SET_LOCKPR
d060: 4f 58 59 46 49 4c 45 20 20 20 20 20 20 33 0a 23  OXYFILE      3.#
d070: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 41  define SQLITE_LA
d080: 53 54 5f 45 52 52 4e 4f 20 20 20 20 20 20 20 20  ST_ERRNO        
d090: 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53       4.#define S
d0a0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45  QLITE_FCNTL_SIZE
d0b0: 5f 48 49 4e 54 20 20 20 20 20 20 20 20 35 0a 23  _HINT        5.#
d0c0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
d0d0: 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 20 20  NTL_CHUNK_SIZE  
d0e0: 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53       6.#define S
d0f0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45  QLITE_FCNTL_FILE
d100: 5f 50 4f 49 4e 54 45 52 20 20 20 20 20 37 0a 23  _POINTER     7.#
d110: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
d120: 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44  NTL_SYNC_OMITTED
d130: 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43       8.../*.** C
d140: 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20 48  API3REF: Mutex H
d150: 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20  andle.**.** The 
d160: 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20 77 69 74  mutex module wit
d170: 68 69 6e 20 53 51 4c 69 74 65 20 64 65 66 69 6e  hin SQLite defin
d180: 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  es [sqlite3_mute
d190: 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20 61  x] to be an.** a
d1a0: 62 73 74 72 61 63 74 20 74 79 70 65 20 66 6f 72  bstract type for
d1b0: 20 61 20 6d 75 74 65 78 20 6f 62 6a 65 63 74 2e   a mutex object.
d1c0: 20 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72    The SQLite cor
d1d0: 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a  e never looks.**
d1e0: 20 61 74 20 74 68 65 20 69 6e 74 65 72 6e 61 6c   at the internal
d1f0: 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20   representation 
d200: 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 6d  of an [sqlite3_m
d210: 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a  utex].  It only.
d220: 2a 2a 20 64 65 61 6c 73 20 77 69 74 68 20 70 6f  ** deals with po
d230: 69 6e 74 65 72 73 20 74 6f 20 74 68 65 20 5b 73  inters to the [s
d240: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f 62  qlite3_mutex] ob
d250: 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65  ject..**.** Mute
d260: 78 65 73 20 61 72 65 20 63 72 65 61 74 65 64 20  xes are created 
d270: 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d  using [sqlite3_m
d280: 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a  utex_alloc()]..*
d290: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
d2a0: 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 73   sqlite3_mutex s
d2b0: 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f  qlite3_mutex;../
d2c0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
d2d0: 53 20 49 6e 74 65 72 66 61 63 65 20 4f 62 6a 65  S Interface Obje
d2e0: 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74  ct.**.** An inst
d2f0: 61 6e 63 65 20 6f 66 20 74 68 65 20 73 71 6c 69  ance of the sqli
d300: 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 64  te3_vfs object d
d310: 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72  efines the inter
d320: 66 61 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a 20  face between.** 
d330: 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20  the SQLite core 
d340: 61 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69  and the underlyi
d350: 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  ng operating sys
d360: 74 65 6d 2e 20 20 54 68 65 20 22 76 66 73 22 0a  tem.  The "vfs".
d370: 2a 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 6f  ** in the name o
d380: 66 20 74 68 65 20 6f 62 6a 65 63 74 20 73 74 61  f the object sta
d390: 6e 64 73 20 66 6f 72 20 22 76 69 72 74 75 61 6c  nds for "virtual
d3a0: 20 66 69 6c 65 20 73 79 73 74 65 6d 22 2e 20 20   file system".  
d3b0: 53 65 65 0a 2a 2a 20 74 68 65 20 5b 56 46 53 20  See.** the [VFS 
d3c0: 7c 20 56 46 53 20 64 6f 63 75 6d 65 6e 74 61 74  | VFS documentat
d3d0: 69 6f 6e 5d 20 66 6f 72 20 66 75 72 74 68 65 72  ion] for further
d3e0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a   information..**
d3f0: 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 6f 66  .** The value of
d400: 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69   the iVersion fi
d410: 65 6c 64 20 69 73 20 69 6e 69 74 69 61 6c 6c 79  eld is initially
d420: 20 31 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61   1 but may be la
d430: 72 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74 75 72  rger in.** futur
d440: 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
d450: 4c 69 74 65 2e 20 20 41 64 64 69 74 69 6f 6e 61  Lite.  Additiona
d460: 6c 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20  l fields may be 
d470: 61 70 70 65 6e 64 65 64 20 74 6f 20 74 68 69 73  appended to this
d480: 0a 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65 6e 20  .** object when 
d490: 74 68 65 20 69 56 65 72 73 69 6f 6e 20 76 61 6c  the iVersion val
d4a0: 75 65 20 69 73 20 69 6e 63 72 65 61 73 65 64 2e  ue is increased.
d4b0: 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20    Note that the 
d4c0: 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f 66 20  structure.** of 
d4d0: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20  the sqlite3_vfs 
d4e0: 6f 62 6a 65 63 74 20 63 68 61 6e 67 65 73 20 69  object changes i
d4f0: 6e 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f  n the transactio
d500: 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53 51 4c  n between.** SQL
d510: 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e  ite version 3.5.
d520: 39 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e 64 20  9 and 3.6.0 and 
d530: 79 65 74 20 74 68 65 20 69 56 65 72 73 69 6f 6e  yet the iVersion
d540: 20 66 69 65 6c 64 20 77 61 73 20 6e 6f 74 0a 2a   field was not.*
d550: 2a 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a  * modified..**.*
d560: 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c 65 20 66  * The szOsFile f
d570: 69 65 6c 64 20 69 73 20 74 68 65 20 73 69 7a 65  ield is the size
d580: 20 6f 66 20 74 68 65 20 73 75 62 63 6c 61 73 73   of the subclass
d590: 65 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ed [sqlite3_file
d5a0: 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 75  ].** structure u
d5b0: 73 65 64 20 62 79 20 74 68 69 73 20 56 46 53 2e  sed by this VFS.
d5c0: 20 20 6d 78 50 61 74 68 6e 61 6d 65 20 69 73 20    mxPathname is 
d5d0: 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67  the maximum leng
d5e0: 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68 6e  th of.** a pathn
d5f0: 61 6d 65 20 69 6e 20 74 68 69 73 20 56 46 53 2e  ame in this VFS.
d600: 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 65  .**.** Registere
d610: 64 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62  d sqlite3_vfs ob
d620: 6a 65 63 74 73 20 61 72 65 20 6b 65 70 74 20 6f  jects are kept o
d630: 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74 20  n a linked list 
d640: 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68 65  formed by.** the
d650: 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 20   pNext pointer. 
d660: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   The [sqlite3_vf
d670: 73 5f 72 65 67 69 73 74 65 72 28 29 5d 0a 2a 2a  s_register()].**
d680: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76 66   and [sqlite3_vf
d690: 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29 5d 20  s_unregister()] 
d6a0: 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6e 61 67  interfaces manag
d6b0: 65 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20 69  e this list.** i
d6c0: 6e 20 61 20 74 68 72 65 61 64 2d 73 61 66 65 20  n a thread-safe 
d6d0: 77 61 79 2e 20 20 54 68 65 20 5b 73 71 6c 69 74  way.  The [sqlit
d6e0: 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20 69  e3_vfs_find()] i
d6f0: 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 65 61 72  nterface.** sear
d700: 63 68 65 73 20 74 68 65 20 6c 69 73 74 2e 20 20  ches the list.  
d710: 4e 65 69 74 68 65 72 20 74 68 65 20 61 70 70 6c  Neither the appl
d720: 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f 72  ication code nor
d730: 20 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70 6c   the VFS.** impl
d740: 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c  ementation shoul
d750: 64 20 75 73 65 20 74 68 65 20 70 4e 65 78 74 20  d use the pNext 
d760: 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54  pointer..**.** T
d770: 68 65 20 70 4e 65 78 74 20 66 69 65 6c 64 20 69  he pNext field i
d780: 73 20 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c 64  s the only field
d790: 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f   in the sqlite3_
d7a0: 76 66 73 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  vfs.** structure
d7b0: 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c   that SQLite wil
d7c0: 6c 20 65 76 65 72 20 6d 6f 64 69 66 79 2e 20 20  l ever modify.  
d7d0: 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79  SQLite will only
d7e0: 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f   access.** or mo
d7f0: 64 69 66 79 20 74 68 69 73 20 66 69 65 6c 64 20  dify this field 
d800: 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61 20  while holding a 
d810: 70 61 72 74 69 63 75 6c 61 72 20 73 74 61 74 69  particular stati
d820: 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65 20  c mutex..** The 
d830: 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
d840: 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69 66 79 20  ld never modify 
d850: 61 6e 79 74 68 69 6e 67 20 77 69 74 68 69 6e 20  anything within 
d860: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a  the sqlite3_vfs.
d870: 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20 74  ** object once t
d880: 68 65 20 6f 62 6a 65 63 74 20 68 61 73 20 62 65  he object has be
d890: 65 6e 20 72 65 67 69 73 74 65 72 65 64 2e 0a 2a  en registered..*
d8a0: 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20 66  *.** The zName f
d8b0: 69 65 6c 64 20 68 6f 6c 64 73 20 74 68 65 20 6e  ield holds the n
d8c0: 61 6d 65 20 6f 66 20 74 68 65 20 56 46 53 20 6d  ame of the VFS m
d8d0: 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d 65  odule.  The name
d8e0: 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69 71   must.** be uniq
d8f0: 75 65 20 61 63 72 6f 73 73 20 61 6c 6c 20 56 46  ue across all VF
d900: 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a  S modules..**.**
d910: 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78   [[sqlite3_vfs.x
d920: 4f 70 65 6e 5d 5d 0a 2a 2a 20 5e 53 51 4c 69 74  Open]].** ^SQLit
d930: 65 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61  e guarantees tha
d940: 74 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20  t the zFilename 
d950: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70  parameter to xOp
d960: 65 6e 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20  en.** is either 
d970: 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f  a NULL pointer o
d980: 72 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65  r string obtaine
d990: 64 0a 2a 2a 20 66 72 6f 6d 20 78 46 75 6c 6c 50  d.** from xFullP
d9a0: 61 74 68 6e 61 6d 65 28 29 20 77 69 74 68 20 61  athname() with a
d9b0: 6e 20 6f 70 74 69 6f 6e 61 6c 20 73 75 66 66 69  n optional suffi
d9c0: 78 20 61 64 64 65 64 2e 0a 2a 2a 20 5e 49 66 20  x added..** ^If 
d9d0: 61 20 73 75 66 66 69 78 20 69 73 20 61 64 64 65  a suffix is adde
d9e0: 64 20 74 6f 20 74 68 65 20 7a 46 69 6c 65 6e 61  d to the zFilena
d9f0: 6d 65 20 70 61 72 61 6d 65 74 65 72 2c 20 69 74  me parameter, it
da00: 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 73 69 73 74   will.** consist
da10: 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 22 2d 22   of a single "-"
da20: 20 63 68 61 72 61 63 74 65 72 20 66 6f 6c 6c 6f   character follo
da30: 77 65 64 20 62 79 20 6e 6f 20 6d 6f 72 65 20 74  wed by no more t
da40: 68 61 6e 0a 2a 2a 20 31 30 20 61 6c 70 68 61 6e  han.** 10 alphan
da50: 75 6d 65 72 69 63 20 61 6e 64 2f 6f 72 20 22 2d  umeric and/or "-
da60: 22 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a  " characters..**
da70: 20 5e 53 51 4c 69 74 65 20 66 75 72 74 68 65 72   ^SQLite further
da80: 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74   guarantees that
da90: 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 77  .** the string w
daa0: 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 6e 64  ill be valid and
dab0: 20 75 6e 63 68 61 6e 67 65 64 20 75 6e 74 69 6c   unchanged until
dac0: 20 78 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a 20   xClose() is.** 
dad0: 63 61 6c 6c 65 64 2e 20 42 65 63 61 75 73 65 20  called. Because 
dae0: 6f 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 20  of the previous 
daf0: 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20 74 68 65  sentence,.** the
db00: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
db10: 63 61 6e 20 73 61 66 65 6c 79 20 73 74 6f 72 65  can safely store
db20: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
db30: 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 66  e.** filename if
db40: 20 69 74 20 6e 65 65 64 73 20 74 6f 20 72 65 6d   it needs to rem
db50: 65 6d 62 65 72 20 74 68 65 20 66 69 6c 65 6e 61  ember the filena
db60: 6d 65 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73  me for some reas
db70: 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 20 7a 46  on..** If the zF
db80: 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65  ilename paramete
db90: 72 20 74 6f 20 78 4f 70 65 6e 20 69 73 20 61 20  r to xOpen is a 
dba0: 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65  NULL pointer the
dbb0: 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74 20  n xOpen.** must 
dbc0: 69 6e 76 65 6e 74 20 69 74 73 20 6f 77 6e 20 74  invent its own t
dbd0: 65 6d 70 6f 72 61 72 79 20 6e 61 6d 65 20 66 6f  emporary name fo
dbe0: 72 20 74 68 65 20 66 69 6c 65 2e 20 20 5e 57 68  r the file.  ^Wh
dbf0: 65 6e 65 76 65 72 20 74 68 65 20 0a 2a 2a 20 78  enever the .** x
dc00: 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74  Filename paramet
dc10: 65 72 20 69 73 20 4e 55 4c 4c 20 69 74 20 77 69  er is NULL it wi
dc20: 6c 6c 20 61 6c 73 6f 20 62 65 20 74 68 65 20 63  ll also be the c
dc30: 61 73 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  ase that the.** 
dc40: 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20  flags parameter 
dc50: 77 69 6c 6c 20 69 6e 63 6c 75 64 65 20 5b 53 51  will include [SQ
dc60: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
dc70: 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20  ONCLOSE]..**.** 
dc80: 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  The flags argume
dc90: 6e 74 20 74 6f 20 78 4f 70 65 6e 28 29 20 69 6e  nt to xOpen() in
dca0: 63 6c 75 64 65 73 20 61 6c 6c 20 62 69 74 73 20  cludes all bits 
dcb0: 73 65 74 20 69 6e 0a 2a 2a 20 74 68 65 20 66 6c  set in.** the fl
dcc0: 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ags argument to 
dcd0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
dce0: 28 29 5d 2e 20 20 4f 72 20 69 66 20 5b 73 71 6c  ()].  Or if [sql
dcf0: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20  ite3_open()].** 
dd00: 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  or [sqlite3_open
dd10: 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20 74  16()] is used, t
dd20: 68 65 6e 20 66 6c 61 67 73 20 69 6e 63 6c 75 64  hen flags includ
dd30: 65 73 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20 5b  es at least.** [
dd40: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
dd50: 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45  WRITE] | [SQLITE
dd60: 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e 20 0a  _OPEN_CREATE]. .
dd70: 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29 20 6f 70  ** If xOpen() op
dd80: 65 6e 73 20 61 20 66 69 6c 65 20 72 65 61 64 2d  ens a file read-
dd90: 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20 73 65 74  only then it set
dda0: 73 20 2a 70 4f 75 74 46 6c 61 67 73 20 74 6f 0a  s *pOutFlags to.
ddb0: 2a 2a 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49  ** include [SQLI
ddc0: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
ddd0: 5d 2e 20 20 4f 74 68 65 72 20 62 69 74 73 20 69  ].  Other bits i
dde0: 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d 61 79  n *pOutFlags may
ddf0: 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e   be set..**.** ^
de00: 28 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73  (SQLite will als
de10: 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65  o add one of the
de20: 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73   following flags
de30: 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 0a   to the xOpen().
de40: 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e 64 69  ** call, dependi
de50: 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65 63 74  ng on the object
de60: 20 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a   being opened:.*
de70: 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
de80: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
de90: 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e  MAIN_DB].** <li>
dea0: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d    [SQLITE_OPEN_M
deb0: 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20  AIN_JOURNAL].** 
dec0: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
ded0: 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c  EN_TEMP_DB].** <
dee0: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
def0: 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a  N_TEMP_JOURNAL].
df00: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
df10: 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f  _OPEN_TRANSIENT_
df20: 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  DB].** <li>  [SQ
df30: 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55  LITE_OPEN_SUBJOU
df40: 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  RNAL].** <li>  [
df50: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54  SQLITE_OPEN_MAST
df60: 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c  ER_JOURNAL].** <
df70: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
df80: 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 29  N_WAL].** </ul>)
df90: 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c 65  ^.**.** The file
dfa0: 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61 74   I/O implementat
dfb0: 69 6f 6e 20 63 61 6e 20 75 73 65 20 74 68 65 20  ion can use the 
dfc0: 6f 62 6a 65 63 74 20 74 79 70 65 20 66 6c 61 67  object type flag
dfd0: 73 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 20 74  s to.** change t
dfe0: 68 65 20 77 61 79 20 69 74 20 64 65 61 6c 73 20  he way it deals 
dff0: 77 69 74 68 20 66 69 6c 65 73 2e 20 20 46 6f 72  with files.  For
e000: 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70   example, an app
e010: 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61 74  lication.** that
e020: 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 61   does not care a
e030: 62 6f 75 74 20 63 72 61 73 68 20 72 65 63 6f 76  bout crash recov
e040: 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20  ery or rollback 
e050: 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74 68  might make.** th
e060: 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75 72  e open of a jour
e070: 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f 70  nal file a no-op
e080: 2e 20 20 57 72 69 74 65 73 20 74 6f 20 74 68 69  .  Writes to thi
e090: 73 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 0a  s journal would.
e0a0: 2a 2a 20 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70  ** also be no-op
e0b0: 73 2c 20 61 6e 64 20 61 6e 79 20 61 74 74 65 6d  s, and any attem
e0c0: 70 74 20 74 6f 20 72 65 61 64 20 74 68 65 20 6a  pt to read the j
e0d0: 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 20 72 65 74  ournal would ret
e0e0: 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f  urn.** SQLITE_IO
e0f0: 45 52 52 2e 20 20 4f 72 20 74 68 65 20 69 6d 70  ERR.  Or the imp
e100: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68  lementation migh
e110: 74 20 72 65 63 6f 67 6e 69 7a 65 20 74 68 61 74  t recognize that
e120: 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66   a database.** f
e130: 69 6c 65 20 77 69 6c 6c 20 62 65 20 64 6f 69 6e  ile will be doin
e140: 67 20 70 61 67 65 2d 61 6c 69 67 6e 65 64 20 73  g page-aligned s
e150: 65 63 74 6f 72 20 72 65 61 64 73 20 61 6e 64 20  ector reads and 
e160: 77 72 69 74 65 73 20 69 6e 20 61 20 72 61 6e 64  writes in a rand
e170: 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20 61 6e 64 20  om.** order and 
e180: 73 65 74 20 75 70 20 69 74 73 20 49 2f 4f 20 73  set up its I/O s
e190: 75 62 73 79 73 74 65 6d 20 61 63 63 6f 72 64 69  ubsystem accordi
e1a0: 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  ngly..**.** SQLi
e1b0: 74 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 61 64  te might also ad
e1c0: 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c  d one of the fol
e1d0: 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20  lowing flags to 
e1e0: 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64  the xOpen method
e1f0: 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
e200: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45  <li> [SQLITE_OPE
e210: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d  N_DELETEONCLOSE]
e220: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
e230: 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d  _OPEN_EXCLUSIVE]
e240: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
e250: 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  The [SQLITE_OPEN
e260: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 20  _DELETEONCLOSE] 
e270: 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 65 20 66  flag means the f
e280: 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a  ile should be.**
e290: 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 69 74   deleted when it
e2a0: 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 5e 54 68   is closed.  ^Th
e2b0: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44  e [SQLITE_OPEN_D
e2c0: 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a  ELETEONCLOSE].**
e2d0: 20 77 69 6c 6c 20 62 65 20 73 65 74 20 66 6f 72   will be set for
e2e0: 20 54 45 4d 50 20 64 61 74 61 62 61 73 65 73 20   TEMP databases 
e2f0: 61 6e 64 20 74 68 65 69 72 20 6a 6f 75 72 6e 61  and their journa
e300: 6c 73 2c 20 74 72 61 6e 73 69 65 6e 74 0a 2a 2a  ls, transient.**
e310: 20 64 61 74 61 62 61 73 65 73 2c 20 61 6e 64 20   databases, and 
e320: 73 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a  subjournals..**.
e330: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
e340: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 20  OPEN_EXCLUSIVE] 
e350: 66 6c 61 67 20 69 73 20 61 6c 77 61 79 73 20 75  flag is always u
e360: 73 65 64 20 69 6e 20 63 6f 6e 6a 75 6e 63 74 69  sed in conjuncti
e370: 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b  on.** with the [
e380: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
e390: 54 45 5d 20 66 6c 61 67 2c 20 77 68 69 63 68 20  TE] flag, which 
e3a0: 61 72 65 20 62 6f 74 68 20 64 69 72 65 63 74 6c  are both directl
e3b0: 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75 73 20 74  y.** analogous t
e3c0: 6f 20 74 68 65 20 4f 5f 45 58 43 4c 20 61 6e 64  o the O_EXCL and
e3d0: 20 4f 5f 43 52 45 41 54 20 66 6c 61 67 73 20 6f   O_CREAT flags o
e3e0: 66 20 74 68 65 20 50 4f 53 49 58 20 6f 70 65 6e  f the POSIX open
e3f0: 28 29 0a 2a 2a 20 41 50 49 2e 20 20 54 68 65 20  ().** API.  The 
e400: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c  SQLITE_OPEN_EXCL
e410: 55 53 49 56 45 20 66 6c 61 67 2c 20 77 68 65 6e  USIVE flag, when
e420: 20 70 61 69 72 65 64 20 77 69 74 68 20 74 68 65   paired with the
e430: 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 50 45 4e   .** SQLITE_OPEN
e440: 5f 43 52 45 41 54 45 2c 20 69 73 20 75 73 65 64  _CREATE, is used
e450: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61   to indicate tha
e460: 74 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 61 6c  t file should al
e470: 77 61 79 73 0a 2a 2a 20 62 65 20 63 72 65 61 74  ways.** be creat
e480: 65 64 2c 20 61 6e 64 20 74 68 61 74 20 69 74 20  ed, and that it 
e490: 69 73 20 61 6e 20 65 72 72 6f 72 20 69 66 20 69  is an error if i
e4a0: 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 73  t already exists
e4b0: 2e 0a 2a 2a 20 49 74 20 69 73 20 3c 69 3e 6e 6f  ..** It is <i>no
e4c0: 74 3c 2f 69 3e 20 75 73 65 64 20 74 6f 20 69 6e  t</i> used to in
e4d0: 64 69 63 61 74 65 20 74 68 65 20 66 69 6c 65 20  dicate the file 
e4e0: 73 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65 64  should be opened
e4f0: 20 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73 69   .** for exclusi
e500: 76 65 20 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a  ve access..**.**
e510: 20 5e 41 74 20 6c 65 61 73 74 20 73 7a 4f 73 46   ^At least szOsF
e520: 69 6c 65 20 62 79 74 65 73 20 6f 66 20 6d 65 6d  ile bytes of mem
e530: 6f 72 79 20 61 72 65 20 61 6c 6c 6f 63 61 74 65  ory are allocate
e540: 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 74  d by SQLite.** t
e550: 6f 20 68 6f 6c 64 20 74 68 65 20 20 5b 73 71 6c  o hold the  [sql
e560: 69 74 65 33 5f 66 69 6c 65 5d 20 73 74 72 75 63  ite3_file] struc
e570: 74 75 72 65 20 70 61 73 73 65 64 20 61 73 20 74  ture passed as t
e580: 68 65 20 74 68 69 72 64 0a 2a 2a 20 61 72 67 75  he third.** argu
e590: 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 2e 20 20  ment to xOpen.  
e5a0: 54 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64  The xOpen method
e5b0: 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 74   does not have t
e5c0: 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 74 68  o.** allocate th
e5d0: 65 20 73 74 72 75 63 74 75 72 65 3b 20 69 74 20  e structure; it 
e5e0: 73 68 6f 75 6c 64 20 6a 75 73 74 20 66 69 6c 6c  should just fill
e5f0: 20 69 74 20 69 6e 2e 20 20 4e 6f 74 65 20 74 68   it in.  Note th
e600: 61 74 0a 2a 2a 20 74 68 65 20 78 4f 70 65 6e 20  at.** the xOpen 
e610: 6d 65 74 68 6f 64 20 6d 75 73 74 20 73 65 74 20  method must set 
e620: 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  the sqlite3_file
e630: 2e 70 4d 65 74 68 6f 64 73 20 74 6f 20 65 69 74  .pMethods to eit
e640: 68 65 72 0a 2a 2a 20 61 20 76 61 6c 69 64 20 5b  her.** a valid [
e650: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
e660: 64 73 5d 20 6f 62 6a 65 63 74 20 6f 72 20 74 6f  ds] object or to
e670: 20 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e 20 6d 75   NULL.  xOpen mu
e680: 73 74 20 64 6f 0a 2a 2a 20 74 68 69 73 20 65 76  st do.** this ev
e690: 65 6e 20 69 66 20 74 68 65 20 6f 70 65 6e 20 66  en if the open f
e6a0: 61 69 6c 73 2e 20 20 53 51 4c 69 74 65 20 65 78  ails.  SQLite ex
e6b0: 70 65 63 74 73 20 74 68 61 74 20 74 68 65 20 73  pects that the s
e6c0: 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74  qlite3_file.pMet
e6d0: 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65 6e 74 20  hods.** element 
e6e0: 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 66  will be valid af
e6f0: 74 65 72 20 78 4f 70 65 6e 20 72 65 74 75 72 6e  ter xOpen return
e700: 73 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20  s regardless of 
e710: 74 68 65 20 73 75 63 63 65 73 73 0a 2a 2a 20 6f  the success.** o
e720: 72 20 66 61 69 6c 75 72 65 20 6f 66 20 74 68 65  r failure of the
e730: 20 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a   xOpen call..**.
e740: 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73  ** [[sqlite3_vfs
e750: 2e 78 41 63 63 65 73 73 5d 5d 0a 2a 2a 20 5e 54  .xAccess]].** ^T
e760: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
e770: 74 20 74 6f 20 78 41 63 63 65 73 73 28 29 20 6d  t to xAccess() m
e780: 61 79 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 43  ay be [SQLITE_AC
e790: 43 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a 20  CESS_EXISTS].** 
e7a0: 74 6f 20 74 65 73 74 20 66 6f 72 20 74 68 65 20  to test for the 
e7b0: 65 78 69 73 74 65 6e 63 65 20 6f 66 20 61 20 66  existence of a f
e7c0: 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ile, or [SQLITE_
e7d0: 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45  ACCESS_READWRITE
e7e0: 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68 65  ] to.** test whe
e7f0: 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 72  ther a file is r
e800: 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74  eadable and writ
e810: 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45  able, or [SQLITE
e820: 5f 41 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a 2a  _ACCESS_READ].**
e830: 20 74 6f 20 74 65 73 74 20 77 68 65 74 68 65 72   to test whether
e840: 20 61 20 66 69 6c 65 20 69 73 20 61 74 20 6c 65   a file is at le
e850: 61 73 74 20 72 65 61 64 61 62 6c 65 2e 20 20 20  ast readable.   
e860: 54 68 65 20 66 69 6c 65 20 63 61 6e 20 62 65 20  The file can be 
e870: 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e 0a  a.** directory..
e880: 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69  **.** ^SQLite wi
e890: 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63 61  ll always alloca
e8a0: 74 65 20 61 74 20 6c 65 61 73 74 20 6d 78 50 61  te at least mxPa
e8b0: 74 68 6e 61 6d 65 2b 31 20 62 79 74 65 73 20 66  thname+1 bytes f
e8c0: 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75 74  or the.** output
e8d0: 20 62 75 66 66 65 72 20 78 46 75 6c 6c 50 61 74   buffer xFullPat
e8e0: 68 6e 61 6d 65 2e 20 20 54 68 65 20 65 78 61 63  hname.  The exac
e8f0: 74 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6f 75  t size of the ou
e900: 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69  tput buffer.** i
e910: 73 20 61 6c 73 6f 20 70 61 73 73 65 64 20 61 73  s also passed as
e920: 20 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20   a parameter to 
e930: 62 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e 20 49  both  methods. I
e940: 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66  f the output buf
e950: 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c 61  fer.** is not la
e960: 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51 4c  rge enough, [SQL
e970: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73 68  ITE_CANTOPEN] sh
e980: 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64  ould be returned
e990: 2e 20 53 69 6e 63 65 20 74 68 69 73 20 69 73 0a  . Since this is.
e9a0: 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73 20 61 20  ** handled as a 
e9b0: 66 61 74 61 6c 20 65 72 72 6f 72 20 62 79 20 53  fatal error by S
e9c0: 51 4c 69 74 65 2c 20 76 66 73 20 69 6d 70 6c 65  QLite, vfs imple
e9d0: 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c  mentations shoul
e9e0: 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74 6f  d endeavor.** to
e9f0: 20 70 72 65 76 65 6e 74 20 74 68 69 73 20 62 79   prevent this by
ea00: 20 73 65 74 74 69 6e 67 20 6d 78 50 61 74 68 6e   setting mxPathn
ea10: 61 6d 65 20 74 6f 20 61 20 73 75 66 66 69 63 69  ame to a suffici
ea20: 65 6e 74 6c 79 20 6c 61 72 67 65 20 76 61 6c 75  ently large valu
ea30: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 61  e..**.** The xRa
ea40: 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c 65  ndomness(), xSle
ea50: 65 70 28 29 2c 20 78 43 75 72 72 65 6e 74 54 69  ep(), xCurrentTi
ea60: 6d 65 28 29 2c 20 61 6e 64 20 78 43 75 72 72 65  me(), and xCurre
ea70: 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 0a 2a 2a  ntTimeInt64().**
ea80: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
ea90: 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 61 20 70  not strictly a p
eaa0: 61 72 74 20 6f 66 20 74 68 65 20 66 69 6c 65 73  art of the files
eab0: 79 73 74 65 6d 2c 20 62 75 74 20 74 68 65 79 20  ystem, but they 
eac0: 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64 20  are.** included 
ead0: 69 6e 20 74 68 65 20 56 46 53 20 73 74 72 75 63  in the VFS struc
eae0: 74 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65 74  ture for complet
eaf0: 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78 52  eness..** The xR
eb00: 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e 63  andomness() func
eb10: 74 69 6f 6e 20 61 74 74 65 6d 70 74 73 20 74 6f  tion attempts to
eb20: 20 72 65 74 75 72 6e 20 6e 42 79 74 65 73 20 62   return nBytes b
eb30: 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d  ytes.** of good-
eb40: 71 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e 65  quality randomne
eb50: 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20 54  ss into zOut.  T
eb60: 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
eb70: 69 73 0a 2a 2a 20 74 68 65 20 61 63 74 75 61 6c  is.** the actual
eb80: 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
eb90: 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f   of randomness o
eba0: 62 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20  btained..** The 
ebb0: 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 20  xSleep() method 
ebc0: 63 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c 69  causes the calli
ebd0: 6e 67 20 74 68 72 65 61 64 20 74 6f 20 73 6c 65  ng thread to sle
ebe0: 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65 61  ep for at.** lea
ebf0: 73 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  st the number of
ec00: 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20 67 69   microseconds gi
ec10: 76 65 6e 2e 20 20 5e 54 68 65 20 78 43 75 72 72  ven.  ^The xCurr
ec20: 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65 74  entTime().** met
ec30: 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 4a 75  hod returns a Ju
ec40: 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62 65 72 20  lian Day Number 
ec50: 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74 20  for the current 
ec60: 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20 61 73  date and time as
ec70: 0a 2a 2a 20 61 20 66 6c 6f 61 74 69 6e 67 20 70  .** a floating p
ec80: 6f 69 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a 20 5e  oint value..** ^
ec90: 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65  The xCurrentTime
eca0: 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 72  Int64() method r
ecb0: 65 74 75 72 6e 73 2c 20 61 73 20 61 6e 20 69 6e  eturns, as an in
ecc0: 74 65 67 65 72 2c 20 74 68 65 20 4a 75 6c 69 61  teger, the Julia
ecd0: 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d 62 65 72 20  n.** Day Number 
ece0: 6d 75 6c 74 69 70 6c 69 65 64 20 62 79 20 38 36  multiplied by 86
ecf0: 34 30 30 30 30 30 20 28 74 68 65 20 6e 75 6d 62  400000 (the numb
ed00: 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e  er of millisecon
ed10: 64 73 20 69 6e 20 0a 2a 2a 20 61 20 32 34 2d 68  ds in .** a 24-h
ed20: 6f 75 72 20 64 61 79 29 2e 20 20 0a 2a 2a 20 5e  our day).  .** ^
ed30: 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20  SQLite will use 
ed40: 74 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65  the xCurrentTime
ed50: 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 74  Int64() method t
ed60: 6f 20 67 65 74 20 74 68 65 20 63 75 72 72 65 6e  o get the curren
ed70: 74 0a 2a 2a 20 64 61 74 65 20 61 6e 64 20 74 69  t.** date and ti
ed80: 6d 65 20 69 66 20 74 68 61 74 20 6d 65 74 68 6f  me if that metho
ed90: 64 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 28  d is available (
eda0: 69 66 20 69 56 65 72 73 69 6f 6e 20 69 73 20 32  if iVersion is 2
edb0: 20 6f 72 20 0a 2a 2a 20 67 72 65 61 74 65 72 20   or .** greater 
edc0: 61 6e 64 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  and the function
edd0: 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20   pointer is not 
ede0: 4e 55 4c 4c 29 20 61 6e 64 20 77 69 6c 6c 20 66  NULL) and will f
edf0: 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f 20 78  all back.** to x
ee00: 43 75 72 72 65 6e 74 54 69 6d 65 28 29 20 69 66  CurrentTime() if
ee10: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74   xCurrentTimeInt
ee20: 36 34 28 29 20 69 73 20 75 6e 61 76 61 69 6c 61  64() is unavaila
ee30: 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ble..**.** ^The 
ee40: 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 29  xSetSystemCall()
ee50: 2c 20 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c  , xGetSystemCall
ee60: 28 29 2c 20 61 6e 64 20 78 4e 65 73 74 53 79 73  (), and xNestSys
ee70: 74 65 6d 43 61 6c 6c 28 29 20 69 6e 74 65 72 66  temCall() interf
ee80: 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 20  aces.** are not 
ee90: 75 73 65 64 20 62 79 20 74 68 65 20 53 51 4c 69  used by the SQLi
eea0: 74 65 20 63 6f 72 65 2e 20 20 54 68 65 73 65 20  te core.  These 
eeb0: 6f 70 74 69 6f 6e 61 6c 20 69 6e 74 65 72 66 61  optional interfa
eec0: 63 65 73 20 61 72 65 20 70 72 6f 76 69 64 65 64  ces are provided
eed0: 0a 2a 2a 20 62 79 20 73 6f 6d 65 20 56 46 53 65  .** by some VFSe
eee0: 73 20 74 6f 20 66 61 63 69 6c 69 74 61 74 65 20  s to facilitate 
eef0: 74 65 73 74 69 6e 67 20 6f 66 20 74 68 65 20 56  testing of the V
ef00: 46 53 20 63 6f 64 65 2e 20 42 79 20 6f 76 65 72  FS code. By over
ef10: 72 69 64 69 6e 67 20 0a 2a 2a 20 73 79 73 74 65  riding .** syste
ef20: 6d 20 63 61 6c 6c 73 20 77 69 74 68 20 66 75 6e  m calls with fun
ef30: 63 74 69 6f 6e 73 20 75 6e 64 65 72 20 69 74 73  ctions under its
ef40: 20 63 6f 6e 74 72 6f 6c 2c 20 61 20 74 65 73 74   control, a test
ef50: 20 70 72 6f 67 72 61 6d 20 63 61 6e 0a 2a 2a 20   program can.** 
ef60: 73 69 6d 75 6c 61 74 65 20 66 61 75 6c 74 73 20  simulate faults 
ef70: 61 6e 64 20 65 72 72 6f 72 20 63 6f 6e 64 69 74  and error condit
ef80: 69 6f 6e 73 20 74 68 61 74 20 77 6f 75 6c 64 20  ions that would 
ef90: 6f 74 68 65 72 77 69 73 65 20 62 65 20 64 69 66  otherwise be dif
efa0: 66 69 63 75 6c 74 0a 2a 2a 20 6f 72 20 69 6d 70  ficult.** or imp
efb0: 6f 73 73 69 62 6c 65 20 74 6f 20 69 6e 64 75 63  ossible to induc
efc0: 65 2e 20 20 54 68 65 20 73 65 74 20 6f 66 20 73  e.  The set of s
efd0: 79 73 74 65 6d 20 63 61 6c 6c 73 20 74 68 61 74  ystem calls that
efe0: 20 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64 64   can be overridd
eff0: 65 6e 0a 2a 2a 20 76 61 72 69 65 73 20 66 72 6f  en.** varies fro
f000: 6d 20 6f 6e 65 20 56 46 53 20 74 6f 20 61 6e 6f  m one VFS to ano
f010: 74 68 65 72 2c 20 61 6e 64 20 66 72 6f 6d 20 6f  ther, and from o
f020: 6e 65 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68  ne version of th
f030: 65 20 73 61 6d 65 20 56 46 53 20 74 6f 20 74 68  e same VFS to th
f040: 65 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70 70 6c  e.** next.  Appl
f050: 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 75 73  ications that us
f060: 65 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63  e these interfac
f070: 65 73 20 6d 75 73 74 20 62 65 20 70 72 65 70 61  es must be prepa
f080: 72 65 64 20 66 6f 72 20 61 6e 79 0a 2a 2a 20 6f  red for any.** o
f090: 72 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 69  r all of these i
f0a0: 6e 74 65 72 66 61 63 65 73 20 74 6f 20 62 65 20  nterfaces to be 
f0b0: 4e 55 4c 4c 20 6f 72 20 66 6f 72 20 74 68 65 69  NULL or for thei
f0c0: 72 20 62 65 68 61 76 69 6f 72 20 74 6f 20 63 68  r behavior to ch
f0d0: 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f 6e 65  ange.** from one
f0e0: 20 72 65 6c 65 61 73 65 20 74 6f 20 74 68 65 20   release to the 
f0f0: 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69  next.  Applicati
f100: 6f 6e 73 20 6d 75 73 74 20 6e 6f 74 20 61 74 74  ons must not att
f110: 65 6d 70 74 20 74 6f 20 61 63 63 65 73 73 0a 2a  empt to access.*
f120: 2a 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 6d  * any of these m
f130: 65 74 68 6f 64 73 20 69 66 20 74 68 65 20 69 56  ethods if the iV
f140: 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 56 46  ersion of the VF
f150: 53 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 33  S is less than 3
f160: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
f170: 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20  uct sqlite3_vfs 
f180: 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a 74 79 70  sqlite3_vfs;.typ
f190: 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69  edef void (*sqli
f1a0: 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29  te3_syscall_ptr)
f1b0: 28 76 6f 69 64 29 3b 0a 73 74 72 75 63 74 20 73  (void);.struct s
f1c0: 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20 69  qlite3_vfs {.  i
f1d0: 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20 20  nt iVersion;    
f1e0: 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75 63          /* Struc
f1f0: 74 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d  ture version num
f200: 62 65 72 20 28 63 75 72 72 65 6e 74 6c 79 20 33  ber (currently 3
f210: 29 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 46  ) */.  int szOsF
f220: 69 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20 20  ile;            
f230: 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63 6c  /* Size of subcl
f240: 61 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66 69  assed sqlite3_fi
f250: 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 61  le */.  int mxPa
f260: 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20 20  thname;         
f270: 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c 65   /* Maximum file
f280: 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74 68   pathname length
f290: 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76 66   */.  sqlite3_vf
f2a0: 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20 2f  s *pNext;      /
f2b0: 2a 20 4e 65 78 74 20 72 65 67 69 73 74 65 72 65  * Next registere
f2c0: 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 74  d VFS */.  const
f2d0: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 20   char *zName;   
f2e0: 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74      /* Name of t
f2f0: 68 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c 65  his virtual file
f300: 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f 69   system */.  voi
f310: 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20  d *pAppData;    
f320: 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65 72        /* Pointer
f330: 20 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   to application-
f340: 73 70 65 63 69 66 69 63 20 64 61 74 61 20 2a 2f  specific data */
f350: 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28  .  int (*xOpen)(
f360: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
f370: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
f380: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 0a   sqlite3_file*,.
f390: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69                 i
f3a0: 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70  nt flags, int *p
f3b0: 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e 74  OutFlags);.  int
f3c0: 20 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c 69   (*xDelete)(sqli
f3d0: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
f3e0: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74  char *zName, int
f3f0: 20 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e 74   syncDir);.  int
f400: 20 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c 69   (*xAccess)(sqli
f410: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
f420: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74  char *zName, int
f430: 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52 65   flags, int *pRe
f440: 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  sOut);.  int (*x
f450: 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73 71  FullPathname)(sq
f460: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
f470: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69  t char *zName, i
f480: 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a  nt nOut, char *z
f490: 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a  Out);.  void *(*
f4a0: 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65 33  xDlOpen)(sqlite3
f4b0: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
f4c0: 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a 20  r *zFilename);. 
f4d0: 20 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f 72   void (*xDlError
f4e0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
f4f0: 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20  int nByte, char 
f500: 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f 69  *zErrMsg);.  voi
f510: 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73 71  d (*(*xDlSym)(sq
f520: 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64 2a  lite3_vfs*,void*
f530: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53  , const char *zS
f540: 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a 20  ymbol))(void);. 
f550: 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65   void (*xDlClose
f560: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
f570: 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  void*);.  int (*
f580: 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c  xRandomness)(sql
f590: 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e  ite3_vfs*, int n
f5a0: 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74  Byte, char *zOut
f5b0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65 65  );.  int (*xSlee
f5c0: 70 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  p)(sqlite3_vfs*,
f5d0: 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64   int microsecond
f5e0: 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75 72  s);.  int (*xCur
f5f0: 72 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74 65  rentTime)(sqlite
f600: 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29  3_vfs*, double*)
f610: 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c 61  ;.  int (*xGetLa
f620: 73 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33  stError)(sqlite3
f630: 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61 72  _vfs*, int, char
f640: 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54   *);.  /*.  ** T
f650: 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65  he methods above
f660: 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 20   are in version 
f670: 31 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f  1 of the sqlite_
f680: 76 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a 2a 20  vfs object.  ** 
f690: 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 6f  definition.  Tho
f6a0: 73 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 61  se that follow a
f6b0: 72 65 20 61 64 64 65 64 20 69 6e 20 76 65 72 73  re added in vers
f6c0: 69 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72 0a 20  ion 2 or later. 
f6d0: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 43 75 72   */.  int (*xCur
f6e0: 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 29 28 73  rentTimeInt64)(s
f6f0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 73 71 6c  qlite3_vfs*, sql
f700: 69 74 65 33 5f 69 6e 74 36 34 2a 29 3b 0a 20 20  ite3_int64*);.  
f710: 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68  /*.  ** The meth
f720: 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e  ods above are in
f730: 20 76 65 72 73 69 6f 6e 73 20 31 20 61 6e 64 20   versions 1 and 
f740: 32 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f  2 of the sqlite_
f750: 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a  vfs object..  **
f760: 20 54 68 6f 73 65 20 62 65 6c 6f 77 20 61 72 65   Those below are
f770: 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 61   for version 3 a
f780: 6e 64 20 67 72 65 61 74 65 72 2e 0a 20 20 2a 2f  nd greater..  */
f790: 0a 20 20 69 6e 74 20 28 2a 78 53 65 74 53 79 73  .  int (*xSetSys
f7a0: 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33  temCall)(sqlite3
f7b0: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
f7c0: 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65  r *zName, sqlite
f7d0: 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 3b 0a  3_syscall_ptr);.
f7e0: 20 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c    sqlite3_syscal
f7f0: 6c 5f 70 74 72 20 28 2a 78 47 65 74 53 79 73 74  l_ptr (*xGetSyst
f800: 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f  emCall)(sqlite3_
f810: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
f820: 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f 6e 73   *zName);.  cons
f830: 74 20 63 68 61 72 20 2a 28 2a 78 4e 65 78 74 53  t char *(*xNextS
f840: 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74  ystemCall)(sqlit
f850: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
f860: 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 2f  har *zName);.  /
f870: 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f  *.  ** The metho
f880: 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20  ds above are in 
f890: 76 65 72 73 69 6f 6e 73 20 31 20 74 68 72 6f 75  versions 1 throu
f8a0: 67 68 20 33 20 6f 66 20 74 68 65 20 73 71 6c 69  gh 3 of the sqli
f8b0: 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20  te_vfs object.. 
f8c0: 20 2a 2a 20 4e 65 77 20 66 69 65 6c 64 73 20 6d   ** New fields m
f8d0: 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 69  ay be appended i
f8e0: 6e 20 66 69 67 75 72 65 20 76 65 72 73 69 6f 6e  n figure version
f8f0: 73 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f 6e  s.  The iVersion
f900: 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c 6c  .  ** value will
f910: 20 69 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e 65   increment whene
f920: 76 65 72 20 74 68 69 73 20 68 61 70 70 65 6e 73  ver this happens
f930: 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  . .  */.};../*.*
f940: 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67  * CAPI3REF: Flag
f950: 73 20 66 6f 72 20 74 68 65 20 78 41 63 63 65 73  s for the xAcces
f960: 73 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a  s VFS method.**.
f970: 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72  ** These integer
f980: 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20 62   constants can b
f990: 65 20 75 73 65 64 20 61 73 20 74 68 65 20 74 68  e used as the th
f9a0: 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
f9b0: 0a 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73 20  .** the xAccess 
f9c0: 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71  method of an [sq
f9d0: 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
f9e0: 74 2e 20 20 54 68 65 79 20 64 65 74 65 72 6d 69  t.  They determi
f9f0: 6e 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64 20  ne.** what kind 
fa00: 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e 73 20 74  of permissions t
fa10: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
fa20: 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72  d is looking for
fa30: 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45  ..** With SQLITE
fa40: 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 2c 20  _ACCESS_EXISTS, 
fa50: 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68  the xAccess meth
fa60: 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65  od.** simply che
fa70: 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20  cks whether the 
fa80: 66 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a 20  file exists..** 
fa90: 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45  With SQLITE_ACCE
faa0: 53 53 5f 52 45 41 44 57 52 49 54 45 2c 20 74 68  SS_READWRITE, th
fab0: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
fac0: 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68  .** checks wheth
fad0: 65 72 20 74 68 65 20 6e 61 6d 65 64 20 64 69 72  er the named dir
fae0: 65 63 74 6f 72 79 20 69 73 20 62 6f 74 68 20 72  ectory is both r
faf0: 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74  eadable and writ
fb00: 61 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74 68 65  able.** (in othe
fb10: 72 20 77 6f 72 64 73 2c 20 69 66 20 66 69 6c 65  r words, if file
fb20: 73 20 63 61 6e 20 62 65 20 61 64 64 65 64 2c 20  s can be added, 
fb30: 72 65 6d 6f 76 65 64 2c 20 61 6e 64 20 72 65 6e  removed, and ren
fb40: 61 6d 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 74  amed within.** t
fb50: 68 65 20 64 69 72 65 63 74 6f 72 79 29 2e 0a 2a  he directory)..*
fb60: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43  * The SQLITE_ACC
fb70: 45 53 53 5f 52 45 41 44 57 52 49 54 45 20 63 6f  ESS_READWRITE co
fb80: 6e 73 74 61 6e 74 20 69 73 20 63 75 72 72 65 6e  nstant is curren
fb90: 74 6c 79 20 75 73 65 64 20 6f 6e 6c 79 20 62 79  tly used only by
fba0: 20 74 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73 74   the.** [temp_st
fbb0: 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72  ore_directory pr
fbc0: 61 67 6d 61 5d 2c 20 74 68 6f 75 67 68 20 74 68  agma], though th
fbd0: 69 73 20 63 6f 75 6c 64 20 63 68 61 6e 67 65 20  is could change 
fbe0: 69 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a 20 72  in a future.** r
fbf0: 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65  elease of SQLite
fc00: 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45  ..** With SQLITE
fc10: 5f 41 43 43 45 53 53 5f 52 45 41 44 2c 20 74 68  _ACCESS_READ, th
fc20: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
fc30: 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68  .** checks wheth
fc40: 65 72 20 74 68 65 20 66 69 6c 65 20 69 73 20 72  er the file is r
fc50: 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20 53 51  eadable.  The SQ
fc60: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
fc70: 20 63 6f 6e 73 74 61 6e 74 20 69 73 0a 2a 2a 20   constant is.** 
fc80: 63 75 72 72 65 6e 74 6c 79 20 75 6e 75 73 65 64  currently unused
fc90: 2c 20 74 68 6f 75 67 68 20 69 74 20 6d 69 67 68  , though it migh
fca0: 74 20 62 65 20 75 73 65 64 20 69 6e 20 61 20 66  t be used in a f
fcb0: 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66  uture release of
fcc0: 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23  .** SQLite..*/.#
fcd0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43  define SQLITE_AC
fce0: 43 45 53 53 5f 45 58 49 53 54 53 20 20 20 20 30  CESS_EXISTS    0
fcf0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
fd00: 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45  ACCESS_READWRITE
fd10: 20 31 20 20 20 2f 2a 20 55 73 65 64 20 62 79 20   1   /* Used by 
fd20: 50 52 41 47 4d 41 20 74 65 6d 70 5f 73 74 6f 72  PRAGMA temp_stor
fd30: 65 5f 64 69 72 65 63 74 6f 72 79 20 2a 2f 0a 23  e_directory */.#
fd40: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43  define SQLITE_AC
fd50: 43 45 53 53 5f 52 45 41 44 20 20 20 20 20 20 32  CESS_READ      2
fd60: 20 20 20 2f 2a 20 55 6e 75 73 65 64 20 2a 2f 0a     /* Unused */.
fd70: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
fd80: 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78   Flags for the x
fd90: 53 68 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74 68  ShmLock VFS meth
fda0: 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69  od.**.** These i
fdb0: 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73  nteger constants
fdc0: 20 64 65 66 69 6e 65 20 74 68 65 20 76 61 72 69   define the vari
fdd0: 6f 75 73 20 6c 6f 63 6b 69 6e 67 20 6f 70 65 72  ous locking oper
fde0: 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77 65  ations.** allowe
fdf0: 64 20 62 79 20 74 68 65 20 78 53 68 6d 4c 6f 63  d by the xShmLoc
fe00: 6b 20 6d 65 74 68 6f 64 20 6f 66 20 5b 73 71 6c  k method of [sql
fe10: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
fe20: 2e 20 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77  .  The.** follow
fe30: 69 6e 67 20 61 72 65 20 74 68 65 20 6f 6e 6c 79  ing are the only
fe40: 20 6c 65 67 61 6c 20 63 6f 6d 62 69 6e 61 74 69   legal combinati
fe50: 6f 6e 73 20 6f 66 20 66 6c 61 67 73 20 74 6f 20  ons of flags to 
fe60: 74 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b 20  the.** xShmLock 
fe70: 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75  method:.**.** <u
fe80: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49  l>.** <li>  SQLI
fe90: 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51  TE_SHM_LOCK | SQ
fea0: 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a  LITE_SHM_SHARED.
feb0: 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f  ** <li>  SQLITE_
fec0: 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54  SHM_LOCK | SQLIT
fed0: 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a  E_SHM_EXCLUSIVE.
fee0: 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f  ** <li>  SQLITE_
fef0: 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c  SHM_UNLOCK | SQL
ff00: 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a  ITE_SHM_SHARED.*
ff10: 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53  * <li>  SQLITE_S
ff20: 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49  HM_UNLOCK | SQLI
ff30: 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45  TE_SHM_EXCLUSIVE
ff40: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
ff50: 57 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c 20  When unlocking, 
ff60: 74 68 65 20 73 61 6d 65 20 53 48 41 52 45 44 20  the same SHARED 
ff70: 6f 72 20 45 58 43 4c 55 53 49 56 45 20 66 6c 61  or EXCLUSIVE fla
ff80: 67 20 6d 75 73 74 20 62 65 20 73 75 70 70 6c 69  g must be suppli
ff90: 65 64 20 61 73 0a 2a 2a 20 77 61 73 20 67 69 76  ed as.** was giv
ffa0: 65 6e 20 6e 6f 20 74 68 65 20 63 6f 72 72 65 73  en no the corres
ffb0: 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20 20 0a  ponding lock.  .
ffc0: 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f  **.** The xShmLo
ffd0: 63 6b 20 6d 65 74 68 6f 64 20 63 61 6e 20 74 72  ck method can tr
ffe0: 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e  ansition between
fff0: 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 53 48   unlocked and SH
10000 41 52 45 44 20 6f 72 0a 2a 2a 20 62 65 74 77 65  ARED or.** betwe
10010 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20  en unlocked and 
10020 45 58 43 4c 55 53 49 56 45 2e 20 20 49 74 20 63  EXCLUSIVE.  It c
10030 61 6e 6e 6f 74 20 74 72 61 6e 73 69 74 69 6f 6e  annot transition
10040 20 62 65 74 77 65 65 6e 20 53 48 41 52 45 44 0a   between SHARED.
10050 2a 2a 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45  ** and EXCLUSIVE
10060 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
10070 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 20  ITE_SHM_UNLOCK  
10080 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
10090 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 20  QLITE_SHM_LOCK  
100a0 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65         2.#define
100b0 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52   SQLITE_SHM_SHAR
100c0 45 44 20 20 20 20 20 20 20 34 0a 23 64 65 66 69  ED       4.#defi
100d0 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58  ne SQLITE_SHM_EX
100e0 43 4c 55 53 49 56 45 20 20 20 20 38 0a 0a 2f 2a  CLUSIVE    8../*
100f0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 61  .** CAPI3REF: Ma
10100 78 69 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b 20 69  ximum xShmLock i
10110 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ndex.**.** The x
10120 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f  ShmLock method o
10130 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  n [sqlite3_io_me
10140 74 68 6f 64 73 5d 20 6d 61 79 20 75 73 65 20 76  thods] may use v
10150 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e  alues.** between
10160 20 30 20 61 6e 64 20 74 68 69 73 20 75 70 70 65   0 and this uppe
10170 72 20 62 6f 75 6e 64 20 61 73 20 69 74 73 20 22  r bound as its "
10180 6f 66 66 73 65 74 22 20 61 72 67 75 6d 65 6e 74  offset" argument
10190 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20  ..** The SQLite 
101a0 63 6f 72 65 20 77 69 6c 6c 20 6e 65 76 65 72 20  core will never 
101b0 61 74 74 65 6d 70 74 20 74 6f 20 61 63 71 75 69  attempt to acqui
101c0 72 65 20 6f 72 20 72 65 6c 65 61 73 65 20 61 0a  re or release a.
101d0 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73 69 64 65 20  ** lock outside 
101e0 6f 66 20 74 68 69 73 20 72 61 6e 67 65 0a 2a 2f  of this range.*/
101f0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
10200 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20 20 20  SHM_NLOCK       
10210 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   8.../*.** CAPI3
10220 52 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65 20  REF: Initialize 
10230 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61  The SQLite Libra
10240 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ry.**.** ^The sq
10250 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
10260 28 29 20 72 6f 75 74 69 6e 65 20 69 6e 69 74 69  () routine initi
10270 61 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53 51  alizes the.** SQ
10280 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 5e  Lite library.  ^
10290 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74  The sqlite3_shut
102a0 64 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a  down() routine.*
102b0 2a 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 6e  * deallocates an
102c0 79 20 72 65 73 6f 75 72 63 65 73 20 74 68 61 74  y resources that
102d0 20 77 65 72 65 20 61 6c 6c 6f 63 61 74 65 64 20   were allocated 
102e0 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  by sqlite3_initi
102f0 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65 73  alize()..** Thes
10300 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 64  e routines are d
10310 65 73 69 67 6e 65 64 20 74 6f 20 61 69 64 20 69  esigned to aid i
10320 6e 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61  n process initia
10330 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20  lization and.** 
10340 73 68 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62 65  shutdown on embe
10350 64 64 65 64 20 73 79 73 74 65 6d 73 2e 20 20 57  dded systems.  W
10360 6f 72 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c 69  orkstation appli
10370 63 61 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a 2a  cations using.**
10380 20 53 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c 79   SQLite normally
10390 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20   do not need to 
103a0 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 6f 66  invoke either of
103b0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e   these routines.
103c0 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f  .**.** A call to
103d0 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
103e0 69 7a 65 28 29 20 69 73 20 61 6e 20 22 65 66 66  ize() is an "eff
103f0 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20  ective" call if 
10400 69 74 20 69 73 0a 2a 2a 20 74 68 65 20 66 69 72  it is.** the fir
10410 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f  st time sqlite3_
10420 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20  initialize() is 
10430 69 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67 20 74  invoked during t
10440 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a  he lifetime of.*
10450 2a 20 74 68 65 20 70 72 6f 63 65 73 73 2c 20 6f  * the process, o
10460 72 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66  r if it is the f
10470 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65  irst time sqlite
10480 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
10490 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c  s invoked.** fol
104a0 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f  lowing a call to
104b0 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
104c0 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e 20  n().  ^(Only an 
104d0 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 0a 2a  effective call.*
104e0 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e 69  * of sqlite3_ini
104f0 74 69 61 6c 69 7a 65 28 29 20 64 6f 65 73 20 61  tialize() does a
10500 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  ny initializatio
10510 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 63 61  n.  All other ca
10520 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d 6c  lls.** are harml
10530 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a  ess no-ops.)^.**
10540 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71  .** A call to sq
10550 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
10560 20 69 73 20 61 6e 20 22 65 66 66 65 63 74 69 76   is an "effectiv
10570 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73  e" call if it is
10580 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 63 61   the first.** ca
10590 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68  ll to sqlite3_sh
105a0 75 74 64 6f 77 6e 28 29 20 73 69 6e 63 65 20 74  utdown() since t
105b0 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f  he last sqlite3_
105c0 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20 20 5e  initialize().  ^
105d0 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66 65  (Only.** an effe
105e0 63 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 73 71  ctive call to sq
105f0 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
10600 20 64 6f 65 73 20 61 6e 79 20 64 65 69 6e 69 74   does any deinit
10610 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41  ialization..** A
10620 6c 6c 20 6f 74 68 65 72 20 76 61 6c 69 64 20 63  ll other valid c
10630 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
10640 73 68 75 74 64 6f 77 6e 28 29 20 61 72 65 20 68  shutdown() are h
10650 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29  armless no-ops.)
10660 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ^.**.** The sqli
10670 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
10680 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 68   interface is th
10690 72 65 61 64 73 61 66 65 2c 20 62 75 74 20 73 71  readsafe, but sq
106a0 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
106b0 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68 65  .** is not.  The
106c0 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
106d0 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d 75  n() interface mu
106e0 73 74 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65  st only be calle
106f0 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e 67  d from a.** sing
10700 6c 65 20 74 68 72 65 61 64 2e 20 20 41 6c 6c 20  le thread.  All 
10710 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63  open [database c
10720 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73 74  onnections] must
10730 20 62 65 20 63 6c 6f 73 65 64 20 61 6e 64 20 61   be closed and a
10740 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c 69  ll.** other SQLi
10750 74 65 20 72 65 73 6f 75 72 63 65 73 20 6d 75 73  te resources mus
10760 74 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64  t be deallocated
10770 20 70 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b 69   prior to invoki
10780 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 68  ng.** sqlite3_sh
10790 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20  utdown()..**.** 
107a0 41 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68 69 6e  Among other thin
107b0 67 73 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e 69  gs, ^sqlite3_ini
107c0 74 69 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20 69  tialize() will i
107d0 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33  nvoke.** sqlite3
107e0 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d  _os_init().  Sim
107f0 69 6c 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65 33  ilarly, ^sqlite3
10800 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 77  _shutdown().** w
10810 69 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74  ill invoke sqlit
10820 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a  e3_os_end()..**.
10830 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
10840 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75  initialize() rou
10850 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51  tine returns [SQ
10860 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63  LITE_OK] on succ
10870 65 73 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72 20  ess..** ^If for 
10880 73 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71 6c  some reason, sql
10890 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
108a0 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 69  ) is unable to i
108b0 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68 65  nitialize.** the
108c0 20 6c 69 62 72 61 72 79 20 28 70 65 72 68 61 70   library (perhap
108d0 73 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74  s it is unable t
108e0 6f 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65 65  o allocate a nee
108f0 64 65 64 20 72 65 73 6f 75 72 63 65 20 73 75 63  ded resource suc
10900 68 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65 78 29  h.** as a mutex)
10910 20 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20 5b   it returns an [
10920 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68 65  error code] othe
10930 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f  r than [SQLITE_O
10940 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  K]..**.** ^The s
10950 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
10960 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63  e() routine is c
10970 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79  alled internally
10980 20 62 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a   by many other.*
10990 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  * SQLite interfa
109a0 63 65 73 20 73 6f 20 74 68 61 74 20 61 6e 20 61  ces so that an a
109b0 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 75 61 6c  pplication usual
109c0 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64  ly does not need
109d0 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71   to.** invoke sq
109e0 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
109f0 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 46 6f  () directly.  Fo
10a00 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c 69  r example, [sqli
10a10 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63  te3_open()].** c
10a20 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e 69  alls sqlite3_ini
10a30 74 69 61 6c 69 7a 65 28 29 20 73 6f 20 74 68 65  tialize() so the
10a40 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20   SQLite library 
10a50 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69  will be automati
10a60 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61 6c  cally.** initial
10a70 69 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74  ized when [sqlit
10a80 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63 61  e3_open()] is ca
10a90 6c 6c 65 64 20 69 66 20 69 74 20 68 61 73 20 6e  lled if it has n
10aa0 6f 74 20 62 65 20 69 6e 69 74 69 61 6c 69 7a 65  ot be initialize
10ab0 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20 5e  d.** already.  ^
10ac0 48 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c 69  However, if SQLi
10ad0 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
10ae0 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ith the [SQLITE_
10af0 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a  OMIT_AUTOINIT].*
10b00 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  * compile-time o
10b10 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20  ption, then the 
10b20 61 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73 20  automatic calls 
10b30 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  to sqlite3_initi
10b40 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20 6f  alize().** are o
10b50 6d 69 74 74 65 64 20 61 6e 64 20 74 68 65 20 61  mitted and the a
10b60 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
10b70 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e 69  call sqlite3_ini
10b80 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74  tialize() direct
10b90 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 75  ly.** prior to u
10ba0 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53  sing any other S
10bb0 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e  QLite interface.
10bc0 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70 6f    For maximum po
10bd0 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69 74  rtability,.** it
10be0 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
10bf0 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e  that application
10c00 73 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65 20  s always invoke 
10c10 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
10c20 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c 79  ze().** directly
10c30 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20   prior to using 
10c40 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65  any other SQLite
10c50 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46 75 74   interface.  Fut
10c60 75 72 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a 20  ure releases.** 
10c70 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 72 65  of SQLite may re
10c80 71 75 69 72 65 20 74 68 69 73 2e 20 20 49 6e 20  quire this.  In 
10c90 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65  other words, the
10ca0 20 62 65 68 61 76 69 6f 72 20 65 78 68 69 62 69   behavior exhibi
10cb0 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69  ted.** when SQLi
10cc0 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
10cd0 69 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54  ith [SQLITE_OMIT
10ce0 5f 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68 74  _AUTOINIT] might
10cf0 20 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 64   become the.** d
10d00 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20  efault behavior 
10d10 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72  in some future r
10d20 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65  elease of SQLite
10d30 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
10d40 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72 6f  te3_os_init() ro
10d50 75 74 69 6e 65 20 64 6f 65 73 20 6f 70 65 72 61  utine does opera
10d60 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63  ting-system spec
10d70 69 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c 69  ific.** initiali
10d80 7a 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 53 51  zation of the SQ
10d90 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 54  Lite library.  T
10da0 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  he sqlite3_os_en
10db0 64 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75  d().** routine u
10dc0 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65 63 74  ndoes the effect
10dd0 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69   of sqlite3_os_i
10de0 6e 69 74 28 29 2e 20 20 54 79 70 69 63 61 6c 20  nit().  Typical 
10df0 74 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 6d  tasks.** perform
10e00 65 64 20 62 79 20 74 68 65 73 65 20 72 6f 75 74  ed by these rout
10e10 69 6e 65 73 20 69 6e 63 6c 75 64 65 20 61 6c 6c  ines include all
10e20 6f 63 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c 6c  ocation or deall
10e30 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74  ocation.** of st
10e40 61 74 69 63 20 72 65 73 6f 75 72 63 65 73 2c 20  atic resources, 
10e50 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f  initialization o
10e60 66 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c  f global variabl
10e70 65 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20 75  es,.** setting u
10e80 70 20 61 20 64 65 66 61 75 6c 74 20 5b 73 71 6c  p a default [sql
10e90 69 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c 65  ite3_vfs] module
10ea0 2c 20 6f 72 20 73 65 74 74 69 6e 67 20 75 70 0a  , or setting up.
10eb0 2a 2a 20 61 20 64 65 66 61 75 6c 74 20 63 6f 6e  ** a default con
10ec0 66 69 67 75 72 61 74 69 6f 6e 20 75 73 69 6e 67  figuration using
10ed0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
10ee0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61  ()]..**.** The a
10ef0 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
10f00 64 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 65  d never invoke e
10f10 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f 6f 73  ither sqlite3_os
10f20 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73 71  _init().** or sq
10f30 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 64  lite3_os_end() d
10f40 69 72 65 63 74 6c 79 2e 20 20 54 68 65 20 61 70  irectly.  The ap
10f50 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
10f60 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20   only invoke.** 
10f70 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
10f80 7a 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  ze() and sqlite3
10f90 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 54 68  _shutdown().  Th
10fa0 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  e sqlite3_os_ini
10fb0 74 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  t().** interface
10fc0 20 69 73 20 63 61 6c 6c 65 64 20 61 75 74 6f 6d   is called autom
10fd0 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69  atically by sqli
10fe0 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
10ff0 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   and.** sqlite3_
11000 6f 73 5f 65 6e 64 28 29 20 69 73 20 63 61 6c 6c  os_end() is call
11010 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73 68  ed by sqlite3_sh
11020 75 74 64 6f 77 6e 28 29 2e 20 20 41 70 70 72 6f  utdown().  Appro
11030 70 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d  priate.** implem
11040 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 73 71  entations for sq
11050 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20  lite3_os_init() 
11060 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  and sqlite3_os_e
11070 6e 64 28 29 0a 2a 2a 20 61 72 65 20 62 75 69 6c  nd().** are buil
11080 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 77 68  t into SQLite wh
11090 65 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c 65  en it is compile
110a0 64 20 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e 64  d for Unix, Wind
110b0 6f 77 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a 2a  ows, or OS/2..**
110c0 20 57 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62 75   When [custom bu
110d0 69 6c 64 73 20 7c 20 62 75 69 6c 74 20 66 6f 72  ilds | built for
110e0 20 6f 74 68 65 72 20 70 6c 61 74 66 6f 72 6d 73   other platforms
110f0 5d 0a 2a 2a 20 28 75 73 69 6e 67 20 74 68 65 20  ].** (using the 
11100 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45 52  [SQLITE_OS_OTHER
11110 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  =1] compile-time
11120 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65 20  .** option) the 
11130 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
11140 20 73 75 70 70 6c 79 20 61 20 73 75 69 74 61 62   supply a suitab
11150 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
11160 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  n for.** sqlite3
11170 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73  _os_init() and s
11180 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e  qlite3_os_end().
11190 20 20 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e    An application
111a0 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d 70  -supplied.** imp
111b0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73  lementation of s
111c0 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
111d0 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65   or sqlite3_os_e
111e0 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65 74  nd().** must ret
111f0 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  urn [SQLITE_OK] 
11200 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20 73  on success and s
11210 6f 6d 65 20 6f 74 68 65 72 20 5b 65 72 72 6f 72  ome other [error
11220 20 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66   code] upon.** f
11230 61 69 6c 75 72 65 2e 0a 2a 2f 0a 53 51 4c 49 54  ailure..*/.SQLIT
11240 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
11250 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 76 6f 69  3_initialize(voi
11260 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  d);.SQLITE_API i
11270 6e 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  nt sqlite3_shutd
11280 6f 77 6e 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54  own(void);.SQLIT
11290 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
112a0 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b  3_os_init(void);
112b0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
112c0 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 76  sqlite3_os_end(v
112d0 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  oid);../*.** CAP
112e0 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 69  I3REF: Configuri
112f0 6e 67 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69  ng The SQLite Li
11300 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65 20  brary.**.** The 
11310 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
11320 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73   interface is us
11330 65 64 20 74 6f 20 6d 61 6b 65 20 67 6c 6f 62 61  ed to make globa
11340 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a  l configuration.
11350 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 53 51  ** changes to SQ
11360 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f  Lite in order to
11370 20 74 75 6e 65 20 53 51 4c 69 74 65 20 74 6f 20   tune SQLite to 
11380 74 68 65 20 73 70 65 63 69 66 69 63 20 6e 65 65  the specific nee
11390 64 73 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70  ds of.** the app
113a0 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68 65 20 64  lication.  The d
113b0 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61  efault configura
113c0 74 69 6f 6e 20 69 73 20 72 65 63 6f 6d 6d 65 6e  tion is recommen
113d0 64 65 64 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20  ded for most.** 
113e0 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6e 64  applications and
113f0 20 73 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65   so this routine
11400 20 69 73 20 75 73 75 61 6c 6c 79 20 6e 6f 74 20   is usually not 
11410 6e 65 63 65 73 73 61 72 79 2e 20 20 49 74 20 69  necessary.  It i
11420 73 0a 2a 2a 20 70 72 6f 76 69 64 65 64 20 74 6f  s.** provided to
11430 20 73 75 70 70 6f 72 74 20 72 61 72 65 20 61 70   support rare ap
11440 70 6c 69 63 61 74 69 6f 6e 73 20 77 69 74 68 20  plications with 
11450 75 6e 75 73 75 61 6c 20 6e 65 65 64 73 2e 0a 2a  unusual needs..*
11460 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
11470 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66  _config() interf
11480 61 63 65 20 69 73 20 6e 6f 74 20 74 68 72 65 61  ace is not threa
11490 64 73 61 66 65 2e 20 20 54 68 65 20 61 70 70 6c  dsafe.  The appl
114a0 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20  ication.** must 
114b0 69 6e 73 75 72 65 20 74 68 61 74 20 6e 6f 20 6f  insure that no o
114c0 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65  ther SQLite inte
114d0 72 66 61 63 65 73 20 61 72 65 20 69 6e 76 6f 6b  rfaces are invok
114e0 65 64 20 62 79 20 6f 74 68 65 72 0a 2a 2a 20 74  ed by other.** t
114f0 68 72 65 61 64 73 20 77 68 69 6c 65 20 73 71 6c  hreads while sql
11500 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73  ite3_config() is
11510 20 72 75 6e 6e 69 6e 67 2e 20 20 46 75 72 74 68   running.  Furth
11520 65 72 6d 6f 72 65 2c 20 73 71 6c 69 74 65 33 5f  ermore, sqlite3_
11530 63 6f 6e 66 69 67 28 29 0a 2a 2a 20 6d 61 79 20  config().** may 
11540 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64 20  only be invoked 
11550 70 72 69 6f 72 20 74 6f 20 6c 69 62 72 61 72 79  prior to library
11560 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
11570 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
11580 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20  3_initialize()] 
11590 6f 72 20 61 66 74 65 72 20 73 68 75 74 64 6f 77  or after shutdow
115a0 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 68  n by [sqlite3_sh
115b0 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49  utdown()]..** ^I
115c0 66 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  f sqlite3_config
115d0 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 66 74  () is called aft
115e0 65 72 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74  er [sqlite3_init
115f0 69 61 6c 69 7a 65 28 29 5d 20 61 6e 64 20 62 65  ialize()] and be
11600 66 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  fore.** [sqlite3
11610 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 74 68 65  _shutdown()] the
11620 6e 20 69 74 20 77 69 6c 6c 20 72 65 74 75 72 6e  n it will return
11630 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a   SQLITE_MISUSE..
11640 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72  ** Note, however
11650 2c 20 74 68 61 74 20 5e 73 71 6c 69 74 65 33 5f  , that ^sqlite3_
11660 63 6f 6e 66 69 67 28 29 20 63 61 6e 20 62 65 20  config() can be 
11670 63 61 6c 6c 65 64 20 61 73 20 70 61 72 74 20 6f  called as part o
11680 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65  f the.** impleme
11690 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70  ntation of an ap
116a0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
116b0 64 20 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  d [sqlite3_os_in
116c0 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  it()]..**.** The
116d0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
116e0 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  to sqlite3_confi
116f0 67 28 29 20 69 73 20 61 6e 20 69 6e 74 65 67 65  g() is an intege
11700 72 0a 2a 2a 20 5b 63 6f 6e 66 69 67 75 72 61 74  r.** [configurat
11710 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74 68 61 74  ion option] that
11720 20 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 77   determines.** w
11730 68 61 74 20 70 72 6f 70 65 72 74 79 20 6f 66 20  hat property of 
11740 53 51 4c 69 74 65 20 69 73 20 74 6f 20 62 65 20  SQLite is to be 
11750 63 6f 6e 66 69 67 75 72 65 64 2e 20 20 53 75 62  configured.  Sub
11760 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74  sequent argument
11770 73 0a 2a 2a 20 76 61 72 79 20 64 65 70 65 6e 64  s.** vary depend
11780 69 6e 67 20 6f 6e 20 74 68 65 20 5b 63 6f 6e 66  ing on the [conf
11790 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
117a0 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73  ].** in the firs
117b0 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  t argument..**.*
117c0 2a 20 5e 57 68 65 6e 20 61 20 63 6f 6e 66 69 67  * ^When a config
117d0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69  uration option i
117e0 73 20 73 65 74 2c 20 73 71 6c 69 74 65 33 5f 63  s set, sqlite3_c
117f0 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e 73 20  onfig() returns 
11800 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20  [SQLITE_OK]..** 
11810 5e 49 66 20 74 68 65 20 6f 70 74 69 6f 6e 20 69  ^If the option i
11820 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c  s unknown or SQL
11830 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f  ite is unable to
11840 20 73 65 74 20 74 68 65 20 6f 70 74 69 6f 6e 0a   set the option.
11850 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75  ** then this rou
11860 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 6e  tine returns a n
11870 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63  on-zero [error c
11880 6f 64 65 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  ode]..*/.SQLITE_
11890 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
118a0 63 6f 6e 66 69 67 28 69 6e 74 2c 20 2e 2e 2e 29  config(int, ...)
118b0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
118c0 46 3a 20 43 6f 6e 66 69 67 75 72 65 20 64 61 74  F: Configure dat
118d0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
118e0 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  s.**.** The sqli
118f0 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20  te3_db_config() 
11900 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65  interface is use
11910 64 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 69 67  d to make config
11920 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67  uration.** chang
11930 65 73 20 74 6f 20 61 20 5b 64 61 74 61 62 61 73  es to a [databas
11940 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20  e connection].  
11950 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 69 73  The interface is
11960 20 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b   similar to.** [
11970 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
11980 5d 20 65 78 63 65 70 74 20 74 68 61 74 20 74 68  ] except that th
11990 65 20 63 68 61 6e 67 65 73 20 61 70 70 6c 79 20  e changes apply 
119a0 74 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b  to a single.** [
119b0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
119c0 69 6f 6e 5d 20 28 73 70 65 63 69 66 69 65 64 20  ion] (specified 
119d0 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67  in the first arg
119e0 75 6d 65 6e 74 29 2e 0a 2a 2a 0a 2a 2a 20 54 68  ument)..**.** Th
119f0 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
11a00 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f  t to sqlite3_db_
11a10 63 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e 29 20  config(D,V,...) 
11a20 20 69 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49   is the.** [SQLI
11a30 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
11a40 41 53 49 44 45 20 7c 20 63 6f 6e 66 69 67 75 72  ASIDE | configur
11a50 61 74 69 6f 6e 20 76 65 72 62 5d 20 2d 20 61 6e  ation verb] - an
11a60 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 0a 2a   integer code .*
11a70 2a 20 74 68 61 74 20 69 6e 64 69 63 61 74 65 73  * that indicates
11a80 20 77 68 61 74 20 61 73 70 65 63 74 20 6f 66 20   what aspect of 
11a90 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
11aa0 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 69  nnection] is bei
11ab0 6e 67 20 63 6f 6e 66 69 67 75 72 65 64 2e 0a 2a  ng configured..*
11ac0 2a 20 53 75 62 73 65 71 75 65 6e 74 20 61 72 67  * Subsequent arg
11ad0 75 6d 65 6e 74 73 20 76 61 72 79 20 64 65 70 65  uments vary depe
11ae0 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f 6e  nding on the con
11af0 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62 2e  figuration verb.
11b00 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f  .**.** ^Calls to
11b10 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66   sqlite3_db_conf
11b20 69 67 28 29 20 72 65 74 75 72 6e 20 53 51 4c 49  ig() return SQLI
11b30 54 45 5f 4f 4b 20 69 66 20 61 6e 64 20 6f 6e 6c  TE_OK if and onl
11b40 79 20 69 66 0a 2a 2a 20 74 68 65 20 63 61 6c 6c  y if.** the call
11b50 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 73   is considered s
11b60 75 63 63 65 73 73 66 75 6c 2e 0a 2a 2f 0a 53 51  uccessful..*/.SQ
11b70 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
11b80 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 73  ite3_db_config(s
11b90 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c  qlite3*, int op,
11ba0 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   ...);../*.** CA
11bb0 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41  PI3REF: Memory A
11bc0 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e  llocation Routin
11bd0 65 73 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74  es.**.** An inst
11be0 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
11bf0 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20  ect defines the 
11c00 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65  interface betwee
11c10 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20  n SQLite.** and 
11c20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79  low-level memory
11c30 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74   allocation rout
11c40 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  ines..**.** This
11c50 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 20   object is used 
11c60 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63  in only one plac
11c70 65 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20  e in the SQLite 
11c80 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20  interface..** A 
11c90 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
11ca0 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f  stance of this o
11cb0 62 6a 65 63 74 20 69 73 20 74 68 65 20 61 72 67  bject is the arg
11cc0 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c  ument to.** [sql
11cd0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
11ce0 68 65 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72  hen the configur
11cf0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a  ation option is.
11d00 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ** [SQLITE_CONFI
11d10 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51  G_MALLOC] or [SQ
11d20 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
11d30 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79 20  ALLOC].  .** By 
11d40 63 72 65 61 74 69 6e 67 20 61 6e 20 69 6e 73 74  creating an inst
11d50 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
11d60 65 63 74 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69  ect.** and passi
11d70 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65  ng it to [sqlite
11d80 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54  3_config]([SQLIT
11d90 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d  E_CONFIG_MALLOC]
11da0 29 0a 2a 2a 20 64 75 72 69 6e 67 20 63 6f 6e 66  ).** during conf
11db0 69 67 75 72 61 74 69 6f 6e 2c 20 61 6e 20 61 70  iguration, an ap
11dc0 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 73 70  plication can sp
11dd0 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61  ecify an alterna
11de0 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  tive.** memory a
11df0 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73  llocation subsys
11e00 74 65 6d 20 66 6f 72 20 53 51 4c 69 74 65 20 74  tem for SQLite t
11e10 6f 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66  o use for all of
11e20 20 69 74 73 0a 2a 2a 20 64 79 6e 61 6d 69 63 20   its.** dynamic 
11e30 6d 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a  memory needs..**
11e40 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51  .** Note that SQ
11e50 4c 69 74 65 20 63 6f 6d 65 73 20 77 69 74 68 20  Lite comes with 
11e60 73 65 76 65 72 61 6c 20 5b 62 75 69 6c 74 2d 69  several [built-i
11e70 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  n memory allocat
11e80 6f 72 73 5d 0a 2a 2a 20 74 68 61 74 20 61 72 65  ors].** that are
11e90 20 70 65 72 66 65 63 74 6c 79 20 61 64 65 71 75   perfectly adequ
11ea0 61 74 65 20 66 6f 72 20 74 68 65 20 6f 76 65 72  ate for the over
11eb0 77 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74  whelming majorit
11ec0 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e  y of application
11ed0 73 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 74 68  s.** and that th
11ee0 69 73 20 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c  is object is onl
11ef0 79 20 75 73 65 66 75 6c 20 74 6f 20 61 20 74 69  y useful to a ti
11f00 6e 79 20 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61  ny minority of a
11f10 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77  pplications.** w
11f20 69 74 68 20 73 70 65 63 69 61 6c 69 7a 65 64 20  ith specialized 
11f30 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
11f40 6e 20 72 65 71 75 69 72 65 6d 65 6e 74 73 2e 20  n requirements. 
11f50 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 0a   This object is.
11f60 2a 2a 20 61 6c 73 6f 20 75 73 65 64 20 64 75 72  ** also used dur
11f70 69 6e 67 20 74 65 73 74 69 6e 67 20 6f 66 20 53  ing testing of S
11f80 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74  QLite in order t
11f90 6f 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74  o specify an alt
11fa0 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f  ernative.** memo
11fb0 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61  ry allocator tha
11fc0 74 20 73 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f  t simulates memo
11fd0 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79  ry out-of-memory
11fe0 20 63 6f 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a   conditions in.*
11ff0 2a 20 6f 72 64 65 72 20 74 6f 20 76 65 72 69 66  * order to verif
12000 79 20 74 68 61 74 20 53 51 4c 69 74 65 20 72 65  y that SQLite re
12010 63 6f 76 65 72 73 20 67 72 61 63 65 66 75 6c 6c  covers gracefull
12020 79 20 66 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63  y from such.** c
12030 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  onditions..**.**
12040 20 54 68 65 20 78 4d 61 6c 6c 6f 63 20 61 6e 64   The xMalloc and
12050 20 78 46 72 65 65 20 6d 65 74 68 6f 64 73 20 6d   xFree methods m
12060 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20 74 68  ust work like th
12070 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29 20 61 6e  e.** malloc() an
12080 64 20 66 72 65 65 28 29 20 66 75 6e 63 74 69 6f  d free() functio
12090 6e 73 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e  ns from the stan
120a0 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a  dard C library..
120b0 2a 2a 20 54 68 65 20 78 52 65 61 6c 6c 6f 63 20  ** The xRealloc 
120c0 6d 65 74 68 6f 64 20 6d 75 73 74 20 77 6f 72 6b  method must work
120d0 20 6c 69 6b 65 20 72 65 61 6c 6c 6f 63 28 29 20   like realloc() 
120e0 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72  from the standar
120f0 64 20 43 20 6c 69 62 72 61 72 79 0a 2a 2a 20 77  d C library.** w
12100 69 74 68 20 74 68 65 20 65 78 63 65 70 74 69 6f  ith the exceptio
12110 6e 20 74 68 61 74 20 69 66 20 74 68 65 20 73 65  n that if the se
12120 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
12130 20 78 52 65 61 6c 6c 6f 63 20 69 73 20 7a 65 72   xRealloc is zer
12140 6f 2c 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 6d  o,.** xRealloc m
12150 75 73 74 20 62 65 20 61 20 6e 6f 2d 6f 70 20 2d  ust be a no-op -
12160 20 69 74 20 6d 75 73 74 20 6e 6f 74 20 70 65 72   it must not per
12170 66 6f 72 6d 20 61 6e 79 20 61 6c 6c 6f 63 61 74  form any allocat
12180 69 6f 6e 20 6f 72 0a 2a 2a 20 64 65 61 6c 6c 6f  ion or.** deallo
12190 63 61 74 69 6f 6e 2e 20 20 5e 53 51 4c 69 74 65  cation.  ^SQLite
121a0 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74   guarantees that
121b0 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
121c0 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78 52 65 61 6c  ment to.** xReal
121d0 6c 6f 63 20 69 73 20 61 6c 77 61 79 73 20 61 20  loc is always a 
121e0 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
121f0 79 20 61 20 70 72 69 6f 72 20 63 61 6c 6c 20 74  y a prior call t
12200 6f 20 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a 20 41  o xRoundup..** A
12210 6e 64 20 73 6f 20 69 6e 20 63 61 73 65 73 20 77  nd so in cases w
12220 68 65 72 65 20 78 52 6f 75 6e 64 75 70 20 61 6c  here xRoundup al
12230 77 61 79 73 20 72 65 74 75 72 6e 73 20 61 20 70  ways returns a p
12240 6f 73 69 74 69 76 65 20 6e 75 6d 62 65 72 2c 0a  ositive number,.
12250 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 63 61 6e 20  ** xRealloc can 
12260 70 65 72 66 6f 72 6d 20 65 78 61 63 74 6c 79 20  perform exactly 
12270 61 73 20 74 68 65 20 73 74 61 6e 64 61 72 64 20  as the standard 
12280 6c 69 62 72 61 72 79 20 72 65 61 6c 6c 6f 63 28  library realloc(
12290 29 20 61 6e 64 0a 2a 2a 20 73 74 69 6c 6c 20 62  ) and.** still b
122a0 65 20 69 6e 20 63 6f 6d 70 6c 69 61 6e 63 65 20  e in compliance 
122b0 77 69 74 68 20 74 68 69 73 20 73 70 65 63 69 66  with this specif
122c0 69 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 78  ication..**.** x
122d0 53 69 7a 65 20 73 68 6f 75 6c 64 20 72 65 74 75  Size should retu
122e0 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64  rn the allocated
122f0 20 73 69 7a 65 20 6f 66 20 61 20 6d 65 6d 6f 72   size of a memor
12300 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  y allocation.** 
12310 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69  previously obtai
12320 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63  ned from xMalloc
12330 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e 20 20 54   or xRealloc.  T
12340 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a  he allocated siz
12350 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61  e.** is always a
12360 74 20 6c 65 61 73 74 20 61 73 20 62 69 67 20 61  t least as big a
12370 73 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20  s the requested 
12380 73 69 7a 65 20 62 75 74 20 6d 61 79 20 62 65 20  size but may be 
12390 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  larger..**.** Th
123a0 65 20 78 52 6f 75 6e 64 75 70 20 6d 65 74 68 6f  e xRoundup metho
123b0 64 20 72 65 74 75 72 6e 73 20 77 68 61 74 20 77  d returns what w
123c0 6f 75 6c 64 20 62 65 20 74 68 65 20 61 6c 6c 6f  ould be the allo
123d0 63 61 74 65 64 20 73 69 7a 65 20 6f 66 0a 2a 2a  cated size of.**
123e0 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
123f0 74 69 6f 6e 20 67 69 76 65 6e 20 61 20 70 61 72  tion given a par
12400 74 69 63 75 6c 61 72 20 72 65 71 75 65 73 74 65  ticular requeste
12410 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74 20 6d 65  d size.  Most me
12420 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f  mory.** allocato
12430 72 73 20 72 6f 75 6e 64 20 75 70 20 6d 65 6d 6f  rs round up memo
12440 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61  ry allocations a
12450 74 20 6c 65 61 73 74 20 74 6f 20 74 68 65 20 6e  t least to the n
12460 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20  ext multiple.** 
12470 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f  of 8.  Some allo
12480 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20  cators round up 
12490 74 6f 20 61 20 6c 61 72 67 65 72 20 6d 75 6c 74  to a larger mult
124a0 69 70 6c 65 20 6f 72 20 74 6f 20 61 20 70 6f 77  iple or to a pow
124b0 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 45 76 65 72  er of 2..** Ever
124c0 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  y memory allocat
124d0 69 6f 6e 20 72 65 71 75 65 73 74 20 63 6f 6d 69  ion request comi
124e0 6e 67 20 69 6e 20 74 68 72 6f 75 67 68 20 5b 73  ng in through [s
124f0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
12500 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
12510 72 65 61 6c 6c 6f 63 28 29 5d 20 66 69 72 73 74  realloc()] first
12520 20 63 61 6c 6c 73 20 78 52 6f 75 6e 64 75 70 2e   calls xRoundup.
12530 20 20 49 66 20 78 52 6f 75 6e 64 75 70 20 72 65    If xRoundup re
12540 74 75 72 6e 73 20 30 2c 20 0a 2a 2a 20 74 68 61  turns 0, .** tha
12550 74 20 63 61 75 73 65 73 20 74 68 65 20 63 6f 72  t causes the cor
12560 72 65 73 70 6f 6e 64 69 6e 67 20 6d 65 6d 6f 72  responding memor
12570 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20  y allocation to 
12580 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  fail..**.** The 
12590 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 69 6e 69  xInit method ini
125a0 74 69 61 6c 69 7a 65 73 20 74 68 65 20 6d 65 6d  tializes the mem
125b0 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20 20  ory allocator.  
125c0 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a  (For example,.**
125d0 20 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f 63 61   it might alloca
125e0 74 65 20 61 6e 79 20 72 65 71 75 69 72 65 20 6d  te any require m
125f0 75 74 65 78 65 73 20 6f 72 20 69 6e 69 74 69 61  utexes or initia
12600 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20 64 61  lize internal da
12610 74 61 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 73  ta.** structures
12620 2e 20 20 54 68 65 20 78 53 68 75 74 64 6f 77 6e  .  The xShutdown
12630 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b   method is invok
12640 65 64 20 28 69 6e 64 69 72 65 63 74 6c 79 29 20  ed (indirectly) 
12650 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  by.** [sqlite3_s
12660 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64 20 73  hutdown()] and s
12670 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61 74 65  hould deallocate
12680 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 61   any resources a
12690 63 71 75 69 72 65 64 0a 2a 2a 20 62 79 20 78 49  cquired.** by xI
126a0 6e 69 74 2e 20 20 54 68 65 20 70 41 70 70 44 61  nit.  The pAppDa
126b0 74 61 20 70 6f 69 6e 74 65 72 20 69 73 20 75 73  ta pointer is us
126c0 65 64 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70  ed as the only p
126d0 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 78  arameter to.** x
126e0 49 6e 69 74 20 61 6e 64 20 78 53 68 75 74 64 6f  Init and xShutdo
126f0 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  wn..**.** SQLite
12700 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49   holds the [SQLI
12710 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f  TE_MUTEX_STATIC_
12720 4d 41 53 54 45 52 5d 20 6d 75 74 65 78 20 77 68  MASTER] mutex wh
12730 65 6e 20 69 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a  en it invokes.**
12740 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f   the xInit metho
12750 64 2c 20 73 6f 20 74 68 65 20 78 49 6e 69 74 20  d, so the xInit 
12760 6d 65 74 68 6f 64 20 6e 65 65 64 20 6e 6f 74 20  method need not 
12770 62 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 20  be threadsafe.  
12780 54 68 65 0a 2a 2a 20 78 53 68 75 74 64 6f 77 6e  The.** xShutdown
12790 20 6d 65 74 68 6f 64 20 69 73 20 6f 6e 6c 79 20   method is only 
127a0 63 61 6c 6c 65 64 20 66 72 6f 6d 20 5b 73 71 6c  called from [sql
127b0 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d  ite3_shutdown()]
127c0 20 73 6f 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e   so it does.** n
127d0 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 74 68  ot need to be th
127e0 72 65 61 64 73 61 66 65 20 65 69 74 68 65 72 2e  readsafe either.
127f0 20 20 46 6f 72 20 61 6c 6c 20 6f 74 68 65 72 20    For all other 
12800 6d 65 74 68 6f 64 73 2c 20 53 51 4c 69 74 65 0a  methods, SQLite.
12810 2a 2a 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51  ** holds the [SQ
12820 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49  LITE_MUTEX_STATI
12830 43 5f 4d 45 4d 5d 20 6d 75 74 65 78 20 61 73 20  C_MEM] mutex as 
12840 6c 6f 6e 67 20 61 73 20 74 68 65 0a 2a 2a 20 5b  long as the.** [
12850 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
12860 4d 53 54 41 54 55 53 5d 20 63 6f 6e 66 69 67 75  MSTATUS] configu
12870 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73  ration option is
12880 20 74 75 72 6e 65 64 20 6f 6e 20 28 77 68 69 63   turned on (whic
12890 68 0a 2a 2a 20 69 74 20 69 73 20 62 79 20 64 65  h.** it is by de
128a0 66 61 75 6c 74 29 20 61 6e 64 20 73 6f 20 74 68  fault) and so th
128b0 65 20 6d 65 74 68 6f 64 73 20 61 72 65 20 61 75  e methods are au
128c0 74 6f 6d 61 74 69 63 61 6c 6c 79 20 73 65 72 69  tomatically seri
128d0 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77 65 76  alized..** Howev
128e0 65 72 2c 20 69 66 20 5b 53 51 4c 49 54 45 5f 43  er, if [SQLITE_C
128f0 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d  ONFIG_MEMSTATUS]
12900 20 69 73 20 64 69 73 61 62 6c 65 64 2c 20 74 68   is disabled, th
12910 65 6e 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20  en the other.** 
12920 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 62 65 20  methods must be 
12930 74 68 72 65 61 64 73 61 66 65 20 6f 72 20 65 6c  threadsafe or el
12940 73 65 20 6d 61 6b 65 20 74 68 65 69 72 20 6f 77  se make their ow
12950 6e 20 61 72 72 61 6e 67 65 6d 65 6e 74 73 20 66  n arrangements f
12960 6f 72 0a 2a 2a 20 73 65 72 69 61 6c 69 7a 61 74  or.** serializat
12970 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  ion..**.** SQLit
12980 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76  e will never inv
12990 6f 6b 65 20 78 49 6e 69 74 28 29 20 6d 6f 72 65  oke xInit() more
129a0 20 74 68 61 6e 20 6f 6e 63 65 20 77 69 74 68 6f   than once witho
129b0 75 74 20 61 6e 20 69 6e 74 65 72 76 65 6e 69 6e  ut an intervenin
129c0 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 78 53 68  g.** call to xSh
129d0 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70  utdown()..*/.typ
129e0 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
129f0 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20  te3_mem_methods 
12a00 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
12a10 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69  ods;.struct sqli
12a20 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20  te3_mem_methods 
12a30 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61 6c  {.  void *(*xMal
12a40 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20 20 20 20  loc)(int);      
12a50 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c     /* Memory all
12a60 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e  ocation function
12a70 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46 72   */.  void (*xFr
12a80 65 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20  ee)(void*);     
12a90 20 20 20 20 20 2f 2a 20 46 72 65 65 20 61 20 70       /* Free a p
12aa0 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  rior allocation 
12ab0 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52 65  */.  void *(*xRe
12ac0 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e 74  alloc)(void*,int
12ad0 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20 61 6e  );  /* Resize an
12ae0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20   allocation */. 
12af0 20 69 6e 74 20 28 2a 78 53 69 7a 65 29 28 76 6f   int (*xSize)(vo
12b00 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20  id*);           
12b10 2f 2a 20 52 65 74 75 72 6e 20 74 68 65 20 73 69  /* Return the si
12b20 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61 74  ze of an allocat
12b30 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ion */.  int (*x
12b40 52 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b 20 20  Roundup)(int);  
12b50 20 20 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e 64          /* Round
12b60 20 75 70 20 72 65 71 75 65 73 74 20 73 69 7a 65   up request size
12b70 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73   to allocation s
12b80 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ize */.  int (*x
12b90 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20 20 20  Init)(void*);   
12ba0 20 20 20 20 20 20 20 20 2f 2a 20 49 6e 69 74 69          /* Initi
12bb0 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79  alize the memory
12bc0 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20   allocator */.  
12bd0 76 6f 69 64 20 28 2a 78 53 68 75 74 64 6f 77 6e  void (*xShutdown
12be0 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 2f  )(void*);      /
12bf0 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a 65 20 74  * Deinitialize t
12c00 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
12c10 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70  tor */.  void *p
12c20 41 70 70 44 61 74 61 3b 20 20 20 20 20 20 20 20  AppData;        
12c30 20 20 20 20 20 20 20 20 2f 2a 20 41 72 67 75 6d          /* Argum
12c40 65 6e 74 20 74 6f 20 78 49 6e 69 74 28 29 20 61  ent to xInit() a
12c50 6e 64 20 78 53 68 75 74 64 6f 77 6e 28 29 20 2a  nd xShutdown() *
12c60 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.};../*.** CAPI
12c70 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 61 74  3REF: Configurat
12c80 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 20 4b  ion Options.** K
12c90 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6e 66 69 67  EYWORDS: {config
12ca0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 7d 0a  uration option}.
12cb0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
12cc0 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76  tants are the av
12cd0 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20  ailable integer 
12ce0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
12cf0 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61  tions that.** ca
12d00 6e 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74  n be passed as t
12d10 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
12d20 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  t to the [sqlite
12d30 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65  3_config()] inte
12d40 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77  rface..**.** New
12d50 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
12d60 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64  ptions may be ad
12d70 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65  ded in future re
12d80 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65  leases of SQLite
12d90 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f  ..** Existing co
12da0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
12db0 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73  ons might be dis
12dc0 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c  continued.  Appl
12dd0 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75  ications.** shou
12de0 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74  ld check the ret
12df0 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73  urn code from [s
12e00 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
12e10 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68   to make sure th
12e20 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77  at.** the call w
12e30 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b 73 71 6c  orked.  The [sql
12e40 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69  ite3_config()] i
12e50 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65  nterface will re
12e60 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65  turn a.** non-ze
12e70 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  ro [error code] 
12e80 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65  if a discontinue
12e90 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64  d or unsupported
12ea0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
12eb0 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f  ption.** is invo
12ec0 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a  ked..**.** <dl>.
12ed0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
12ee0 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d  IG_SINGLETHREAD]
12ef0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
12f00 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
12f10 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
12f20 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65  re are no argume
12f30 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69  nts to this opti
12f40 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f  on.  ^This optio
12f50 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74  n sets the.** [t
12f60 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74  hreading mode] t
12f70 6f 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 2e  o Single-thread.
12f80 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73    In other words
12f90 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a  , it disables.**
12fa0 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e   all mutexing an
12fb0 64 20 70 75 74 73 20 53 51 4c 69 74 65 20 69 6e  d puts SQLite in
12fc0 74 6f 20 61 20 6d 6f 64 65 20 77 68 65 72 65 20  to a mode where 
12fd0 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75  it can only be u
12fe0 73 65 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67  sed.** by a sing
12ff0 6c 65 20 74 68 72 65 61 64 2e 20 20 20 5e 49 66  le thread.   ^If
13000 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
13010 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
13020 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
13030 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45  FE | SQLITE_THRE
13040 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c  ADSAFE=0] compil
13050 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68  e-time option th
13060 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20  en.** it is not 
13070 70 6f 73 73 69 62 6c 65 20 74 6f 20 63 68 61 6e  possible to chan
13080 67 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e  ge the [threadin
13090 67 20 6d 6f 64 65 5d 20 66 72 6f 6d 20 69 74 73  g mode] from its
130a0 20 64 65 66 61 75 6c 74 0a 2a 2a 20 76 61 6c 75   default.** valu
130b0 65 20 6f 66 20 53 69 6e 67 6c 65 2d 74 68 72 65  e of Single-thre
130c0 61 64 20 61 6e 64 20 73 6f 20 5b 73 71 6c 69 74  ad and so [sqlit
130d0 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c  e3_config()] wil
130e0 6c 20 72 65 74 75 72 6e 20 0a 2a 2a 20 5b 53 51  l return .** [SQ
130f0 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63  LITE_ERROR] if c
13100 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 53  alled with the S
13110 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
13120 47 4c 45 54 48 52 45 41 44 0a 2a 2a 20 63 6f 6e  GLETHREAD.** con
13130 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
13140 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  n.</dd>.**.** [[
13150 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
13160 4c 54 49 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e  LTITHREAD]] <dt>
13170 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
13180 4c 54 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a  LTITHREAD</dt>.*
13190 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20  * <dd>There are 
131a0 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  no arguments to 
131b0 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54  this option.  ^T
131c0 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20  his option sets 
131d0 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e  the.** [threadin
131e0 67 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c 74 69  g mode] to Multi
131f0 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68  -thread.  In oth
13200 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73  er words, it dis
13210 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e  ables.** mutexin
13220 67 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63  g on [database c
13230 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b  onnection] and [
13240 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
13250 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20  nt] objects..** 
13260 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
13270 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66  is responsible f
13280 6f 72 20 73 65 72 69 61 6c 69 7a 69 6e 67 20 61  or serializing a
13290 63 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74  ccess to.** [dat
132a0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
132b0 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64  s] and [prepared
132c0 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42   statements].  B
132d0 75 74 20 6f 74 68 65 72 20 6d 75 74 65 78 65 73  ut other mutexes
132e0 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20  .** are enabled 
132f0 73 6f 20 74 68 61 74 20 53 51 4c 69 74 65 20 77  so that SQLite w
13300 69 6c 6c 20 62 65 20 73 61 66 65 20 74 6f 20 75  ill be safe to u
13310 73 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68  se in a multi-th
13320 72 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f  readed.** enviro
13330 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73  nment as long as
13340 20 6e 6f 20 74 77 6f 20 74 68 72 65 61 64 73 20   no two threads 
13350 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74  attempt to use t
13360 68 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 61  he same.** [data
13370 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
13380 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d   at the same tim
13390 65 2e 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69  e.  ^If SQLite i
133a0 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
133b0 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** the [SQLITE_T
133c0 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49  HREADSAFE | SQLI
133d0 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
133e0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
133f0 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20  tion then.** it 
13400 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20  is not possible 
13410 74 6f 20 73 65 74 20 74 68 65 20 4d 75 6c 74 69  to set the Multi
13420 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69  -thread [threadi
13430 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20  ng mode] and.** 
13440 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
13450 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b  )] will return [
13460 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66  SQLITE_ERROR] if
13470 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65   called with the
13480 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  .** SQLITE_CONFI
13490 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 63 6f  G_MULTITHREAD co
134a0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
134b0 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  on.</dd>.**.** [
134c0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
134d0 45 52 49 41 4c 49 5a 45 44 5d 5d 20 3c 64 74 3e  ERIALIZED]] <dt>
134e0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45  SQLITE_CONFIG_SE
134f0 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a  RIALIZED</dt>.**
13500 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e   <dd>There are n
13510 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  o arguments to t
13520 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68  his option.  ^Th
13530 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74  is option sets t
13540 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67  he.** [threading
13550 20 6d 6f 64 65 5d 20 74 6f 20 53 65 72 69 61 6c   mode] to Serial
13560 69 7a 65 64 2e 20 49 6e 20 6f 74 68 65 72 20 77  ized. In other w
13570 6f 72 64 73 2c 20 74 68 69 73 20 6f 70 74 69 6f  ords, this optio
13580 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c  n enables.** all
13590 20 6d 75 74 65 78 65 73 20 69 6e 63 6c 75 64 69   mutexes includi
135a0 6e 67 20 74 68 65 20 72 65 63 75 72 73 69 76 65  ng the recursive
135b0 0a 2a 2a 20 6d 75 74 65 78 65 73 20 6f 6e 20 5b  .** mutexes on [
135c0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
135d0 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72  ion] and [prepar
135e0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62  ed statement] ob
135f0 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 74 68 69  jects..** In thi
13600 73 20 6d 6f 64 65 20 28 77 68 69 63 68 20 69 73  s mode (which is
13610 20 74 68 65 20 64 65 66 61 75 6c 74 20 77 68 65   the default whe
13620 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  n SQLite is comp
13630 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 5b 53 51  iled with.** [SQ
13640 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
13650 31 5d 29 20 74 68 65 20 53 51 4c 69 74 65 20 6c  1]) the SQLite l
13660 69 62 72 61 72 79 20 77 69 6c 6c 20 69 74 73 65  ibrary will itse
13670 6c 66 20 73 65 72 69 61 6c 69 7a 65 20 61 63 63  lf serialize acc
13680 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 74 61 62  ess.** to [datab
13690 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d  ase connections]
136a0 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73   and [prepared s
136b0 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f 20 74 68  tatements] so th
136c0 61 74 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63  at the.** applic
136d0 61 74 69 6f 6e 20 69 73 20 66 72 65 65 20 74 6f  ation is free to
136e0 20 75 73 65 20 74 68 65 20 73 61 6d 65 20 5b 64   use the same [d
136f0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
13700 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a 20 73 61  on] or the.** sa
13710 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  me [prepared sta
13720 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69 66 66 65  tement] in diffe
13730 72 65 6e 74 20 74 68 72 65 61 64 73 20 61 74 20  rent threads at 
13740 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 0a 2a  the same time..*
13750 2a 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20  * ^If SQLite is 
13760 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
13770 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
13780 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45  EADSAFE | SQLITE
13790 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63  _THREADSAFE=0] c
137a0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
137b0 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73  on then.** it is
137c0 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f   not possible to
137d0 20 73 65 74 20 74 68 65 20 53 65 72 69 61 6c 69   set the Seriali
137e0 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  zed [threading m
137f0 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ode] and.** [sql
13800 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
13810 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  ill return [SQLI
13820 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c  TE_ERROR] if cal
13830 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  led with the.** 
13840 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45  SQLITE_CONFIG_SE
13850 52 49 41 4c 49 5a 45 44 20 63 6f 6e 66 69 67 75  RIALIZED configu
13860 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f  ration option.</
13870 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
13880 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
13890 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
138a0 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e  NFIG_MALLOC</dt>
138b0 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20  .** <dd> ^(This 
138c0 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
138d0 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
138e0 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65  hich is a pointe
138f0 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61  r to an.** insta
13900 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  nce of the [sqli
13910 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d  te3_mem_methods]
13920 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65   structure.  The
13930 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66   argument specif
13940 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69  ies.** alternati
13950 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d  ve low-level mem
13960 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
13970 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73  outines to be us
13980 65 64 20 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  ed in place of.*
13990 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  * the memory all
139a0 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  ocation routines
139b0 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69   built into SQLi
139c0 74 65 2e 29 5e 20 5e 53 51 4c 69 74 65 20 6d 61  te.)^ ^SQLite ma
139d0 6b 65 73 0a 2a 2a 20 69 74 73 20 6f 77 6e 20 70  kes.** its own p
139e0 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74  rivate copy of t
139f0 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  he content of th
13a00 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  e [sqlite3_mem_m
13a10 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
13a20 65 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 65 20  e.** before the 
13a30 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
13a40 29 5d 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e  )] call returns.
13a50 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
13a60 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
13a70 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49  ALLOC]] <dt>SQLI
13a80 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c  TE_CONFIG_GETMAL
13a90 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  LOC</dt>.** <dd>
13aa0 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74   ^(This option t
13ab0 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
13ac0 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
13ad0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
13ae0 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  ** instance of t
13af0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  he [sqlite3_mem_
13b00 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
13b10 72 65 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65  re.  The [sqlite
13b20 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a  3_mem_methods].*
13b30 2a 20 73 74 72 75 63 74 75 72 65 20 69 73 20 66  * structure is f
13b40 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 63  illed with the c
13b50 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64  urrently defined
13b60 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
13b70 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a  on routines.)^.*
13b80 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61  * This option ca
13b90 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65  n be used to ove
13ba0 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c  rload the defaul
13bb0 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  t memory allocat
13bc0 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20  ion.** routines 
13bd0 77 69 74 68 20 61 20 77 72 61 70 70 65 72 20 74  with a wrapper t
13be0 68 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20  hat simulations 
13bf0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
13c00 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20  n failure or.** 
13c10 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73  tracks memory us
13c20 61 67 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65  age, for example
13c30 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  . </dd>.**.** [[
13c40 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
13c50 4d 53 54 41 54 55 53 5d 5d 20 3c 64 74 3e 53 51  MSTATUS]] <dt>SQ
13c60 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53  LITE_CONFIG_MEMS
13c70 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  TATUS</dt>.** <d
13c80 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
13c90 74 61 6b 65 73 20 73 69 6e 67 6c 65 20 61 72 67  takes single arg
13ca0 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e  ument of type in
13cb0 74 2c 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  t, interpreted a
13cc0 73 20 61 20 0a 2a 2a 20 62 6f 6f 6c 65 61 6e 2c  s a .** boolean,
13cd0 20 77 68 69 63 68 20 65 6e 61 62 6c 65 73 20 6f   which enables o
13ce0 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 63  r disables the c
13cf0 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 20 6d 65 6d  ollection of mem
13d00 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 0a  ory allocation .
13d10 2a 2a 20 73 74 61 74 69 73 74 69 63 73 2e 20 5e  ** statistics. ^
13d20 28 57 68 65 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c  (When memory all
13d30 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69  ocation statisti
13d40 63 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 2c  cs are disabled,
13d50 20 74 68 65 20 0a 2a 2a 20 66 6f 6c 6c 6f 77 69   the .** followi
13d60 6e 67 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  ng SQLite interf
13d70 61 63 65 73 20 62 65 63 6f 6d 65 20 6e 6f 6e 2d  aces become non-
13d80 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20  operational:.** 
13d90 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e    <ul>.**   <li>
13da0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
13db0 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c  _used()].**   <l
13dc0 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  i> [sqlite3_memo
13dd0 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 0a  ry_highwater()].
13de0 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74  **   <li> [sqlit
13df0 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d  e3_soft_heap_lim
13e00 69 74 36 34 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69  it64()].**   <li
13e10 3e 20 5b 73 71 6c 69 74 65 33 5f 73 74 61 74 75  > [sqlite3_statu
13e20 73 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 29  s()].**   </ul>)
13e30 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 20 61 6c 6c  ^.** ^Memory all
13e40 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69  ocation statisti
13e50 63 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20 62  cs are enabled b
13e60 79 20 64 65 66 61 75 6c 74 20 75 6e 6c 65 73 73  y default unless
13e70 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63 6f   SQLite is.** co
13e80 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c  mpiled with [SQL
13e90 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d 53  ITE_DEFAULT_MEMS
13ea0 54 41 54 55 53 5d 3d 30 20 69 6e 20 77 68 69 63  TATUS]=0 in whic
13eb0 68 20 63 61 73 65 20 6d 65 6d 6f 72 79 0a 2a 2a  h case memory.**
13ec0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74   allocation stat
13ed0 69 73 74 69 63 73 20 61 72 65 20 64 69 73 61 62  istics are disab
13ee0 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a  led by default..
13ef0 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  ** </dd>.**.** [
13f00 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
13f10 43 52 41 54 43 48 5d 5d 20 3c 64 74 3e 53 51 4c  CRATCH]] <dt>SQL
13f20 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54  ITE_CONFIG_SCRAT
13f30 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  CH</dt>.** <dd> 
13f40 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65  ^This option spe
13f50 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20  cifies a static 
13f60 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68  memory buffer th
13f70 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73  at SQLite can us
13f80 65 20 66 6f 72 0a 2a 2a 20 73 63 72 61 74 63 68  e for.** scratch
13f90 20 6d 65 6d 6f 72 79 2e 20 20 54 68 65 72 65 20   memory.  There 
13fa0 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65  are three argume
13fb0 6e 74 73 3a 20 20 41 20 70 6f 69 6e 74 65 72 20  nts:  A pointer 
13fc0 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61 6c 69  an 8-byte.** ali
13fd0 67 6e 65 64 20 6d 65 6d 6f 72 79 20 62 75 66 66  gned memory buff
13fe0 65 72 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68  er from which th
13ff0 65 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61  e scratch alloca
14000 74 69 6f 6e 73 20 77 69 6c 6c 20 62 65 0a 2a 2a  tions will be.**
14010 20 64 72 61 77 6e 2c 20 74 68 65 20 73 69 7a 65   drawn, the size
14020 20 6f 66 20 65 61 63 68 20 73 63 72 61 74 63 68   of each scratch
14030 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 28 73 7a 29   allocation (sz)
14040 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6d 61 78  ,.** and the max
14050 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 73  imum number of s
14060 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f  cratch allocatio
14070 6e 73 20 28 4e 29 2e 20 20 54 68 65 20 73 7a 0a  ns (N).  The sz.
14080 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74  ** argument must
14090 20 62 65 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f   be a multiple o
140a0 66 20 31 36 2e 0a 2a 2a 20 54 68 65 20 66 69 72  f 16..** The fir
140b0 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74  st argument must
140c0 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   be a pointer to
140d0 20 61 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e   an 8-byte align
140e0 65 64 20 62 75 66 66 65 72 0a 2a 2a 20 6f 66 20  ed buffer.** of 
140f0 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79  at least sz*N by
14100 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a  tes of memory..*
14110 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75  * ^SQLite will u
14120 73 65 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 20  se no more than 
14130 74 77 6f 20 73 63 72 61 74 63 68 20 62 75 66 66  two scratch buff
14140 65 72 73 20 70 65 72 20 74 68 72 65 61 64 2e 20  ers per thread. 
14150 20 53 6f 0a 2a 2a 20 4e 20 73 68 6f 75 6c 64 20   So.** N should 
14160 62 65 20 73 65 74 20 74 6f 20 74 77 69 63 65 20  be set to twice 
14170 74 68 65 20 65 78 70 65 63 74 65 64 20 6d 61 78  the expected max
14180 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74  imum number of t
14190 68 72 65 61 64 73 2e 0a 2a 2a 20 5e 53 51 4c 69  hreads..** ^SQLi
141a0 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 72 65  te will never re
141b0 71 75 69 72 65 20 61 20 73 63 72 61 74 63 68 20  quire a scratch 
141c0 62 75 66 66 65 72 20 74 68 61 74 20 69 73 20 6d  buffer that is m
141d0 6f 72 65 20 74 68 61 6e 20 36 0a 2a 2a 20 74 69  ore than 6.** ti
141e0 6d 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65  mes the database
141f0 20 70 61 67 65 20 73 69 7a 65 2e 20 5e 49 66 20   page size. ^If 
14200 53 51 4c 69 74 65 20 6e 65 65 64 73 20 6e 65 65  SQLite needs nee
14210 64 73 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a  ds additional.**
14220 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 20   scratch memory 
14230 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70  beyond what is p
14240 72 6f 76 69 64 65 64 20 62 79 20 74 68 69 73 20  rovided by this 
14250 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
14260 74 69 6f 6e 2c 20 74 68 65 6e 20 0a 2a 2a 20 5b  tion, then .** [
14270 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
14280 5d 20 77 69 6c 6c 20 62 65 20 75 73 65 64 20 74  ] will be used t
14290 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6d 65 6d  o obtain the mem
142a0 6f 72 79 20 6e 65 65 64 65 64 2e 3c 2f 64 64 3e  ory needed.</dd>
142b0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
142c0 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
142d0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
142e0 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 3c 2f  NFIG_PAGECACHE</
142f0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69  dt>.** <dd> ^Thi
14300 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69  s option specifi
14310 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f  es a static memo
14320 72 79 20 62 75 66 66 65 72 20 74 68 61 74 20 53  ry buffer that S
14330 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f  QLite can use fo
14340 72 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  r.** the databas
14350 65 20 70 61 67 65 20 63 61 63 68 65 20 77 69 74  e page cache wit
14360 68 20 74 68 65 20 64 65 66 61 75 6c 74 20 70 61  h the default pa
14370 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65  ge cache impleme
14380 6e 74 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20 54 68  ntation.  .** Th
14390 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  is configuration
143a0 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75   should not be u
143b0 73 65 64 20 69 66 20 61 6e 20 61 70 70 6c 69 63  sed if an applic
143c0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 20 70 61 67  ation-define pag
143d0 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c 65  e.** cache imple
143e0 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6c 6f 61  mentation is loa
143f0 64 65 64 20 75 73 69 6e 67 20 74 68 65 20 53 51  ded using the SQ
14400 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
14410 48 45 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 54 68  HE option..** Th
14420 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72  ere are three ar
14430 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20  guments to this 
14440 6f 70 74 69 6f 6e 3a 20 41 20 70 6f 69 6e 74 65  option: A pointe
14450 72 20 74 6f 20 38 2d 62 79 74 65 20 61 6c 69 67  r to 8-byte alig
14460 6e 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 74  ned.** memory, t
14470 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20  he size of each 
14480 70 61 67 65 20 62 75 66 66 65 72 20 28 73 7a 29  page buffer (sz)
14490 2c 20 61 6e 64 20 74 68 65 20 6e 75 6d 62 65 72  , and the number
144a0 20 6f 66 20 70 61 67 65 73 20 28 4e 29 2e 0a 2a   of pages (N)..*
144b0 2a 20 54 68 65 20 73 7a 20 61 72 67 75 6d 65 6e  * The sz argumen
144c0 74 20 73 68 6f 75 6c 64 20 62 65 20 74 68 65 20  t should be the 
144d0 73 69 7a 65 20 6f 66 20 74 68 65 20 6c 61 72 67  size of the larg
144e0 65 73 74 20 64 61 74 61 62 61 73 65 20 70 61 67  est database pag
144f0 65 0a 2a 2a 20 28 61 20 70 6f 77 65 72 20 6f 66  e.** (a power of
14500 20 74 77 6f 20 62 65 74 77 65 65 6e 20 35 31 32   two between 512
14510 20 61 6e 64 20 33 32 37 36 38 29 20 70 6c 75 73   and 32768) plus
14520 20 61 20 6c 69 74 74 6c 65 20 65 78 74 72 61 20   a little extra 
14530 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70 61 67 65  for each.** page
14540 20 68 65 61 64 65 72 2e 20 20 5e 54 68 65 20 70   header.  ^The p
14550 61 67 65 20 68 65 61 64 65 72 20 73 69 7a 65 20  age header size 
14560 69 73 20 32 30 20 74 6f 20 34 30 20 62 79 74 65  is 20 to 40 byte
14570 73 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 0a 2a  s depending on.*
14580 2a 20 74 68 65 20 68 6f 73 74 20 61 72 63 68 69  * the host archi
14590 74 65 63 74 75 72 65 2e 20 20 5e 49 74 20 69 73  tecture.  ^It is
145a0 20 68 61 72 6d 6c 65 73 73 2c 20 61 70 61 72 74   harmless, apart
145b0 20 66 72 6f 6d 20 74 68 65 20 77 61 73 74 65 64   from the wasted
145c0 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 6f 20 6d   memory,.** to m
145d0 61 6b 65 20 73 7a 20 61 20 6c 69 74 74 6c 65 20  ake sz a little 
145e0 74 6f 6f 20 6c 61 72 67 65 2e 20 20 54 68 65 20  too large.  The 
145f0 66 69 72 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e  first.** argumen
14600 74 20 73 68 6f 75 6c 64 20 70 6f 69 6e 74 20 74  t should point t
14610 6f 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  o an allocation 
14620 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e  of at least sz*N
14630 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79   bytes of memory
14640 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c  ..** ^SQLite wil
14650 6c 20 75 73 65 20 74 68 65 20 6d 65 6d 6f 72 79  l use the memory
14660 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 65   provided by the
14670 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
14680 74 6f 20 73 61 74 69 73 66 79 20 69 74 73 0a 2a  to satisfy its.*
14690 2a 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 20 66  * memory needs f
146a0 6f 72 20 74 68 65 20 66 69 72 73 74 20 4e 20 70  or the first N p
146b0 61 67 65 73 20 74 68 61 74 20 69 74 20 61 64 64  ages that it add
146c0 73 20 74 6f 20 63 61 63 68 65 2e 20 20 5e 49 66  s to cache.  ^If
146d0 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70   additional.** p
146e0 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79  age cache memory
146f0 20 69 73 20 6e 65 65 64 65 64 20 62 65 79 6f 6e   is needed beyon
14700 64 20 77 68 61 74 20 69 73 20 70 72 6f 76 69 64  d what is provid
14710 65 64 20 62 79 20 74 68 69 73 20 6f 70 74 69 6f  ed by this optio
14720 6e 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74  n, then.** SQLit
14730 65 20 67 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74  e goes to [sqlit
14740 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 66 6f 72  e3_malloc()] for
14750 20 74 68 65 20 61 64 64 69 74 69 6f 6e 61 6c 20   the additional 
14760 73 74 6f 72 61 67 65 20 73 70 61 63 65 2e 0a 2a  storage space..*
14770 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 20 69 6e  * The pointer in
14780 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
14790 65 6e 74 20 6d 75 73 74 0a 2a 2a 20 62 65 20 61  ent must.** be a
147a0 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62  ligned to an 8-b
147b0 79 74 65 20 62 6f 75 6e 64 61 72 79 20 6f 72 20  yte boundary or 
147c0 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61 76  subsequent behav
147d0 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a  ior of SQLite.**
147e0 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e   will be undefin
147f0 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  ed.</dd>.**.** [
14800 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48  [SQLITE_CONFIG_H
14810 45 41 50 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  EAP]] <dt>SQLITE
14820 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c 2f 64 74  _CONFIG_HEAP</dt
14830 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20  >.** <dd> ^This 
14840 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73  option specifies
14850 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79   a static memory
14860 20 62 75 66 66 65 72 20 74 68 61 74 20 53 51 4c   buffer that SQL
14870 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20  ite will use.** 
14880 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 64  for all of its d
14890 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 61 6c  ynamic memory al
148a0 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 20 62  location needs b
148b0 65 79 6f 6e 64 20 74 68 6f 73 65 20 70 72 6f 76  eyond those prov
148c0 69 64 65 64 0a 2a 2a 20 66 6f 72 20 62 79 20 5b  ided.** for by [
148d0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43  SQLITE_CONFIG_SC
148e0 52 41 54 43 48 5d 20 61 6e 64 20 5b 53 51 4c 49  RATCH] and [SQLI
148f0 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41  TE_CONFIG_PAGECA
14900 43 48 45 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 61  CHE]..** There a
14910 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e  re three argumen
14920 74 73 3a 20 41 6e 20 38 2d 62 79 74 65 20 61 6c  ts: An 8-byte al
14930 69 67 6e 65 64 20 70 6f 69 6e 74 65 72 20 74 6f  igned pointer to
14940 20 74 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20   the memory,.** 
14950 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
14960 74 65 73 20 69 6e 20 74 68 65 20 6d 65 6d 6f 72  tes in the memor
14970 79 20 62 75 66 66 65 72 2c 20 61 6e 64 20 74 68  y buffer, and th
14980 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61  e minimum alloca
14990 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49  tion size..** ^I
149a0 66 20 74 68 65 20 66 69 72 73 74 20 70 6f 69 6e  f the first poin
149b0 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20  ter (the memory 
149c0 70 6f 69 6e 74 65 72 29 20 69 73 20 4e 55 4c 4c  pointer) is NULL
149d0 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 72 65  , then SQLite re
149e0 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75 73 69 6e  verts.** to usin
149f0 67 20 69 74 73 20 64 65 66 61 75 6c 74 20 6d 65  g its default me
14a00 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 28  mory allocator (
14a10 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f  the system mallo
14a20 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  c() implementati
14a30 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20  on),.** undoing 
14a40 61 6e 79 20 70 72 69 6f 72 20 69 6e 76 6f 63 61  any prior invoca
14a50 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49 54 45 5f  tion of [SQLITE_
14a60 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20  CONFIG_MALLOC]. 
14a70 20 5e 49 66 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f   ^If the.** memo
14a80 72 79 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f  ry pointer is no
14a90 74 20 4e 55 4c 4c 20 61 6e 64 20 65 69 74 68 65  t NULL and eithe
14aa0 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  r [SQLITE_ENABLE
14ab0 5f 4d 45 4d 53 59 53 33 5d 20 6f 72 0a 2a 2a 20  _MEMSYS3] or.** 
14ac0 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d  [SQLITE_ENABLE_M
14ad0 45 4d 53 59 53 35 5d 20 61 72 65 20 64 65 66 69  EMSYS5] are defi
14ae0 6e 65 64 2c 20 74 68 65 6e 20 74 68 65 20 61 6c  ned, then the al
14af0 74 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72 79  ternative memory
14b00 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 20 69 73  .** allocator is
14b10 20 65 6e 67 61 67 65 64 20 74 6f 20 68 61 6e 64   engaged to hand
14b20 6c 65 20 61 6c 6c 20 6f 66 20 53 51 4c 69 74 65  le all of SQLite
14b30 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  s memory allocat
14b40 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a 20 54 68  ion needs..** Th
14b50 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20  e first pointer 
14b60 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e  (the memory poin
14b70 74 65 72 29 20 6d 75 73 74 20 62 65 20 61 6c 69  ter) must be ali
14b80 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74  gned to an 8-byt
14b90 65 0a 2a 2a 20 62 6f 75 6e 64 61 72 79 20 6f 72  e.** boundary or
14ba0 20 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61   subsequent beha
14bb0 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 20 77  vior of SQLite w
14bc0 69 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 64  ill be undefined
14bd0 2e 0a 2a 2a 20 54 68 65 20 6d 69 6e 69 6d 75 6d  ..** The minimum
14be0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65   allocation size
14bf0 20 69 73 20 63 61 70 70 65 64 20 61 74 20 32 5e   is capped at 2^
14c00 31 32 2e 20 52 65 61 73 6f 6e 61 62 6c 65 20 76  12. Reasonable v
14c10 61 6c 75 65 73 0a 2a 2a 20 66 6f 72 20 74 68 65  alues.** for the
14c20 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74   minimum allocat
14c30 69 6f 6e 20 73 69 7a 65 20 61 72 65 20 32 5e 35  ion size are 2^5
14c40 20 74 68 72 6f 75 67 68 20 32 5e 38 2e 3c 2f 64   through 2^8.</d
14c50 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
14c60 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 5d  E_CONFIG_MUTEX]]
14c70 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
14c80 49 47 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a  IG_MUTEX</dt>.**
14c90 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74   <dd> ^(This opt
14ca0 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
14cb0 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
14cc0 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  h is a pointer t
14cd0 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65  o an.** instance
14ce0 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
14cf0 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20  _mutex_methods] 
14d00 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 20  structure.  The 
14d10 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69  argument specifi
14d20 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76  es.** alternativ
14d30 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75 74 65  e low-level mute
14d40 78 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65  x routines to be
14d50 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65 0a 2a   used in place.*
14d60 2a 20 74 68 65 20 6d 75 74 65 78 20 72 6f 75 74  * the mutex rout
14d70 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20  ines built into 
14d80 53 51 4c 69 74 65 2e 29 5e 20 20 5e 53 51 4c 69  SQLite.)^  ^SQLi
14d90 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20  te makes a copy 
14da0 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6e 74 65 6e  of the.** conten
14db0 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  t of the [sqlite
14dc0 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d  3_mutex_methods]
14dd0 20 73 74 72 75 63 74 75 72 65 20 62 65 66 6f 72   structure befor
14de0 65 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a  e the call to.**
14df0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
14e00 28 29 5d 20 72 65 74 75 72 6e 73 2e 20 5e 49 66  ()] returns. ^If
14e10 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
14e20 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
14e30 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
14e40 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45  FE | SQLITE_THRE
14e50 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c  ADSAFE=0] compil
14e60 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68  e-time option th
14e70 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65  en.** the entire
14e80 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79 73   mutexing subsys
14e90 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66  tem is omitted f
14ea0 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e  rom the build an
14eb0 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f  d hence calls to
14ec0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
14ed0 66 69 67 28 29 5d 20 77 69 74 68 20 74 68 65 20  fig()] with the 
14ee0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
14ef0 54 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  TEX configuratio
14f00 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a  n option will.**
14f10 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
14f20 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a  ERROR].</dd>.**.
14f30 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
14f40 49 47 5f 47 45 54 4d 55 54 45 58 5d 5d 20 3c 64  IG_GETMUTEX]] <d
14f50 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
14f60 47 45 54 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a  GETMUTEX</dt>.**
14f70 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74   <dd> ^(This opt
14f80 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
14f90 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
14fa0 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  h is a pointer t
14fb0 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65  o an.** instance
14fc0 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
14fd0 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20  _mutex_methods] 
14fe0 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 0a  structure.  The.
14ff0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  ** [sqlite3_mute
15000 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74  x_methods].** st
15010 72 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65  ructure is fille
15020 64 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65  d with the curre
15030 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 75 74  ntly defined mut
15040 65 78 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a  ex routines.)^.*
15050 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61  * This option ca
15060 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65  n be used to ove
15070 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c  rload the defaul
15080 74 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74 69  t mutex allocati
15090 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77  on.** routines w
150a0 69 74 68 20 61 20 77 72 61 70 70 65 72 20 75 73  ith a wrapper us
150b0 65 64 20 74 6f 20 74 72 61 63 6b 20 6d 75 74 65  ed to track mute
150c0 78 20 75 73 61 67 65 20 66 6f 72 20 70 65 72 66  x usage for perf
150d0 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69  ormance.** profi
150e0 6c 69 6e 67 20 6f 72 20 74 65 73 74 69 6e 67 2c  ling or testing,
150f0 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 20 20   for example.   
15100 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f  ^If SQLite is co
15110 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74  mpiled with.** t
15120 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
15130 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54  DSAFE | SQLITE_T
15140 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d  HREADSAFE=0] com
15150 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
15160 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74   then.** the ent
15170 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62  ire mutexing sub
15180 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65  system is omitte
15190 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64  d from the build
151a0 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73   and hence calls
151b0 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
151c0 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74  config()] with t
151d0 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
151e0 5f 47 45 54 4d 55 54 45 58 20 63 6f 6e 66 69 67  _GETMUTEX config
151f0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77  uration option w
15200 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53  ill.** return [S
15210 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64  QLITE_ERROR].</d
15220 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
15230 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  E_CONFIG_LOOKASI
15240 44 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  DE]] <dt>SQLITE_
15250 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
15260 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
15270 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
15280 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 20  s two arguments 
15290 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74  that determine t
152a0 68 65 20 64 65 66 61 75 6c 74 0a 2a 2a 20 6d 65  he default.** me
152b0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
152c0 66 6f 72 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64  for the lookasid
152d0 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
152e0 6f 72 20 6f 6e 20 65 61 63 68 0a 2a 2a 20 5b 64  or on each.** [d
152f0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
15300 6f 6e 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20  on].  The first 
15310 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a  argument is the.
15320 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20  ** size of each 
15330 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72  lookaside buffer
15340 20 73 6c 6f 74 20 61 6e 64 20 74 68 65 20 73 65   slot and the se
15350 63 6f 6e 64 20 69 73 20 74 68 65 20 6e 75 6d 62  cond is the numb
15360 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20 61  er of.** slots a
15370 6c 6c 6f 63 61 74 65 64 20 74 6f 20 65 61 63 68  llocated to each
15380 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
15390 74 69 6f 6e 2e 29 5e 20 20 5e 28 54 68 69 73 20  tion.)^  ^(This 
153a0 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a  option sets the.
153b0 2a 2a 20 3c 69 3e 64 65 66 61 75 6c 74 3c 2f 69  ** <i>default</i
153c0 3e 20 6c 6f 6f 6b 61 73 69 64 65 20 73 69 7a 65  > lookaside size
153d0 2e 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 44 42  . The [SQLITE_DB
153e0 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
153f0 5d 0a 2a 2a 20 76 65 72 62 20 74 6f 20 5b 73 71  ].** verb to [sq
15400 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
15410 29 5d 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  )] can be used t
15420 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f  o change the loo
15430 6b 61 73 69 64 65 0a 2a 2a 20 63 6f 6e 66 69 67  kaside.** config
15440 75 72 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76  uration on indiv
15450 69 64 75 61 6c 20 63 6f 6e 6e 65 63 74 69 6f 6e  idual connection
15460 73 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  s.)^ </dd>.**.**
15470 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
15480 5f 50 43 41 43 48 45 5d 5d 20 3c 64 74 3e 53 51  _PCACHE]] <dt>SQ
15490 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
154a0 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  HE</dt>.** <dd> 
154b0 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61  ^(This option ta
154c0 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
154d0 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
154e0 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 61   pointer to.** a
154f0 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68  n [sqlite3_pcach
15500 65 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  e_methods] objec
15510 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20  t.  This object 
15520 73 70 65 63 69 66 69 65 73 20 74 68 65 20 69 6e  specifies the in
15530 74 65 72 66 61 63 65 0a 2a 2a 20 74 6f 20 61 20  terface.** to a 
15540 63 75 73 74 6f 6d 20 70 61 67 65 20 63 61 63 68  custom page cach
15550 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
15560 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b  .)^  ^SQLite mak
15570 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  es a copy of the
15580 0a 2a 2a 20 6f 62 6a 65 63 74 20 61 6e 64 20 75  .** object and u
15590 73 65 73 20 69 74 20 66 6f 72 20 70 61 67 65 20  ses it for page 
155a0 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  cache memory all
155b0 6f 63 61 74 69 6f 6e 73 2e 3c 2f 64 64 3e 0a 2a  ocations.</dd>.*
155c0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
155d0 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 5d 5d  NFIG_GETPCACHE]]
155e0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
155f0 49 47 5f 47 45 54 50 43 41 43 48 45 3c 2f 64 74  IG_GETPCACHE</dt
15600 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73  >.** <dd> ^(This
15610 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
15620 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
15630 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74  which is a point
15640 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c  er to an.** [sql
15650 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68  ite3_pcache_meth
15660 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 20 20 53 51  ods] object.  SQ
15670 4c 69 74 65 20 63 6f 70 69 65 73 20 6f 66 20 74  Lite copies of t
15680 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 70 61  he current.** pa
15690 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65  ge cache impleme
156a0 6e 74 61 74 69 6f 6e 20 69 6e 74 6f 20 74 68 61  ntation into tha
156b0 74 20 6f 62 6a 65 63 74 2e 29 5e 20 3c 2f 64 64  t object.)^ </dd
156c0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
156d0 5f 43 4f 4e 46 49 47 5f 4c 4f 47 5d 5d 20 3c 64  _CONFIG_LOG]] <d
156e0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
156f0 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  LOG</dt>.** <dd>
15700 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e   ^The SQLITE_CON
15710 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 74  FIG_LOG option t
15720 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e  akes two argumen
15730 74 73 3a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  ts: a pointer to
15740 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77   a.** function w
15750 69 74 68 20 61 20 63 61 6c 6c 20 73 69 67 6e 61  ith a call signa
15760 74 75 72 65 20 6f 66 20 76 6f 69 64 28 2a 29 28  ture of void(*)(
15770 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
15780 63 68 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20  char*), .** and 
15790 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 76 6f 69  a pointer to voi
157a0 64 2e 20 5e 49 66 20 74 68 65 20 66 75 6e 63 74  d. ^If the funct
157b0 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e  ion pointer is n
157c0 6f 74 20 4e 55 4c 4c 2c 20 69 74 20 69 73 0a 2a  ot NULL, it is.*
157d0 2a 20 69 6e 76 6f 6b 65 64 20 62 79 20 5b 73 71  * invoked by [sq
157e0 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 74 6f 20  lite3_log()] to 
157f0 70 72 6f 63 65 73 73 20 65 61 63 68 20 6c 6f 67  process each log
15800 67 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66  ging event.  ^If
15810 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e   the.** function
15820 20 70 6f 69 6e 74 65 72 20 69 73 20 4e 55 4c 4c   pointer is NULL
15830 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c  , the [sqlite3_l
15840 6f 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  og()] interface 
15850 62 65 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e  becomes a no-op.
15860 0a 2a 2a 20 5e 54 68 65 20 76 6f 69 64 20 70 6f  .** ^The void po
15870 69 6e 74 65 72 20 74 68 61 74 20 69 73 20 74 68  inter that is th
15880 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
15890 74 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46  t to SQLITE_CONF
158a0 49 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70 61 73  IG_LOG is.** pas
158b0 73 65 64 20 74 68 72 6f 75 67 68 20 61 73 20 74  sed through as t
158c0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
158d0 65 72 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63  er to the applic
158e0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f  ation-defined lo
158f0 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  gger.** function
15900 20 77 68 65 6e 65 76 65 72 20 74 68 61 74 20 66   whenever that f
15910 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b  unction is invok
15920 65 64 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64  ed.  ^The second
15930 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
15940 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63   the logger func
15950 74 69 6f 6e 20 69 73 20 61 20 63 6f 70 79 20 6f  tion is a copy o
15960 66 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  f the first para
15970 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 6f 72  meter to the cor
15980 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73  responding.** [s
15990 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 63 61  qlite3_log()] ca
159a0 6c 6c 20 61 6e 64 20 69 73 20 69 6e 74 65 6e 64  ll and is intend
159b0 65 64 20 74 6f 20 62 65 20 61 20 5b 72 65 73 75  ed to be a [resu
159c0 6c 74 20 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a  lt code] or an.*
159d0 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  * [extended resu
159e0 6c 74 20 63 6f 64 65 5d 2e 20 20 5e 54 68 65 20  lt code].  ^The 
159f0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
15a00 70 61 73 73 65 64 20 74 6f 20 74 68 65 20 6c 6f  passed to the lo
15a10 67 67 65 72 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d  gger is.** log m
15a20 65 73 73 61 67 65 20 61 66 74 65 72 20 66 6f 72  essage after for
15a30 6d 61 74 74 69 6e 67 20 76 69 61 20 5b 73 71 6c  matting via [sql
15a40 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d  ite3_snprintf()]
15a50 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20  ..** The SQLite 
15a60 6c 6f 67 67 69 6e 67 20 69 6e 74 65 72 66 61 63  logging interfac
15a70 65 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61  e is not reentra
15a80 6e 74 3b 20 74 68 65 20 6c 6f 67 67 65 72 20 66  nt; the logger f
15a90 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c  unction.** suppl
15aa0 69 65 64 20 62 79 20 74 68 65 20 61 70 70 6c 69  ied by the appli
15ab0 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  cation must not 
15ac0 69 6e 76 6f 6b 65 20 61 6e 79 20 53 51 4c 69 74  invoke any SQLit
15ad0 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20  e interface..** 
15ae0 49 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61  In a multi-threa
15af0 64 65 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c  ded application,
15b00 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
15b10 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a  -defined logger.
15b20 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74  ** function must
15b30 20 62 65 20 74 68 72 65 61 64 73 61 66 65 2e 20   be threadsafe. 
15b40 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
15b50 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d  LITE_CONFIG_URI]
15b60 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
15b70 46 49 47 5f 55 52 49 0a 2a 2a 20 3c 64 64 3e 20  FIG_URI.** <dd> 
15b80 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
15b90 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
15ba0 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2e  ent of type int.
15bb0 20 49 66 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68   If non-zero, th
15bc0 65 6e 0a 2a 2a 20 55 52 49 20 68 61 6e 64 6c 69  en.** URI handli
15bd0 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 65  ng is globally e
15be0 6e 61 62 6c 65 64 2e 20 49 66 20 74 68 65 20 70  nabled. If the p
15bf0 61 72 61 6d 65 74 65 72 20 69 73 20 7a 65 72 6f  arameter is zero
15c00 2c 20 74 68 65 6e 20 55 52 49 20 68 61 6e 64 6c  , then URI handl
15c10 69 6e 67 0a 2a 2a 20 69 73 20 67 6c 6f 62 61 6c  ing.** is global
15c20 6c 79 20 64 69 73 61 62 6c 65 64 2e 20 49 66 20  ly disabled. If 
15c30 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20  URI handling is 
15c40 67 6c 6f 62 61 6c 6c 79 20 65 6e 61 62 6c 65 64  globally enabled
15c50 2c 20 61 6c 6c 20 66 69 6c 65 6e 61 6d 65 73 0a  , all filenames.
15c60 2a 2a 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71  ** passed to [sq
15c70 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b  lite3_open()], [
15c80 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
15c90 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
15ca0 6e 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 73 70 65  n16()] or.** spe
15cb0 63 69 66 69 65 64 20 61 73 20 70 61 72 74 20 6f  cified as part o
15cc0 66 20 5b 41 54 54 41 43 48 5d 20 63 6f 6d 6d 61  f [ATTACH] comma
15cd0 6e 64 73 20 61 72 65 20 69 6e 74 65 72 70 72 65  nds are interpre
15ce0 74 65 64 20 61 73 20 55 52 49 73 2c 20 72 65 67  ted as URIs, reg
15cf0 61 72 64 6c 65 73 73 0a 2a 2a 20 6f 66 20 77 68  ardless.** of wh
15d00 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
15d10 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52   [SQLITE_OPEN_UR
15d20 49 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20 77  I] flag is set w
15d30 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
15d40 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  .** connection i
15d50 73 20 6f 70 65 6e 65 64 2e 20 49 66 20 69 74 20  s opened. If it 
15d60 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61  is globally disa
15d70 62 6c 65 64 2c 20 66 69 6c 65 6e 61 6d 65 73 20  bled, filenames 
15d80 61 72 65 0a 2a 2a 20 6f 6e 6c 79 20 69 6e 74 65  are.** only inte
15d90 72 70 72 65 74 65 64 20 61 73 20 55 52 49 73 20  rpreted as URIs 
15da0 69 66 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 50  if the SQLITE_OP
15db0 45 4e 5f 55 52 49 20 66 6c 61 67 20 69 73 20 73  EN_URI flag is s
15dc0 65 74 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 64  et when the.** d
15dd0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
15de0 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 42 79  on is opened. By
15df0 20 64 65 66 61 75 6c 74 2c 20 55 52 49 20 68 61   default, URI ha
15e00 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c  ndling is global
15e10 6c 79 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 20  ly.** disabled. 
15e20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75  The default valu
15e30 65 20 6d 61 79 20 62 65 20 63 68 61 6e 67 65 64  e may be changed
15e40 20 62 79 20 63 6f 6d 70 69 6c 69 6e 67 20 77 69   by compiling wi
15e50 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  th the.** [SQLIT
15e60 45 5f 55 53 45 5f 55 52 49 5d 20 73 79 6d 62 6f  E_USE_URI] symbo
15e70 6c 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 3c 2f  l defined..** </
15e80 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  dl>.*/.#define S
15e90 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
15ea0 47 4c 45 54 48 52 45 41 44 20 20 31 20 20 2f 2a  GLETHREAD  1  /*
15eb0 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20   nil */.#define 
15ec0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
15ed0 4c 54 49 54 48 52 45 41 44 20 20 20 32 20 20 2f  LTITHREAD   2  /
15ee0 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65  * nil */.#define
15ef0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
15f00 45 52 49 41 4c 49 5a 45 44 20 20 20 20 33 20 20  ERIALIZED    3  
15f10 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e  /* nil */.#defin
15f20 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
15f30 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 34 20  MALLOC        4 
15f40 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f   /* sqlite3_mem_
15f50 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66  methods* */.#def
15f60 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
15f70 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20 20  G_GETMALLOC     
15f80 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65  5  /* sqlite3_me
15f90 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64  m_methods* */.#d
15fa0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
15fb0 46 49 47 5f 53 43 52 41 54 43 48 20 20 20 20 20  FIG_SCRATCH     
15fc0 20 20 36 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69    6  /* void*, i
15fd0 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a  nt sz, int N */.
15fe0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
15ff0 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 20  ONFIG_PAGECACHE 
16000 20 20 20 20 37 20 20 2f 2a 20 76 6f 69 64 2a 2c      7  /* void*,
16010 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a   int sz, int N *
16020 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
16030 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 20 20 20  _CONFIG_HEAP    
16040 20 20 20 20 20 20 38 20 20 2f 2a 20 76 6f 69 64        8  /* void
16050 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 69 6e  *, int nByte, in
16060 74 20 6d 69 6e 20 2a 2f 0a 23 64 65 66 69 6e 65  t min */.#define
16070 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
16080 45 4d 53 54 41 54 55 53 20 20 20 20 20 39 20 20  EMSTATUS     9  
16090 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64  /* boolean */.#d
160a0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
160b0 46 49 47 5f 4d 55 54 45 58 20 20 20 20 20 20 20  FIG_MUTEX       
160c0 20 31 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f   10  /* sqlite3_
160d0 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a  mutex_methods* *
160e0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
160f0 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58  _CONFIG_GETMUTEX
16100 20 20 20 20 20 31 31 20 20 2f 2a 20 73 71 6c 69       11  /* sqli
16110 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
16120 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76 69 6f 75  s* */./* previou
16130 73 6c 79 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  sly SQLITE_CONFI
16140 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20 31 32 20  G_CHUNKALLOC 12 
16150 77 68 69 63 68 20 69 73 20 6e 6f 77 20 75 6e 75  which is now unu
16160 73 65 64 2e 20 2a 2f 20 0a 23 64 65 66 69 6e 65  sed. */ .#define
16170 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c   SQLITE_CONFIG_L
16180 4f 4f 4b 41 53 49 44 45 20 20 20 20 31 33 20 20  OOKASIDE    13  
16190 2f 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64  /* int int */.#d
161a0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
161b0 46 49 47 5f 50 43 41 43 48 45 20 20 20 20 20 20  FIG_PCACHE      
161c0 20 31 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f   14  /* sqlite3_
161d0 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 2a 20  pcache_methods* 
161e0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
161f0 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43  E_CONFIG_GETPCAC
16200 48 45 20 20 20 20 31 35 20 20 2f 2a 20 73 71 6c  HE    15  /* sql
16210 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68  ite3_pcache_meth
16220 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ods* */.#define 
16230 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
16240 47 20 20 20 20 20 20 20 20 20 20 31 36 20 20 2f  G          16  /
16250 2a 20 78 46 75 6e 63 2c 20 76 6f 69 64 2a 20 2a  * xFunc, void* *
16260 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
16270 5f 43 4f 4e 46 49 47 5f 55 52 49 20 20 20 20 20  _CONFIG_URI     
16280 20 20 20 20 20 31 37 20 20 2f 2a 20 69 6e 74 20       17  /* int 
16290 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
162a0 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e  EF: Database Con
162b0 6e 65 63 74 69 6f 6e 20 43 6f 6e 66 69 67 75 72  nection Configur
162c0 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a  ation Options.**
162d0 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
162e0 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61 69  nts are the avai
162f0 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f  lable integer co
16300 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
16310 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20  ons that.** can 
16320 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  be passed as the
16330 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
16340 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
16350 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e  _db_config()] in
16360 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e  terface..**.** N
16370 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ew configuration
16380 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20   options may be 
16390 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
163a0 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69  releases of SQLi
163b0 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20  te..** Existing 
163c0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
163d0 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64  tions might be d
163e0 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70  iscontinued.  Ap
163f0 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68  plications.** sh
16400 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72  ould check the r
16410 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20  eturn code from 
16420 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
16430 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75  ig()] to make su
16440 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63  re that.** the c
16450 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 5e 54 68  all worked.  ^Th
16460 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  e [sqlite3_db_co
16470 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63  nfig()] interfac
16480 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a  e will return a.
16490 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72  ** non-zero [err
164a0 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69  or code] if a di
164b0 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e  scontinued or un
164c0 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67  supported config
164d0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a  uration option.*
164e0 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a  * is invoked..**
164f0 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e  .** <dl>.** <dt>
16500 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
16510 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a  LOOKASIDE</dt>.*
16520 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74  * <dd> ^This opt
16530 69 6f 6e 20 74 61 6b 65 73 20 74 68 72 65 65 20  ion takes three 
16540 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d  additional argum
16550 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 6d  ents that determ
16560 69 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f  ine the .** [loo
16570 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c  kaside memory al
16580 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75  locator] configu
16590 72 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 5b  ration for the [
165a0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
165b0 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66 69  ion]..** ^The fi
165c0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 28 74 68  rst argument (th
165d0 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
165e0 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62  r to [sqlite3_db
165f0 5f 63 6f 6e 66 69 67 28 29 5d 20 69 73 20 61 0a  _config()] is a.
16600 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20  ** pointer to a 
16610 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 6f  memory buffer to
16620 20 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69   use for lookasi
16630 64 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54  de memory..** ^T
16640 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
16650 74 20 61 66 74 65 72 20 74 68 65 20 53 51 4c 49  t after the SQLI
16660 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
16670 41 53 49 44 45 20 76 65 72 62 0a 2a 2a 20 6d 61  ASIDE verb.** ma
16680 79 20 62 65 20 4e 55 4c 4c 20 69 6e 20 77 68 69  y be NULL in whi
16690 63 68 20 63 61 73 65 20 53 51 4c 69 74 65 20 77  ch case SQLite w
166a0 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 74 68 65  ill allocate the
166b0 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75  .** lookaside bu
166c0 66 66 65 72 20 69 74 73 65 6c 66 20 75 73 69 6e  ffer itself usin
166d0 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  g [sqlite3_mallo
166e0 63 28 29 5d 2e 20 5e 54 68 65 20 73 65 63 6f 6e  c()]. ^The secon
166f0 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
16700 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63  e.** size of eac
16710 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66  h lookaside buff
16720 65 72 20 73 6c 6f 74 2e 20 20 5e 54 68 65 20 74  er slot.  ^The t
16730 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73  hird argument is
16740 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
16750 2a 20 73 6c 6f 74 73 2e 20 20 54 68 65 20 73 69  * slots.  The si
16760 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 65 72  ze of the buffer
16770 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
16780 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 67  gument must be g
16790 72 65 61 74 65 72 20 74 68 61 6e 0a 2a 2a 20 6f  reater than.** o
167a0 72 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20 70  r equal to the p
167b0 72 6f 64 75 63 74 20 6f 66 20 74 68 65 20 73 65  roduct of the se
167c0 63 6f 6e 64 20 61 6e 64 20 74 68 69 72 64 20 61  cond and third a
167d0 72 67 75 6d 65 6e 74 73 2e 20 20 54 68 65 20 62  rguments.  The b
167e0 75 66 66 65 72 0a 2a 2a 20 6d 75 73 74 20 62 65  uffer.** must be
167f0 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38   aligned to an 8
16800 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2e 20  -byte boundary. 
16810 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20   ^If the second 
16820 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53  argument to.** S
16830 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c  QLITE_DBCONFIG_L
16840 4f 4f 4b 41 53 49 44 45 20 69 73 20 6e 6f 74 20  OOKASIDE is not 
16850 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2c  a multiple of 8,
16860 20 69 74 20 69 73 20 69 6e 74 65 72 6e 61 6c 6c   it is internall
16870 79 0a 2a 2a 20 72 6f 75 6e 64 65 64 20 64 6f 77  y.** rounded dow
16880 6e 20 74 6f 20 74 68 65 20 6e 65 78 74 20 73 6d  n to the next sm
16890 61 6c 6c 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f  aller multiple o
168a0 66 20 38 2e 20 20 5e 28 54 68 65 20 6c 6f 6f 6b  f 8.  ^(The look
168b0 61 73 69 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20  aside memory.** 
168c0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f  configuration fo
168d0 72 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e  r a database con
168e0 6e 65 63 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79  nection can only
168f0 20 62 65 20 63 68 61 6e 67 65 64 20 77 68 65 6e   be changed when
16900 20 74 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74   that.** connect
16910 69 6f 6e 20 69 73 20 6e 6f 74 20 63 75 72 72 65  ion is not curre
16920 6e 74 6c 79 20 75 73 69 6e 67 20 6c 6f 6f 6b 61  ntly using looka
16930 73 69 64 65 20 6d 65 6d 6f 72 79 2c 20 6f 72 20  side memory, or 
16940 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 0a 2a  in other words.*
16950 2a 20 77 68 65 6e 20 74 68 65 20 22 63 75 72 72  * when the "curr
16960 65 6e 74 20 76 61 6c 75 65 22 20 72 65 74 75 72  ent value" retur
16970 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74  ned by.** [sqlit
16980 65 33 5f 64 62 5f 73 74 61 74 75 73 5d 28 44 2c  e3_db_status](D,
16990 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c  [SQLITE_CONFIG_L
169a0 4f 4f 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29 20 69  OOKASIDE],...) i
169b0 73 20 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61  s zero..** Any a
169c0 74 74 65 6d 70 74 20 74 6f 20 63 68 61 6e 67 65  ttempt to change
169d0 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d   the lookaside m
169e0 65 6d 6f 72 79 20 63 6f 6e 66 69 67 75 72 61 74  emory configurat
169f0 69 6f 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61 73 69  ion when lookasi
16a00 64 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69 73 20  de.** memory is 
16a10 69 6e 20 75 73 65 20 6c 65 61 76 65 73 20 74 68  in use leaves th
16a20 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  e configuration 
16a30 75 6e 63 68 61 6e 67 65 64 20 61 6e 64 20 72 65  unchanged and re
16a40 74 75 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49 54  turns .** [SQLIT
16a50 45 5f 42 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a  E_BUSY].)^</dd>.
16a60 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
16a70 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
16a80 5f 46 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  _FKEY</dt>.** <d
16a90 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
16aa0 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c  is used to enabl
16ab0 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68 65  e or disable the
16ac0 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 66 0a   enforcement of.
16ad0 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20  ** [foreign key 
16ae0 63 6f 6e 73 74 72 61 69 6e 74 73 5d 2e 20 20 54  constraints].  T
16af0 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74  here should be t
16b00 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72  wo additional ar
16b10 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20  guments..** The 
16b20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69  first argument i
16b30 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69  s an integer whi
16b40 63 68 20 69 73 20 30 20 74 6f 20 64 69 73 61 62  ch is 0 to disab
16b50 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e  le FK enforcemen
16b60 74 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74  t,.** positive t
16b70 6f 20 65 6e 61 62 6c 65 20 46 4b 20 65 6e 66 6f  o enable FK enfo
16b80 72 63 65 6d 65 6e 74 20 6f 72 20 6e 65 67 61 74  rcement or negat
16b90 69 76 65 20 74 6f 20 6c 65 61 76 65 20 46 4b 20  ive to leave FK 
16ba0 65 6e 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a 20 75  enforcement.** u
16bb0 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20 73  nchanged.  The s
16bc0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
16bd0 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
16be0 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20  an integer into 
16bf0 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74  which.** is writ
16c00 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e  ten 0 or 1 to in
16c10 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20 46  dicate whether F
16c20 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 69 73  K enforcement is
16c30 20 6f 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f   off or on.** fo
16c40 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c  llowing this cal
16c50 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70  l.  The second p
16c60 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20  arameter may be 
16c70 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  a NULL pointer, 
16c80 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65  in.** which case
16c90 20 74 68 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d   the FK enforcem
16ca0 65 6e 74 20 73 65 74 74 69 6e 67 20 69 73 20 6e  ent setting is n
16cb0 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b  ot reported back
16cc0 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  . </dd>.**.** <d
16cd0 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  t>SQLITE_DBCONFI
16ce0 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52  G_ENABLE_TRIGGER
16cf0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
16d00 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73  his option is us
16d10 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20  ed to enable or 
16d20 64 69 73 61 62 6c 65 20 5b 43 52 45 41 54 45 20  disable [CREATE 
16d30 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 65  TRIGGER | trigge
16d40 72 73 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68  rs]..** There sh
16d50 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69  ould be two addi
16d60 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73  tional arguments
16d70 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  ..** The first a
16d80 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e  rgument is an in
16d90 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20 30  teger which is 0
16da0 20 74 6f 20 64 69 73 61 62 6c 65 20 74 72 69 67   to disable trig
16db0 67 65 72 73 2c 0a 2a 2a 20 70 6f 73 69 74 69 76  gers,.** positiv
16dc0 65 20 74 6f 20 65 6e 61 62 6c 65 20 74 72 69 67  e to enable trig
16dd0 67 65 72 73 20 6f 72 20 6e 65 67 61 74 69 76 65  gers or negative
16de0 20 74 6f 20 6c 65 61 76 65 20 74 68 65 20 73 65   to leave the se
16df0 74 74 69 6e 67 20 75 6e 63 68 61 6e 67 65 64 2e  tting unchanged.
16e00 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70  .** The second p
16e10 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f  arameter is a po
16e20 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65  inter to an inte
16e30 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a  ger into which.*
16e40 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f  * is written 0 o
16e50 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20  r 1 to indicate 
16e60 77 68 65 74 68 65 72 20 74 72 69 67 67 65 72 73  whether triggers
16e70 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 6f 72   are disabled or
16e80 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c   enabled.** foll
16e90 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e  owing this call.
16ea0 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72    The second par
16eb0 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61 20  ameter may be a 
16ec0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e  NULL pointer, in
16ed0 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20 74  .** which case t
16ee0 68 65 20 74 72 69 67 67 65 72 20 73 65 74 74 69  he trigger setti
16ef0 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74  ng is not report
16f00 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a  ed back. </dd>.*
16f10 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64  *.** </dl>.*/.#d
16f20 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43  efine SQLITE_DBC
16f30 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20  ONFIG_LOOKASIDE 
16f40 20 20 20 20 20 20 31 30 30 31 20 20 2f 2a 20 76        1001  /* v
16f50 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a  oid* int int */.
16f60 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
16f70 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46  BCONFIG_ENABLE_F
16f80 4b 45 59 20 20 20 20 20 31 30 30 32 20 20 2f 2a  KEY     1002  /*
16f90 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65   int int* */.#de
16fa0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f  fine SQLITE_DBCO
16fb0 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47  NFIG_ENABLE_TRIG
16fc0 47 45 52 20 20 31 30 30 33 20 20 2f 2a 20 69 6e  GER  1003  /* in
16fd0 74 20 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a 2a  t int* */.../*.*
16fe0 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62  * CAPI3REF: Enab
16ff0 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78  le Or Disable Ex
17000 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f  tended Result Co
17010 64 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  des.**.** ^The s
17020 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
17030 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 20 72  result_codes() r
17040 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f  outine enables o
17050 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 0a 2a  r disables the.*
17060 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  * [extended resu
17070 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 74 75 72  lt codes] featur
17080 65 20 6f 66 20 53 51 4c 69 74 65 2e 20 5e 54 68  e of SQLite. ^Th
17090 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c  e extended resul
170a0 74 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65 20 64  t.** codes are d
170b0 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  isabled by defau
170c0 6c 74 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61  lt for historica
170d0 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  l compatibility.
170e0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
170f0 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  nt sqlite3_exten
17100 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73  ded_result_codes
17110 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f  (sqlite3*, int o
17120 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  noff);../*.** CA
17130 50 49 33 52 45 46 3a 20 4c 61 73 74 20 49 6e 73  PI3REF: Last Ins
17140 65 72 74 20 52 6f 77 69 64 0a 2a 2a 0a 2a 2a 20  ert Rowid.**.** 
17150 5e 45 61 63 68 20 65 6e 74 72 79 20 69 6e 20 61  ^Each entry in a
17160 6e 20 53 51 4c 69 74 65 20 74 61 62 6c 65 20 68  n SQLite table h
17170 61 73 20 61 20 75 6e 69 71 75 65 20 36 34 2d 62  as a unique 64-b
17180 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20 69 6e 74  it signed.** int
17190 65 67 65 72 20 6b 65 79 20 63 61 6c 6c 65 64 20  eger key called 
171a0 74 68 65 20 5b 52 4f 57 49 44 20 7c 20 22 72 6f  the [ROWID | "ro
171b0 77 69 64 22 5d 2e 20 5e 54 68 65 20 72 6f 77 69  wid"]. ^The rowi
171c0 64 20 69 73 20 61 6c 77 61 79 73 20 61 76 61 69  d is always avai
171d0 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61 6e 20 75  lable.** as an u
171e0 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e  ndeclared column
171f0 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c 20 4f 49   named ROWID, OI
17200 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f 20 61 73  D, or _ROWID_ as
17210 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73 65 0a 2a   long as those.*
17220 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e 6f 74 20  * names are not 
17230 61 6c 73 6f 20 75 73 65 64 20 62 79 20 65 78 70  also used by exp
17240 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64  licitly declared
17250 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66 0a 2a 2a   columns. ^If.**
17260 20 74 68 65 20 74 61 62 6c 65 20 68 61 73 20 61   the table has a
17270 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 70 65 20   column of type 
17280 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59  [INTEGER PRIMARY
17290 20 4b 45 59 5d 20 74 68 65 6e 20 74 68 61 74 20   KEY] then that 
172a0 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e 6f  column.** is ano
172b0 74 68 65 72 20 61 6c 69 61 73 20 66 6f 72 20 74  ther alias for t
172c0 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20  he rowid..**.** 
172d0 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65  ^This routine re
172e0 74 75 72 6e 73 20 74 68 65 20 5b 72 6f 77 69 64  turns the [rowid
172f0 5d 20 6f 66 20 74 68 65 20 6d 6f 73 74 20 72 65  ] of the most re
17300 63 65 6e 74 0a 2a 2a 20 73 75 63 63 65 73 73 66  cent.** successf
17310 75 6c 20 5b 49 4e 53 45 52 54 5d 20 69 6e 74 6f  ul [INSERT] into
17320 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 72   the database fr
17330 6f 6d 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  om the [database
17340 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20   connection].** 
17350 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67  in the first arg
17360 75 6d 65 6e 74 2e 20 20 5e 41 73 20 6f 66 20 53  ument.  ^As of S
17370 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
17380 37 2e 37 2c 20 74 68 69 73 20 72 6f 75 74 69 6e  7.7, this routin
17390 65 73 0a 2a 2a 20 72 65 63 6f 72 64 73 20 74 68  es.** records th
173a0 65 20 6c 61 73 74 20 69 6e 73 65 72 74 20 72 6f  e last insert ro
173b0 77 69 64 20 6f 66 20 62 6f 74 68 20 6f 72 64 69  wid of both ordi
173c0 6e 61 72 79 20 74 61 62 6c 65 73 20 61 6e 64 20  nary tables and 
173d0 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 5d  [virtual tables]
173e0 2e 0a 2a 2a 20 5e 49 66 20 6e 6f 20 73 75 63 63  ..** ^If no succ
173f0 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 73  essful [INSERT]s
17400 0a 2a 2a 20 68 61 76 65 20 65 76 65 72 20 6f 63  .** have ever oc
17410 63 75 72 72 65 64 20 6f 6e 20 74 68 61 74 20 64  curred on that d
17420 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
17430 6f 6e 2c 20 7a 65 72 6f 20 69 73 20 72 65 74 75  on, zero is retu
17440 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66  rned..**.** ^(If
17450 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 6f 63 63   an [INSERT] occ
17460 75 72 73 20 77 69 74 68 69 6e 20 61 20 74 72 69  urs within a tri
17470 67 67 65 72 20 6f 72 20 77 69 74 68 69 6e 20 61  gger or within a
17480 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d   [virtual table]
17490 0a 2a 2a 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e  .** method, then
174a0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69   this routine wi
174b0 6c 6c 20 72 65 74 75 72 6e 20 74 68 65 20 5b 72  ll return the [r
174c0 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 69 6e 73  owid] of the ins
174d0 65 72 74 65 64 0a 2a 2a 20 72 6f 77 20 61 73 20  erted.** row as 
174e0 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 72 69 67  long as the trig
174f0 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c 20 74  ger or virtual t
17500 61 62 6c 65 20 6d 65 74 68 6f 64 20 69 73 20 72  able method is r
17510 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74 20 6f  unning..** But o
17520 6e 63 65 20 74 68 65 20 74 72 69 67 67 65 72 20  nce the trigger 
17530 6f 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  or virtual table
17540 20 6d 65 74 68 6f 64 20 65 6e 64 73 2c 20 74 68   method ends, th
17550 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
17560 20 0a 2a 2a 20 62 79 20 74 68 69 73 20 72 6f 75   .** by this rou
17570 74 69 6e 65 20 72 65 76 65 72 74 73 20 74 6f 20  tine reverts to 
17580 77 68 61 74 20 69 74 20 77 61 73 20 62 65 66 6f  what it was befo
17590 72 65 20 74 68 65 20 74 72 69 67 67 65 72 20 6f  re the trigger o
175a0 72 20 76 69 72 74 75 61 6c 0a 2a 2a 20 74 61 62  r virtual.** tab
175b0 6c 65 20 6d 65 74 68 6f 64 20 62 65 67 61 6e 2e  le method began.
175c0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e  )^.**.** ^An [IN
175d0 53 45 52 54 5d 20 74 68 61 74 20 66 61 69 6c 73  SERT] that fails
175e0 20 64 75 65 20 74 6f 20 61 20 63 6f 6e 73 74 72   due to a constr
175f0 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69  aint violation i
17600 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65  s not a.** succe
17610 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 61  ssful [INSERT] a
17620 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e  nd does not chan
17630 67 65 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  ge the value ret
17640 75 72 6e 65 64 20 62 79 20 74 68 69 73 0a 2a 2a  urned by this.**
17650 20 72 6f 75 74 69 6e 65 2e 20 20 5e 54 68 75 73   routine.  ^Thus
17660 20 49 4e 53 45 52 54 20 4f 52 20 46 41 49 4c 2c   INSERT OR FAIL,
17670 20 49 4e 53 45 52 54 20 4f 52 20 49 47 4e 4f 52   INSERT OR IGNOR
17680 45 2c 20 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c  E, INSERT OR ROL
17690 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e  LBACK,.** and IN
176a0 53 45 52 54 20 4f 52 20 41 42 4f 52 54 20 6d 61  SERT OR ABORT ma
176b0 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f  ke no changes to
176c0 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
176d0 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75  e of this.** rou
176e0 74 69 6e 65 20 77 68 65 6e 20 74 68 65 69 72 20  tine when their 
176f0 69 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e  insertion fails.
17700 20 20 5e 28 57 68 65 6e 20 49 4e 53 45 52 54 20    ^(When INSERT 
17710 4f 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e  OR REPLACE.** en
17720 63 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e 73 74  counters a const
17730 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c  raint violation,
17740 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 66 61 69   it does not fai
17750 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52  l.  The.** INSER
17760 54 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63  T continues to c
17770 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65 72 20  ompletion after 
17780 64 65 6c 65 74 69 6e 67 20 72 6f 77 73 20 74 68  deleting rows th
17790 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 74 68 65  at caused.** the
177a0 20 63 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f 62   constraint prob
177b0 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f 52  lem so INSERT OR
177c0 20 52 45 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c   REPLACE will al
177d0 77 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74  ways change.** t
177e0 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
177f0 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  of this interfac
17800 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20  e.)^.**.** ^For 
17810 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20  the purposes of 
17820 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e  this routine, an
17830 20 5b 49 4e 53 45 52 54 5d 20 69 73 20 63 6f 6e   [INSERT] is con
17840 73 69 64 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65  sidered to.** be
17850 20 73 75 63 63 65 73 73 66 75 6c 20 65 76 65 6e   successful even
17860 20 69 66 20 69 74 20 69 73 20 73 75 62 73 65 71   if it is subseq
17870 75 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61  uently rolled ba
17880 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66  ck..**.** This f
17890 75 6e 63 74 69 6f 6e 20 69 73 20 61 63 63 65 73  unction is acces
178a0 73 69 62 6c 65 20 74 6f 20 53 51 4c 20 73 74 61  sible to SQL sta
178b0 74 65 6d 65 6e 74 73 20 76 69 61 20 74 68 65 0a  tements via the.
178c0 2a 2a 20 5b 6c 61 73 74 5f 69 6e 73 65 72 74 5f  ** [last_insert_
178d0 72 6f 77 69 64 28 29 20 53 51 4c 20 66 75 6e 63  rowid() SQL func
178e0 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  tion]..**.** If 
178f0 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61  a separate threa
17900 64 20 70 65 72 66 6f 72 6d 73 20 61 20 6e 65 77  d performs a new
17910 20 5b 49 4e 53 45 52 54 5d 20 6f 6e 20 74 68 65   [INSERT] on the
17920 20 73 61 6d 65 0a 2a 2a 20 64 61 74 61 62 61 73   same.** databas
17930 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69  e connection whi
17940 6c 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  le the [sqlite3_
17950 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
17960 64 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  d()].** function
17970 20 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20   is running and 
17980 74 68 75 73 20 63 68 61 6e 67 65 73 20 74 68 65  thus changes the
17990 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f   last insert [ro
179a0 77 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  wid],.** then th
179b0 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
179c0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73   by [sqlite3_las
179d0 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29  t_insert_rowid()
179e0 5d 20 69 73 0a 2a 2a 20 75 6e 70 72 65 64 69 63  ] is.** unpredic
179f0 74 61 62 6c 65 20 61 6e 64 20 6d 69 67 68 74 20  table and might 
17a00 6e 6f 74 20 65 71 75 61 6c 20 65 69 74 68 65 72  not equal either
17a10 20 74 68 65 20 6f 6c 64 20 6f 72 20 74 68 65 20   the old or the 
17a20 6e 65 77 0a 2a 2a 20 6c 61 73 74 20 69 6e 73 65  new.** last inse
17a30 72 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 53  rt [rowid]..*/.S
17a40 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65  QLITE_API sqlite
17a50 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
17a60 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
17a70 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  d(sqlite3*);../*
17a80 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
17a90 75 6e 74 20 54 68 65 20 4e 75 6d 62 65 72 20 4f  unt The Number O
17aa0 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a  f Rows Modified.
17ab0 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63  **.** ^This func
17ac0 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65  tion returns the
17ad0 20 6e 75 6d 62 65 72 20 6f 66 20 64 61 74 61 62   number of datab
17ae0 61 73 65 20 72 6f 77 73 20 74 68 61 74 20 77 65  ase rows that we
17af0 72 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 6f 72  re changed.** or
17b00 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c   inserted or del
17b10 65 74 65 64 20 62 79 20 74 68 65 20 6d 6f 73 74  eted by the most
17b20 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65   recently comple
17b30 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ted SQL statemen
17b40 74 0a 2a 2a 20 6f 6e 20 74 68 65 20 5b 64 61 74  t.** on the [dat
17b50 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
17b60 5d 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74  ] specified by t
17b70 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
17b80 65 72 2e 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 63 68  er..** ^(Only ch
17b90 61 6e 67 65 73 20 74 68 61 74 20 61 72 65 20 64  anges that are d
17ba0 69 72 65 63 74 6c 79 20 73 70 65 63 69 66 69 65  irectly specifie
17bb0 64 20 62 79 20 74 68 65 20 5b 49 4e 53 45 52 54  d by the [INSERT
17bc0 5d 2c 20 5b 55 50 44 41 54 45 5d 2c 0a 2a 2a 20  ], [UPDATE],.** 
17bd0 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74  or [DELETE] stat
17be0 65 6d 65 6e 74 20 61 72 65 20 63 6f 75 6e 74 65  ement are counte
17bf0 64 2e 20 20 41 75 78 69 6c 69 61 72 79 20 63 68  d.  Auxiliary ch
17c00 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 0a  anges caused by.
17c10 2a 2a 20 74 72 69 67 67 65 72 73 20 6f 72 20 5b  ** triggers or [
17c20 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69  foreign key acti
17c30 6f 6e 73 5d 20 61 72 65 20 6e 6f 74 20 63 6f 75  ons] are not cou
17c40 6e 74 65 64 2e 29 5e 20 55 73 65 20 74 68 65 0a  nted.)^ Use the.
17c50 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61  ** [sqlite3_tota
17c60 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 66 75 6e  l_changes()] fun
17c70 63 74 69 6f 6e 20 74 6f 20 66 69 6e 64 20 74 68  ction to find th
17c80 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f  e total number o
17c90 66 20 63 68 61 6e 67 65 73 0a 2a 2a 20 69 6e 63  f changes.** inc
17ca0 6c 75 64 69 6e 67 20 63 68 61 6e 67 65 73 20 63  luding changes c
17cb0 61 75 73 65 64 20 62 79 20 74 72 69 67 67 65 72  aused by trigger
17cc0 73 20 61 6e 64 20 66 6f 72 65 69 67 6e 20 6b 65  s and foreign ke
17cd0 79 20 61 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  y actions..**.**
17ce0 20 5e 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76   ^Changes to a v
17cf0 69 65 77 20 74 68 61 74 20 61 72 65 20 73 69 6d  iew that are sim
17d00 75 6c 61 74 65 64 20 62 79 20 61 6e 20 5b 49 4e  ulated by an [IN
17d10 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72  STEAD OF trigger
17d20 5d 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 63 6f 75  ].** are not cou
17d30 6e 74 65 64 2e 20 20 4f 6e 6c 79 20 72 65 61 6c  nted.  Only real
17d40 20 74 61 62 6c 65 20 63 68 61 6e 67 65 73 20 61   table changes a
17d50 72 65 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a  re counted..**.*
17d60 2a 20 5e 28 41 20 22 72 6f 77 20 63 68 61 6e 67  * ^(A "row chang
17d70 65 22 20 69 73 20 61 20 63 68 61 6e 67 65 20 74  e" is a change t
17d80 6f 20 61 20 73 69 6e 67 6c 65 20 72 6f 77 20 6f  o a single row o
17d90 66 20 61 20 73 69 6e 67 6c 65 20 74 61 62 6c 65  f a single table
17da0 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20 61 6e  .** caused by an
17db0 20 49 4e 53 45 52 54 2c 20 44 45 4c 45 54 45 2c   INSERT, DELETE,
17dc0 20 6f 72 20 55 50 44 41 54 45 20 73 74 61 74 65   or UPDATE state
17dd0 6d 65 6e 74 2e 20 20 52 6f 77 73 20 74 68 61 74  ment.  Rows that
17de0 0a 2a 2a 20 61 72 65 20 63 68 61 6e 67 65 64 20  .** are changed 
17df0 61 73 20 73 69 64 65 20 65 66 66 65 63 74 73 20  as side effects 
17e00 6f 66 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e  of [REPLACE] con
17e10 73 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69  straint resoluti
17e20 6f 6e 2c 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b 2c  on,.** rollback,
17e30 20 41 42 4f 52 54 20 70 72 6f 63 65 73 73 69 6e   ABORT processin
17e40 67 2c 20 5b 44 52 4f 50 20 54 41 42 4c 45 5d 2c  g, [DROP TABLE],
17e50 20 6f 72 20 62 79 20 61 6e 79 20 6f 74 68 65 72   or by any other
17e60 0a 2a 2a 20 6d 65 63 68 61 6e 69 73 6d 73 20 64  .** mechanisms d
17e70 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 64  o not count as d
17e80 69 72 65 63 74 20 72 6f 77 20 63 68 61 6e 67 65  irect row change
17e90 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 22 74 72  s.)^.**.** A "tr
17ea0 69 67 67 65 72 20 63 6f 6e 74 65 78 74 22 20 69  igger context" i
17eb0 73 20 61 20 73 63 6f 70 65 20 6f 66 20 65 78 65  s a scope of exe
17ec0 63 75 74 69 6f 6e 20 74 68 61 74 20 62 65 67 69  cution that begi
17ed0 6e 73 20 61 6e 64 0a 2a 2a 20 65 6e 64 73 20 77  ns and.** ends w
17ee0 69 74 68 20 74 68 65 20 73 63 72 69 70 74 20 6f  ith the script o
17ef0 66 20 61 20 5b 43 52 45 41 54 45 20 54 52 49 47  f a [CREATE TRIG
17f00 47 45 52 20 7c 20 74 72 69 67 67 65 72 5d 2e 20  GER | trigger]. 
17f10 0a 2a 2a 20 4d 6f 73 74 20 53 51 4c 20 73 74 61  .** Most SQL sta
17f20 74 65 6d 65 6e 74 73 20 61 72 65 0a 2a 2a 20 65  tements are.** e
17f30 76 61 6c 75 61 74 65 64 20 6f 75 74 73 69 64 65  valuated outside
17f40 20 6f 66 20 61 6e 79 20 74 72 69 67 67 65 72 2e   of any trigger.
17f50 20 20 54 68 69 73 20 69 73 20 74 68 65 20 22 74    This is the "t
17f60 6f 70 20 6c 65 76 65 6c 22 0a 2a 2a 20 74 72 69  op level".** tri
17f70 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 20 20 49  gger context.  I
17f80 66 20 61 20 74 72 69 67 67 65 72 20 66 69 72 65  f a trigger fire
17f90 73 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c  s from the top l
17fa0 65 76 65 6c 2c 20 61 0a 2a 2a 20 6e 65 77 20 74  evel, a.** new t
17fb0 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 20 69  rigger context i
17fc0 73 20 65 6e 74 65 72 65 64 20 66 6f 72 20 74 68  s entered for th
17fd0 65 20 64 75 72 61 74 69 6f 6e 20 6f 66 20 74 68  e duration of th
17fe0 61 74 20 6f 6e 65 0a 2a 2a 20 74 72 69 67 67 65  at one.** trigge
17ff0 72 2e 20 20 53 75 62 74 72 69 67 67 65 72 73 20  r.  Subtriggers 
18000 63 72 65 61 74 65 20 73 75 62 63 6f 6e 74 65 78  create subcontex
18010 74 73 20 66 6f 72 20 74 68 65 69 72 20 64 75 72  ts for their dur
18020 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61  ation..**.** ^Ca
18030 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65  lling [sqlite3_e
18040 78 65 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  xec()] or [sqlit
18050 65 33 5f 73 74 65 70 28 29 5d 20 72 65 63 75 72  e3_step()] recur
18060 73 69 76 65 6c 79 20 64 6f 65 73 0a 2a 2a 20 6e  sively does.** n
18070 6f 74 20 63 72 65 61 74 65 20 61 20 6e 65 77 20  ot create a new 
18080 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e  trigger context.
18090 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e  .**.** ^This fun
180a0 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
180b0 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 69 72 65  e number of dire
180c0 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73 20 69  ct row changes i
180d0 6e 20 74 68 65 0a 2a 2a 20 6d 6f 73 74 20 72 65  n the.** most re
180e0 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44  cent INSERT, UPD
180f0 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 20 73  ATE, or DELETE s
18100 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20  tatement within 
18110 74 68 65 20 73 61 6d 65 0a 2a 2a 20 74 72 69 67  the same.** trig
18120 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a  ger context..**.
18130 2a 2a 20 5e 54 68 75 73 2c 20 77 68 65 6e 20 63  ** ^Thus, when c
18140 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 74  alled from the t
18150 6f 70 20 6c 65 76 65 6c 2c 20 74 68 69 73 20 66  op level, this f
18160 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
18170 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66  the.** number of
18180 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20   changes in the 
18190 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45  most recent INSE
181a0 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44  RT, UPDATE, or D
181b0 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 61 6c  ELETE.** that al
181c0 73 6f 20 6f 63 63 75 72 72 65 64 20 61 74 20 74  so occurred at t
181d0 68 65 20 74 6f 70 20 6c 65 76 65 6c 2e 20 20 5e  he top level.  ^
181e0 28 57 69 74 68 69 6e 20 74 68 65 20 62 6f 64 79  (Within the body
181f0 20 6f 66 20 61 20 74 72 69 67 67 65 72 2c 0a 2a   of a trigger,.*
18200 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68  * the sqlite3_ch
18210 61 6e 67 65 73 28 29 20 69 6e 74 65 72 66 61 63  anges() interfac
18220 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20  e can be called 
18230 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62  to find the numb
18240 65 72 20 6f 66 0a 2a 2a 20 63 68 61 6e 67 65 73  er of.** changes
18250 20 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63   in the most rec
18260 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20  ently completed 
18270 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20  INSERT, UPDATE, 
18280 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61  or DELETE.** sta
18290 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68  tement within th
182a0 65 20 62 6f 64 79 20 6f 66 20 74 68 65 20 73 61  e body of the sa
182b0 6d 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a 20 48  me trigger..** H
182c0 6f 77 65 76 65 72 2c 20 74 68 65 20 6e 75 6d 62  owever, the numb
182d0 65 72 20 72 65 74 75 72 6e 65 64 20 64 6f 65 73  er returned does
182e0 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63 68 61   not include cha
182f0 6e 67 65 73 0a 2a 2a 20 63 61 75 73 65 64 20 62  nges.** caused b
18300 79 20 73 75 62 74 72 69 67 67 65 72 73 20 73 69  y subtriggers si
18310 6e 63 65 20 74 68 6f 73 65 20 68 61 76 65 20 74  nce those have t
18320 68 65 69 72 20 6f 77 6e 20 63 6f 6e 74 65 78 74  heir own context
18330 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  .)^.**.** See al
18340 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  so the [sqlite3_
18350 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d  total_changes()]
18360 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a   interface, the.
18370 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65  ** [count_change
18380 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74  s pragma], and t
18390 68 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53 51  he [changes() SQ
183a0 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a  L function]..**.
183b0 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65  ** If a separate
183c0 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68   thread makes ch
183d0 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d  anges on the sam
183e0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
183f0 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b  ction.** while [
18400 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
18410 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68  )] is running th
18420 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  en the value ret
18430 75 72 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72  urned.** is unpr
18440 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f  edictable and no
18450 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f  t meaningful..*/
18460 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
18470 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
18480 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
18490 2a 20 43 41 50 49 33 52 45 46 3a 20 54 6f 74 61  * CAPI3REF: Tota
184a0 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73  l Number Of Rows
184b0 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20   Modified.**.** 
184c0 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72  ^This function r
184d0 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
184e0 72 20 6f 66 20 72 6f 77 20 63 68 61 6e 67 65 73  r of row changes
184f0 20 63 61 75 73 65 64 20 62 79 20 5b 49 4e 53 45   caused by [INSE
18500 52 54 5d 2c 0a 2a 2a 20 5b 55 50 44 41 54 45 5d  RT],.** [UPDATE]
18510 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61   or [DELETE] sta
18520 74 65 6d 65 6e 74 73 20 73 69 6e 63 65 20 74 68  tements since th
18530 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
18540 65 63 74 69 6f 6e 5d 20 77 61 73 20 6f 70 65 6e  ection] was open
18550 65 64 2e 0a 2a 2a 20 5e 28 54 68 65 20 63 6f 75  ed..** ^(The cou
18560 6e 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  nt returned by s
18570 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
18580 6e 67 65 73 28 29 20 69 6e 63 6c 75 64 65 73 20  nges() includes 
18590 61 6c 6c 20 63 68 61 6e 67 65 73 0a 2a 2a 20 66  all changes.** f
185a0 72 6f 6d 20 61 6c 6c 20 5b 43 52 45 41 54 45 20  rom all [CREATE 
185b0 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 65  TRIGGER | trigge
185c0 72 5d 20 63 6f 6e 74 65 78 74 73 20 61 6e 64 20  r] contexts and 
185d0 63 68 61 6e 67 65 73 20 6d 61 64 65 20 62 79 0a  changes made by.
185e0 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20  ** [foreign key 
185f0 61 63 74 69 6f 6e 73 5d 2e 20 48 6f 77 65 76 65  actions]. Howeve
18600 72 2c 0a 2a 2a 20 74 68 65 20 63 6f 75 6e 74 20  r,.** the count 
18610 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65  does not include
18620 20 63 68 61 6e 67 65 73 20 75 73 65 64 20 74 6f   changes used to
18630 20 69 6d 70 6c 65 6d 65 6e 74 20 5b 52 45 50 4c   implement [REPL
18640 41 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74 73  ACE] constraints
18650 2c 0a 2a 2a 20 64 6f 20 72 6f 6c 6c 62 61 63 6b  ,.** do rollback
18660 73 20 6f 72 20 41 42 4f 52 54 20 70 72 6f 63 65  s or ABORT proce
18670 73 73 69 6e 67 2c 20 6f 72 20 5b 44 52 4f 50 20  ssing, or [DROP 
18680 54 41 42 4c 45 5d 20 70 72 6f 63 65 73 73 69 6e  TABLE] processin
18690 67 2e 20 20 54 68 65 0a 2a 2a 20 63 6f 75 6e 74  g.  The.** count
186a0 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64   does not includ
186b0 65 20 72 6f 77 73 20 6f 66 20 76 69 65 77 73 20  e rows of views 
186c0 74 68 61 74 20 66 69 72 65 20 61 6e 20 5b 49 4e  that fire an [IN
186d0 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72  STEAD OF trigger
186e0 5d 2c 0a 2a 2a 20 74 68 6f 75 67 68 20 69 66 20  ],.** though if 
186f0 74 68 65 20 49 4e 53 54 45 41 44 20 4f 46 20 74  the INSTEAD OF t
18700 72 69 67 67 65 72 20 6d 61 6b 65 73 20 63 68 61  rigger makes cha
18710 6e 67 65 73 20 6f 66 20 69 74 73 20 6f 77 6e 2c  nges of its own,
18720 20 74 68 6f 73 65 20 63 68 61 6e 67 65 73 20 0a   those changes .
18730 2a 2a 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 29  ** are counted.)
18740 5e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ^.** ^The sqlite
18750 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
18760 29 20 66 75 6e 63 74 69 6f 6e 20 63 6f 75 6e 74  ) function count
18770 73 20 74 68 65 20 63 68 61 6e 67 65 73 20 61 73  s the changes as
18780 20 73 6f 6f 6e 20 61 73 0a 2a 2a 20 74 68 65 20   soon as.** the 
18790 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 6d  statement that m
187a0 61 6b 65 73 20 74 68 65 6d 20 69 73 20 63 6f 6d  akes them is com
187b0 70 6c 65 74 65 64 20 28 77 68 65 6e 20 74 68 65  pleted (when the
187c0 20 73 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   statement handl
187d0 65 0a 2a 2a 20 69 73 20 70 61 73 73 65 64 20 74  e.** is passed t
187e0 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  o [sqlite3_reset
187f0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
18800 66 69 6e 61 6c 69 7a 65 28 29 5d 29 2e 0a 2a 2a  finalize()])..**
18810 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65  .** See also the
18820 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65   [sqlite3_change
18830 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20  s()] interface, 
18840 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68  the.** [count_ch
18850 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 61  anges pragma], a
18860 6e 64 20 74 68 65 20 5b 74 6f 74 61 6c 5f 63 68  nd the [total_ch
18870 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63  anges() SQL func
18880 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  tion]..**.** If 
18890 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61  a separate threa
188a0 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20  d makes changes 
188b0 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  on the same data
188c0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
188d0 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65  ** while [sqlite
188e0 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
188f0 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68  )] is running th
18900 65 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20  en the value.** 
18910 72 65 74 75 72 6e 65 64 20 69 73 20 75 6e 70 72  returned is unpr
18920 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f  edictable and no
18930 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f  t meaningful..*/
18940 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
18950 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
18960 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b  anges(sqlite3*);
18970 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
18980 3a 20 49 6e 74 65 72 72 75 70 74 20 41 20 4c 6f  : Interrupt A Lo
18990 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72 79  ng-Running Query
189a0 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e  .**.** ^This fun
189b0 63 74 69 6f 6e 20 63 61 75 73 65 73 20 61 6e 79  ction causes any
189c0 20 70 65 6e 64 69 6e 67 20 64 61 74 61 62 61 73   pending databas
189d0 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 61  e operation to a
189e0 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75  bort and.** retu
189f0 72 6e 20 61 74 20 69 74 73 20 65 61 72 6c 69 65  rn at its earlie
18a00 73 74 20 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20  st opportunity. 
18a10 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20  This routine is 
18a20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c  typically.** cal
18a30 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e 73 65 20  led in response 
18a40 74 6f 20 61 20 75 73 65 72 20 61 63 74 69 6f 6e  to a user action
18a50 20 73 75 63 68 20 61 73 20 70 72 65 73 73 69 6e   such as pressin
18a60 67 20 22 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72  g "Cancel".** or
18a70 20 43 74 72 6c 2d 43 20 77 68 65 72 65 20 74 68   Ctrl-C where th
18a80 65 20 75 73 65 72 20 77 61 6e 74 73 20 61 20 6c  e user wants a l
18a90 6f 6e 67 20 71 75 65 72 79 20 6f 70 65 72 61 74  ong query operat
18aa0 69 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 69  ion to halt.** i
18ab0 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a  mmediately..**.*
18ac0 2a 20 5e 49 74 20 69 73 20 73 61 66 65 20 74 6f  * ^It is safe to
18ad0 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69   call this routi
18ae0 6e 65 20 66 72 6f 6d 20 61 20 74 68 72 65 61 64  ne from a thread
18af0 20 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20   different from 
18b00 74 68 65 0a 2a 2a 20 74 68 72 65 61 64 20 74 68  the.** thread th
18b10 61 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20  at is currently 
18b20 72 75 6e 6e 69 6e 67 20 74 68 65 20 64 61 74 61  running the data
18b30 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20  base operation. 
18b40 20 42 75 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f   But it.** is no
18b50 74 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74  t safe to call t
18b60 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68  his routine with
18b70 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e   a [database con
18b80 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a  nection] that.**
18b90 20 69 73 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69   is closed or mi
18ba0 67 68 74 20 63 6c 6f 73 65 20 62 65 66 6f 72 65  ght close before
18bb0 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
18bc0 70 74 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a  pt() returns..**
18bd0 0a 2a 2a 20 5e 49 66 20 61 6e 20 53 51 4c 20 6f  .** ^If an SQL o
18be0 70 65 72 61 74 69 6f 6e 20 69 73 20 76 65 72 79  peration is very
18bf0 20 6e 65 61 72 6c 79 20 66 69 6e 69 73 68 65 64   nearly finished
18c00 20 61 74 20 74 68 65 20 74 69 6d 65 20 77 68 65   at the time whe
18c10 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74  n.** sqlite3_int
18c20 65 72 72 75 70 74 28 29 20 69 73 20 63 61 6c 6c  errupt() is call
18c30 65 64 2c 20 74 68 65 6e 20 69 74 20 6d 69 67 68  ed, then it migh
18c40 74 20 6e 6f 74 20 68 61 76 65 20 61 6e 20 6f 70  t not have an op
18c50 70 6f 72 74 75 6e 69 74 79 0a 2a 2a 20 74 6f 20  portunity.** to 
18c60 62 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 61  be interrupted a
18c70 6e 64 20 6d 69 67 68 74 20 63 6f 6e 74 69 6e 75  nd might continu
18c80 65 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e  e to completion.
18c90 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f  .**.** ^An SQL o
18ca0 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20 69 73  peration that is
18cb0 20 69 6e 74 65 72 72 75 70 74 65 64 20 77 69 6c   interrupted wil
18cc0 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  l return [SQLITE
18cd0 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 20  _INTERRUPT]..** 
18ce0 5e 49 66 20 74 68 65 20 69 6e 74 65 72 72 75 70  ^If the interrup
18cf0 74 65 64 20 53 51 4c 20 6f 70 65 72 61 74 69 6f  ted SQL operatio
18d00 6e 20 69 73 20 61 6e 20 49 4e 53 45 52 54 2c 20  n is an INSERT, 
18d10 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54  UPDATE, or DELET
18d20 45 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 73  E.** that is ins
18d30 69 64 65 20 61 6e 20 65 78 70 6c 69 63 69 74 20  ide an explicit 
18d40 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65  transaction, the
18d50 6e 20 74 68 65 20 65 6e 74 69 72 65 20 74 72 61  n the entire tra
18d60 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c  nsaction.** will
18d70 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20   be rolled back 
18d80 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a  automatically..*
18d90 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
18da0 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20 63  3_interrupt(D) c
18db0 61 6c 6c 20 69 73 20 69 6e 20 65 66 66 65 63 74  all is in effect
18dc0 20 75 6e 74 69 6c 20 61 6c 6c 20 63 75 72 72 65   until all curre
18dd0 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20  ntly running.** 
18de0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 6f  SQL statements o
18df0 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  n [database conn
18e00 65 63 74 69 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65  ection] D comple
18e10 74 65 2e 20 20 5e 41 6e 79 20 6e 65 77 20 53 51  te.  ^Any new SQ
18e20 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  L statements.** 
18e30 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64  that are started
18e40 20 61 66 74 65 72 20 74 68 65 20 73 71 6c 69 74   after the sqlit
18e50 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63  e3_interrupt() c
18e60 61 6c 6c 20 61 6e 64 20 62 65 66 6f 72 65 20 74  all and before t
18e70 68 65 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 73  he .** running s
18e80 74 61 74 65 6d 65 6e 74 73 20 72 65 61 63 68 65  tatements reache
18e90 73 20 7a 65 72 6f 20 61 72 65 20 69 6e 74 65 72  s zero are inter
18ea0 72 75 70 74 65 64 20 61 73 20 69 66 20 74 68 65  rupted as if the
18eb0 79 20 68 61 64 20 62 65 65 6e 0a 2a 2a 20 72 75  y had been.** ru
18ec0 6e 6e 69 6e 67 20 70 72 69 6f 72 20 74 6f 20 74  nning prior to t
18ed0 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  he sqlite3_inter
18ee0 72 75 70 74 28 29 20 63 61 6c 6c 2e 20 20 5e 4e  rupt() call.  ^N
18ef0 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ew SQL statement
18f00 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74  s.** that are st
18f10 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20  arted after the 
18f20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e  running statemen
18f30 74 20 63 6f 75 6e 74 20 72 65 61 63 68 65 73 20  t count reaches 
18f40 7a 65 72 6f 20 61 72 65 0a 2a 2a 20 6e 6f 74 20  zero are.** not 
18f50 65 66 66 65 63 74 65 64 20 62 79 20 74 68 65 20  effected by the 
18f60 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
18f70 74 28 29 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20  t()..** ^A call 
18f80 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  to sqlite3_inter
18f90 72 75 70 74 28 44 29 20 74 68 61 74 20 6f 63 63  rupt(D) that occ
18fa0 75 72 73 20 77 68 65 6e 20 74 68 65 72 65 20 61  urs when there a
18fb0 72 65 20 6e 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a  re no running.**
18fc0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
18fd0 69 73 20 61 20 6e 6f 2d 6f 70 20 61 6e 64 20 68  is a no-op and h
18fe0 61 73 20 6e 6f 20 65 66 66 65 63 74 20 6f 6e 20  as no effect on 
18ff0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  SQL statements.*
19000 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74  * that are start
19010 65 64 20 61 66 74 65 72 20 74 68 65 20 73 71 6c  ed after the sql
19020 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
19030 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 0a 2a   call returns..*
19040 2a 0a 2a 2a 20 49 66 20 74 68 65 20 64 61 74 61  *.** If the data
19050 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
19060 63 6c 6f 73 65 73 20 77 68 69 6c 65 20 5b 73 71  closes while [sq
19070 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
19080 29 5d 0a 2a 2a 20 69 73 20 72 75 6e 6e 69 6e 67  )].** is running
19090 20 74 68 65 6e 20 62 61 64 20 74 68 69 6e 67 73   then bad things
190a0 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 68 61 70   will likely hap
190b0 70 65 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  pen..*/.SQLITE_A
190c0 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  PI void sqlite3_
190d0 69 6e 74 65 72 72 75 70 74 28 73 71 6c 69 74 65  interrupt(sqlite
190e0 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  3*);../*.** CAPI
190f0 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20  3REF: Determine 
19100 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d  If An SQL Statem
19110 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74 65 0a  ent Is Complete.
19120 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
19130 69 6e 65 73 20 61 72 65 20 75 73 65 66 75 6c 20  ines are useful 
19140 64 75 72 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c  during command-l
19150 69 6e 65 20 69 6e 70 75 74 20 74 6f 20 64 65 74  ine input to det
19160 65 72 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a  ermine if the.**
19170 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65 72   currently enter
19180 65 64 20 74 65 78 74 20 73 65 65 6d 73 20 74 6f  ed text seems to
19190 20 66 6f 72 6d 20 61 20 63 6f 6d 70 6c 65 74 65   form a complete
191a0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f   SQL statement o
191b0 72 0a 2a 2a 20 69 66 20 61 64 64 69 74 69 6f 6e  r.** if addition
191c0 61 6c 20 69 6e 70 75 74 20 69 73 20 6e 65 65 64  al input is need
191d0 65 64 20 62 65 66 6f 72 65 20 73 65 6e 64 69 6e  ed before sendin
191e0 67 20 74 68 65 20 74 65 78 74 20 69 6e 74 6f 0a  g the text into.
191f0 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72 20 70 61  ** SQLite for pa
19200 72 73 69 6e 67 2e 20 20 5e 54 68 65 73 65 20 72  rsing.  ^These r
19210 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 31  outines return 1
19220 20 69 66 20 74 68 65 20 69 6e 70 75 74 20 73 74   if the input st
19230 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72 73 20  ring.** appears 
19240 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65 74 65  to be a complete
19250 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20   SQL statement. 
19260 20 5e 41 20 73 74 61 74 65 6d 65 6e 74 20 69 73   ^A statement is
19270 20 6a 75 64 67 65 64 20 74 6f 20 62 65 0a 2a 2a   judged to be.**
19280 20 63 6f 6d 70 6c 65 74 65 20 69 66 20 69 74 20   complete if it 
19290 65 6e 64 73 20 77 69 74 68 20 61 20 73 65 6d 69  ends with a semi
192a0 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 20  colon token and 
192b0 69 73 20 6e 6f 74 20 61 20 70 72 65 66 69 78 20  is not a prefix 
192c0 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72  of a.** well-for
192d0 6d 65 64 20 43 52 45 41 54 45 20 54 52 49 47 47  med CREATE TRIGG
192e0 45 52 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e  ER statement.  ^
192f0 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20  Semicolons that 
19300 61 72 65 20 65 6d 62 65 64 64 65 64 20 77 69 74  are embedded wit
19310 68 69 6e 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69  hin.** string li
19320 74 65 72 61 6c 73 20 6f 72 20 71 75 6f 74 65 64  terals or quoted
19330 20 69 64 65 6e 74 69 66 69 65 72 20 6e 61 6d 65   identifier name
19340 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72  s or comments ar
19350 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e  e not.** indepen
19360 64 65 6e 74 20 74 6f 6b 65 6e 73 20 28 74 68 65  dent tokens (the
19370 79 20 61 72 65 20 70 61 72 74 20 6f 66 20 74 68  y are part of th
19380 65 20 74 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68  e token in which
19390 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62   they are.** emb
193a0 65 64 64 65 64 29 20 61 6e 64 20 74 68 75 73 20  edded) and thus 
193b0 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20  do not count as 
193c0 61 20 73 74 61 74 65 6d 65 6e 74 20 74 65 72 6d  a statement term
193d0 69 6e 61 74 6f 72 2e 20 20 5e 57 68 69 74 65 73  inator.  ^Whites
193e0 70 61 63 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d  pace.** and comm
193f0 65 6e 74 73 20 74 68 61 74 20 66 6f 6c 6c 6f 77  ents that follow
19400 20 74 68 65 20 66 69 6e 61 6c 20 73 65 6d 69 63   the final semic
19410 6f 6c 6f 6e 20 61 72 65 20 69 67 6e 6f 72 65 64  olon are ignored
19420 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  ..**.** ^These r
19430 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 30  outines return 0
19440 20 69 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e   if the statemen
19450 74 20 69 73 20 69 6e 63 6f 6d 70 6c 65 74 65 2e  t is incomplete.
19460 20 20 5e 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72    ^If a.** memor
19470 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69  y allocation fai
19480 6c 73 2c 20 74 68 65 6e 20 53 51 4c 49 54 45 5f  ls, then SQLITE_
19490 4e 4f 4d 45 4d 20 69 73 20 72 65 74 75 72 6e 65  NOMEM is returne
194a0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  d..**.** ^These 
194b0 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f 74 20  routines do not 
194c0 70 61 72 73 65 20 74 68 65 20 53 51 4c 20 73 74  parse the SQL st
194d0 61 74 65 6d 65 6e 74 73 20 74 68 75 73 0a 2a 2a  atements thus.**
194e0 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65 63 74   will not detect
194f0 20 73 79 6e 74 61 63 74 69 63 61 6c 6c 79 20 69   syntactically i
19500 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a 2a 2a  ncorrect SQL..**
19510 0a 2a 2a 20 5e 28 49 66 20 53 51 4c 69 74 65 20  .** ^(If SQLite 
19520 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 69 6e 69  has not been ini
19530 74 69 61 6c 69 7a 65 64 20 75 73 69 6e 67 20 5b  tialized using [
19540 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
19550 7a 65 28 29 5d 20 70 72 69 6f 72 20 0a 2a 2a 20  ze()] prior .** 
19560 74 6f 20 69 6e 76 6f 6b 69 6e 67 20 73 71 6c 69  to invoking sqli
19570 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29  te3_complete16()
19580 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 69 6e   then sqlite3_in
19590 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e  itialize() is in
195a0 76 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d 61 74  voked.** automat
195b0 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65  ically by sqlite
195c0 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 2e 20  3_complete16(). 
195d0 20 49 66 20 74 68 61 74 20 69 6e 69 74 69 61 6c   If that initial
195e0 69 7a 61 74 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a  ization fails,.*
195f0 2a 20 74 68 65 6e 20 74 68 65 20 72 65 74 75 72  * then the retur
19600 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c  n value from sql
19610 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
19620 29 20 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65  ) will be non-ze
19630 72 6f 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73 73  ro.** regardless
19640 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e   of whether or n
19650 6f 74 20 74 68 65 20 69 6e 70 75 74 20 53 51 4c  ot the input SQL
19660 20 69 73 20 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a   is complete.)^.
19670 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20  **.** The input 
19680 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70  to [sqlite3_comp
19690 6c 65 74 65 28 29 5d 20 6d 75 73 74 20 62 65 20  lete()] must be 
196a0 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
196b0 64 0a 2a 2a 20 55 54 46 2d 38 20 73 74 72 69 6e  d.** UTF-8 strin
196c0 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70  g..**.** The inp
196d0 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ut to [sqlite3_c
196e0 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20 6d 75 73  omplete16()] mus
196f0 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d  t be a zero-term
19700 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36  inated.** UTF-16
19710 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 76   string in nativ
19720 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f  e byte order..*/
19730 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
19740 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
19750 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  (const char *sql
19760 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
19770 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65  t sqlite3_comple
19780 74 65 31 36 28 63 6f 6e 73 74 20 76 6f 69 64 20  te16(const void 
19790 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  *sql);../*.** CA
197a0 50 49 33 52 45 46 3a 20 52 65 67 69 73 74 65 72  PI3REF: Register
197b0 20 41 20 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48   A Callback To H
197c0 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f 42 55 53  andle SQLITE_BUS
197d0 59 20 45 72 72 6f 72 73 0a 2a 2a 0a 2a 2a 20 5e  Y Errors.**.** ^
197e0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74  This routine set
197f0 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  s a callback fun
19800 63 74 69 6f 6e 20 74 68 61 74 20 6d 69 67 68 74  ction that might
19810 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   be invoked when
19820 65 76 65 72 0a 2a 2a 20 61 6e 20 61 74 74 65 6d  ever.** an attem
19830 70 74 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70  pt is made to op
19840 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 74 61  en a database ta
19850 62 6c 65 20 74 68 61 74 20 61 6e 6f 74 68 65 72  ble that another
19860 20 74 68 72 65 61 64 0a 2a 2a 20 6f 72 20 70 72   thread.** or pr
19870 6f 63 65 73 73 20 68 61 73 20 6c 6f 63 6b 65 64  ocess has locked
19880 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
19890 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73  busy callback is
198a0 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c   NULL, then [SQL
198b0 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51  ITE_BUSY] or [SQ
198c0 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b  LITE_IOERR_BLOCK
198d0 45 44 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e  ED].** is return
198e0 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 75  ed immediately u
198f0 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67  pon encountering
19900 20 74 68 65 20 6c 6f 63 6b 2e 20 20 5e 49 66 20   the lock.  ^If 
19910 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63  the busy callbac
19920 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  k.** is not NULL
19930 2c 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 62  , then the callb
19940 61 63 6b 20 6d 69 67 68 74 20 62 65 20 69 6e 76  ack might be inv
19950 6f 6b 65 64 20 77 69 74 68 20 74 77 6f 20 61 72  oked with two ar
19960 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e  guments..**.** ^
19970 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
19980 6e 74 20 74 6f 20 74 68 65 20 62 75 73 79 20 68  nt to the busy h
19990 61 6e 64 6c 65 72 20 69 73 20 61 20 63 6f 70 79  andler is a copy
199a0 20 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 70 6f   of the void* po
199b0 69 6e 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69  inter which.** i
199c0 73 20 74 68 65 20 74 68 69 72 64 20 61 72 67 75  s the third argu
199d0 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
199e0 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 2e 20  busy_handler(). 
199f0 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67   ^The second arg
19a00 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20  ument to.** the 
19a10 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63 61 6c  busy handler cal
19a20 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e 75 6d  lback is the num
19a30 62 65 72 20 6f 66 20 74 69 6d 65 73 20 74 68 61  ber of times tha
19a40 74 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  t the busy handl
19a50 65 72 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69  er has.** been i
19a60 6e 76 6f 6b 65 64 20 66 6f 72 20 74 68 69 73 20  nvoked for this 
19a70 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20  locking event.  
19a80 5e 49 66 20 74 68 65 0a 2a 2a 20 62 75 73 79 20  ^If the.** busy 
19a90 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
19aa0 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61 64 64 69   0, then no addi
19ab0 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70 74 73 20  tional attempts 
19ac0 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61  are made to.** a
19ad0 63 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61  ccess the databa
19ae0 73 65 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42  se and [SQLITE_B
19af0 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  USY] or [SQLITE_
19b00 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69  IOERR_BLOCKED] i
19b10 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e  s returned..** ^
19b20 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  If the callback 
19b30 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f  returns non-zero
19b40 2c 20 74 68 65 6e 20 61 6e 6f 74 68 65 72 20 61  , then another a
19b50 74 74 65 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64  ttempt.** is mad
19b60 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61  e to open the da
19b70 74 61 62 61 73 65 20 66 6f 72 20 72 65 61 64 69  tabase for readi
19b80 6e 67 20 61 6e 64 20 74 68 65 20 63 79 63 6c 65  ng and the cycle
19b90 20 72 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20   repeats..**.** 
19ba0 54 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66 20  The presence of 
19bb0 61 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64  a busy handler d
19bc0 6f 65 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65  oes not guarante
19bd0 65 20 74 68 61 74 20 69 74 20 77 69 6c 6c 20 62  e that it will b
19be0 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65  e invoked.** whe
19bf0 6e 20 74 68 65 72 65 20 69 73 20 6c 6f 63 6b 20  n there is lock 
19c00 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20 5e 49 66 20  contention. ^If 
19c10 53 51 4c 69 74 65 20 64 65 74 65 72 6d 69 6e 65  SQLite determine
19c20 73 20 74 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20  s that invoking 
19c30 74 68 65 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64  the busy.** hand
19c40 6c 65 72 20 63 6f 75 6c 64 20 72 65 73 75 6c 74  ler could result
19c50 20 69 6e 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20   in a deadlock, 
19c60 69 74 20 77 69 6c 6c 20 67 6f 20 61 68 65 61 64  it will go ahead
19c70 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c   and return [SQL
19c80 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 6f 72 20  ITE_BUSY].** or 
19c90 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c  [SQLITE_IOERR_BL
19ca0 4f 43 4b 45 44 5d 20 69 6e 73 74 65 61 64 20 6f  OCKED] instead o
19cb0 66 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62  f invoking the b
19cc0 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20  usy handler..** 
19cd0 43 6f 6e 73 69 64 65 72 20 61 20 73 63 65 6e 61  Consider a scena
19ce0 72 69 6f 20 77 68 65 72 65 20 6f 6e 65 20 70 72  rio where one pr
19cf0 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67  ocess is holding
19d00 20 61 20 72 65 61 64 20 6c 6f 63 6b 20 74 68 61   a read lock tha
19d10 74 0a 2a 2a 20 69 74 20 69 73 20 74 72 79 69 6e  t.** it is tryin
19d20 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20  g to promote to 
19d30 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20  a reserved lock 
19d40 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 20  and.** a second 
19d50 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69  process is holdi
19d60 6e 67 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f  ng a reserved lo
19d70 63 6b 20 74 68 61 74 20 69 74 20 69 73 20 74 72  ck that it is tr
19d80 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f  ying.** to promo
19d90 74 65 20 74 6f 20 61 6e 20 65 78 63 6c 75 73 69  te to an exclusi
19da0 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65 20 66 69  ve lock.  The fi
19db0 72 73 74 20 70 72 6f 63 65 73 73 20 63 61 6e 6e  rst process cann
19dc0 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a 20 62 65  ot proceed.** be
19dd0 63 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63  cause it is bloc
19de0 6b 65 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e  ked by the secon
19df0 64 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64  d and the second
19e00 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 0a   process cannot.
19e10 2a 2a 20 70 72 6f 63 65 65 64 20 62 65 63 61 75  ** proceed becau
19e20 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64  se it is blocked
19e30 20 62 79 20 74 68 65 20 66 69 72 73 74 2e 20 20   by the first.  
19e40 49 66 20 62 6f 74 68 20 70 72 6f 63 65 73 73 65  If both processe
19e50 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20  s.** invoke the 
19e60 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2c 20 6e  busy handlers, n
19e70 65 69 74 68 65 72 20 77 69 6c 6c 20 6d 61 6b 65  either will make
19e80 20 61 6e 79 20 70 72 6f 67 72 65 73 73 2e 20 20   any progress.  
19e90 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 51  Therefore,.** SQ
19ea0 4c 69 74 65 20 72 65 74 75 72 6e 73 20 5b 53 51  Lite returns [SQ
19eb0 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f 72 20 74  LITE_BUSY] for t
19ec0 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73  he first process
19ed0 2c 20 68 6f 70 69 6e 67 20 74 68 61 74 20 74 68  , hoping that th
19ee0 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 63  is.** will induc
19ef0 65 20 74 68 65 20 66 69 72 73 74 20 70 72 6f 63  e the first proc
19f00 65 73 73 20 74 6f 20 72 65 6c 65 61 73 65 20 69  ess to release i
19f10 74 73 20 72 65 61 64 20 6c 6f 63 6b 20 61 6e 64  ts read lock and
19f20 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 65   allow.** the se
19f30 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 74 6f 20  cond process to 
19f40 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  proceed..**.** ^
19f50 54 68 65 20 64 65 66 61 75 6c 74 20 62 75 73 79  The default busy
19f60 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c   callback is NUL
19f70 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53  L..**.** ^The [S
19f80 51 4c 49 54 45 5f 42 55 53 59 5d 20 65 72 72 6f  QLITE_BUSY] erro
19f90 72 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20 74  r is converted t
19fa0 6f 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  o [SQLITE_IOERR_
19fb0 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 77 68 65 6e  BLOCKED].** when
19fc0 20 53 51 4c 69 74 65 20 69 73 20 69 6e 20 74 68   SQLite is in th
19fd0 65 20 6d 69 64 64 6c 65 20 6f 66 20 61 20 6c 61  e middle of a la
19fe0 72 67 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  rge transaction 
19ff0 77 68 65 72 65 20 61 6c 6c 20 74 68 65 0a 2a 2a  where all the.**
1a000 20 63 68 61 6e 67 65 73 20 77 69 6c 6c 20 6e 6f   changes will no
1a010 74 20 66 69 74 20 69 6e 74 6f 20 74 68 65 20 69  t fit into the i
1a020 6e 2d 6d 65 6d 6f 72 79 20 63 61 63 68 65 2e 20  n-memory cache. 
1a030 20 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20   SQLite will.** 
1a040 61 6c 72 65 61 64 79 20 68 6f 6c 64 20 61 20 52  already hold a R
1a050 45 53 45 52 56 45 44 20 6c 6f 63 6b 20 6f 6e 20  ESERVED lock on 
1a060 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
1a070 65 2c 20 62 75 74 20 69 74 20 6e 65 65 64 73 0a  e, but it needs.
1a080 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68  ** to promote th
1a090 69 73 20 6c 6f 63 6b 20 74 6f 20 45 58 43 4c 55  is lock to EXCLU
1a0a0 53 49 56 45 20 73 6f 20 74 68 61 74 20 69 74 20  SIVE so that it 
1a0b0 63 61 6e 20 73 70 69 6c 6c 20 63 61 63 68 65 0a  can spill cache.
1a0c0 2a 2a 20 70 61 67 65 73 20 69 6e 74 6f 20 74 68  ** pages into th
1a0d0 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
1a0e0 77 69 74 68 6f 75 74 20 68 61 72 6d 20 74 6f 20  without harm to 
1a0f0 63 6f 6e 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65  concurrent.** re
1a100 61 64 65 72 73 2e 20 20 5e 49 66 20 69 74 20 69  aders.  ^If it i
1a110 73 20 75 6e 61 62 6c 65 20 74 6f 20 70 72 6f 6d  s unable to prom
1a120 6f 74 65 20 74 68 65 20 6c 6f 63 6b 2c 20 74 68  ote the lock, th
1a130 65 6e 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79  en the in-memory
1a140 0a 2a 2a 20 63 61 63 68 65 20 77 69 6c 6c 20 62  .** cache will b
1a150 65 20 6c 65 66 74 20 69 6e 20 61 6e 20 69 6e 63  e left in an inc
1a160 6f 6e 73 69 73 74 65 6e 74 20 73 74 61 74 65 20  onsistent state 
1a170 61 6e 64 20 73 6f 20 74 68 65 20 65 72 72 6f 72  and so the error
1a180 0a 2a 2a 20 63 6f 64 65 20 69 73 20 70 72 6f 6d  .** code is prom
1a190 6f 74 65 64 20 66 72 6f 6d 20 74 68 65 20 72 65  oted from the re
1a1a0 6c 61 74 69 76 65 6c 79 20 62 65 6e 69 67 6e 20  latively benign 
1a1b0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 74 6f  [SQLITE_BUSY] to
1a1c0 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 65 76  .** the more sev
1a1d0 65 72 65 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52  ere [SQLITE_IOER
1a1e0 52 5f 42 4c 4f 43 4b 45 44 5d 2e 20 20 5e 54 68  R_BLOCKED].  ^Th
1a1f0 69 73 20 65 72 72 6f 72 20 63 6f 64 65 20 70 72  is error code pr
1a200 6f 6d 6f 74 69 6f 6e 0a 2a 2a 20 66 6f 72 63 65  omotion.** force
1a210 73 20 61 6e 20 61 75 74 6f 6d 61 74 69 63 20 72  s an automatic r
1a220 6f 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 63  ollback of the c
1a230 68 61 6e 67 65 73 2e 20 20 53 65 65 20 74 68 65  hanges.  See the
1a240 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22 2f 63 76  .** <a href="/cv
1a250 73 74 72 61 63 2f 77 69 6b 69 3f 70 3d 43 6f 72  strac/wiki?p=Cor
1a260 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67  ruptionFollowing
1a270 42 75 73 79 45 72 72 6f 72 22 3e 0a 2a 2a 20 43  BusyError">.** C
1a280 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69  orruptionFollowi
1a290 6e 67 42 75 73 79 45 72 72 6f 72 3c 2f 61 3e 20  ngBusyError</a> 
1a2a0 77 69 6b 69 20 70 61 67 65 20 66 6f 72 20 61 20  wiki page for a 
1a2b0 64 69 73 63 75 73 73 69 6f 6e 20 6f 66 20 77 68  discussion of wh
1a2c0 79 0a 2a 2a 20 74 68 69 73 20 69 73 20 69 6d 70  y.** this is imp
1a2d0 6f 72 74 61 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ortant..**.** ^(
1a2e0 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62  There can only b
1a2f0 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20  e a single busy 
1a300 68 61 6e 64 6c 65 72 20 64 65 66 69 6e 65 64 20  handler defined 
1a310 66 6f 72 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74  for each.** [dat
1a320 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1a330 5d 2e 20 20 53 65 74 74 69 6e 67 20 61 20 6e 65  ].  Setting a ne
1a340 77 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63  w busy handler c
1a350 6c 65 61 72 73 20 61 6e 79 0a 2a 2a 20 70 72 65  lears any.** pre
1a360 76 69 6f 75 73 6c 79 20 73 65 74 20 68 61 6e 64  viously set hand
1a370 6c 65 72 2e 29 5e 20 20 5e 4e 6f 74 65 20 74 68  ler.)^  ^Note th
1a380 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  at calling [sqli
1a390 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74  te3_busy_timeout
1a3a0 28 29 5d 0a 2a 2a 20 77 69 6c 6c 20 61 6c 73 6f  ()].** will also
1a3b0 20 73 65 74 20 6f 72 20 63 6c 65 61 72 20 74 68   set or clear th
1a3c0 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a  e busy handler..
1a3d0 2a 2a 0a 2a 2a 20 54 68 65 20 62 75 73 79 20 63  **.** The busy c
1a3e0 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 20 6e  allback should n
1a3f0 6f 74 20 74 61 6b 65 20 61 6e 79 20 61 63 74 69  ot take any acti
1a400 6f 6e 73 20 77 68 69 63 68 20 6d 6f 64 69 66 79  ons which modify
1a410 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
1a420 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74   connection that
1a430 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73   invoked the bus
1a440 79 20 68 61 6e 64 6c 65 72 2e 20 20 41 6e 79 20  y handler.  Any 
1a450 73 75 63 68 20 61 63 74 69 6f 6e 73 0a 2a 2a 20  such actions.** 
1a460 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69  result in undefi
1a470 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a  ned behavior..**
1a480 20 0a 2a 2a 20 41 20 62 75 73 79 20 68 61 6e 64   .** A busy hand
1a490 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f  ler must not clo
1a4a0 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  se the database 
1a4b0 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72  connection.** or
1a4c0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
1a4d0 6d 65 6e 74 5d 20 74 68 61 74 20 69 6e 76 6f 6b  ment] that invok
1a4e0 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ed the busy hand
1a4f0 6c 65 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ler..*/.SQLITE_A
1a500 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  PI int sqlite3_b
1a510 75 73 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69  usy_handler(sqli
1a520 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69  te3*, int(*)(voi
1a530 64 2a 2c 69 6e 74 29 2c 20 76 6f 69 64 2a 29 3b  d*,int), void*);
1a540 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1a550 3a 20 53 65 74 20 41 20 42 75 73 79 20 54 69 6d  : Set A Busy Tim
1a560 65 6f 75 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  eout.**.** ^This
1a570 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20   routine sets a 
1a580 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61  [sqlite3_busy_ha
1a590 6e 64 6c 65 72 20 7c 20 62 75 73 79 20 68 61 6e  ndler | busy han
1a5a0 64 6c 65 72 5d 20 74 68 61 74 20 73 6c 65 65 70  dler] that sleep
1a5b0 73 0a 2a 2a 20 66 6f 72 20 61 20 73 70 65 63 69  s.** for a speci
1a5c0 66 69 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74  fied amount of t
1a5d0 69 6d 65 20 77 68 65 6e 20 61 20 74 61 62 6c 65  ime when a table
1a5e0 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20 5e 54 68   is locked.  ^Th
1a5f0 65 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c  e handler.** wil
1a600 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65  l sleep multiple
1a610 20 74 69 6d 65 73 20 75 6e 74 69 6c 20 61 74 20   times until at 
1a620 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69  least "ms" milli
1a630 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70  seconds of sleep
1a640 69 6e 67 0a 2a 2a 20 68 61 76 65 20 61 63 63 75  ing.** have accu
1a650 6d 75 6c 61 74 65 64 2e 20 20 5e 41 66 74 65 72  mulated.  ^After
1a660 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d   at least "ms" m
1a670 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73  illiseconds of s
1a680 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74 68 65 20  leeping,.** the 
1a690 68 61 6e 64 6c 65 72 20 72 65 74 75 72 6e 73 20  handler returns 
1a6a0 30 20 77 68 69 63 68 20 63 61 75 73 65 73 20 5b  0 which causes [
1a6b0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
1a6c0 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51  to return.** [SQ
1a6d0 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53  LITE_BUSY] or [S
1a6e0 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43  QLITE_IOERR_BLOC
1a6f0 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c  KED]..**.** ^Cal
1a700 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69 6e  ling this routin
1a710 65 20 77 69 74 68 20 61 6e 20 61 72 67 75 6d 65  e with an argume
1a720 6e 74 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20  nt less than or 
1a730 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a  equal to zero.**
1a740 20 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c 20 62   turns off all b
1a750 75 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a  usy handlers..**
1a760 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20  .** ^(There can 
1a770 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65  only be a single
1a780 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f   busy handler fo
1a790 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a  r a particular.*
1a7a0 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
1a7b0 65 63 74 69 6f 6e 5d 20 61 6e 79 20 61 6e 79 20  ection] any any 
1a7c0 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49  given moment.  I
1a7d0 66 20 61 6e 6f 74 68 65 72 20 62 75 73 79 20 68  f another busy h
1a7e0 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73 20 64 65  andler.** was de
1a7f0 66 69 6e 65 64 20 20 28 75 73 69 6e 67 20 5b 73  fined  (using [s
1a800 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
1a810 6c 65 72 28 29 5d 29 20 70 72 69 6f 72 20 74 6f  ler()]) prior to
1a820 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73   calling.** this
1a830 20 72 6f 75 74 69 6e 65 2c 20 74 68 61 74 20 6f   routine, that o
1a840 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65  ther busy handle
1a850 72 20 69 73 20 63 6c 65 61 72 65 64 2e 29 5e 0a  r is cleared.)^.
1a860 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
1a870 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74  t sqlite3_busy_t
1a880 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c  imeout(sqlite3*,
1a890 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a   int ms);../*.**
1a8a0 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 76 65   CAPI3REF: Conve
1a8b0 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e 65 73 20  nience Routines 
1a8c0 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75 65 72  For Running Quer
1a8d0 69 65 73 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69  ies.**.** This i
1a8e0 73 20 61 20 6c 65 67 61 63 79 20 69 6e 74 65 72  s a legacy inter
1a8f0 66 61 63 65 20 74 68 61 74 20 69 73 20 70 72 65  face that is pre
1a900 73 65 72 76 65 64 20 66 6f 72 20 62 61 63 6b 77  served for backw
1a910 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
1a920 74 79 2e 0a 2a 2a 20 55 73 65 20 6f 66 20 74 68  ty..** Use of th
1a930 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  is interface is 
1a940 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e  not recommended.
1a950 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74 69 6f  .**.** Definitio
1a960 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74 20 74  n: A <b>result t
1a970 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f  able</b> is memo
1a980 72 79 20 64 61 74 61 20 73 74 72 75 63 74 75 72  ry data structur
1a990 65 20 63 72 65 61 74 65 64 20 62 79 20 74 68 65  e created by the
1a9a0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65 74  .** [sqlite3_get
1a9b0 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74 65 72 66  _table()] interf
1a9c0 61 63 65 2e 20 20 41 20 72 65 73 75 6c 74 20 74  ace.  A result t
1a9d0 61 62 6c 65 20 72 65 63 6f 72 64 73 20 74 68 65  able records the
1a9e0 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71 75 65  .** complete que
1a9f0 72 79 20 72 65 73 75 6c 74 73 20 66 72 6f 6d 20  ry results from 
1aa00 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75 65 72  one or more quer
1aa10 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  ies..**.** The t
1aa20 61 62 6c 65 20 63 6f 6e 63 65 70 74 75 61 6c 6c  able conceptuall
1aa30 79 20 68 61 73 20 61 20 6e 75 6d 62 65 72 20 6f  y has a number o
1aa40 66 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c 75 6d  f rows and colum
1aa50 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68 65 73  ns.  But.** thes
1aa60 65 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6e 6f  e numbers are no
1aa70 74 20 70 61 72 74 20 6f 66 20 74 68 65 20 72 65  t part of the re
1aa80 73 75 6c 74 20 74 61 62 6c 65 20 69 74 73 65 6c  sult table itsel
1aa90 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e 75 6d  f.  These.** num
1aaa0 62 65 72 73 20 61 72 65 20 6f 62 74 61 69 6e 65  bers are obtaine
1aab0 64 20 73 65 70 61 72 61 74 65 6c 79 2e 20 20 4c  d separately.  L
1aac0 65 74 20 4e 20 62 65 20 74 68 65 20 6e 75 6d 62  et N be the numb
1aad0 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20 61 6e  er of rows.** an
1aae0 64 20 4d 20 62 65 20 74 68 65 20 6e 75 6d 62 65  d M be the numbe
1aaf0 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a  r of columns..**
1ab00 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62  .** A result tab
1ab10 6c 65 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f  le is an array o
1ab20 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65  f pointers to ze
1ab30 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
1ab40 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20  F-8 strings..** 
1ab50 54 68 65 72 65 20 61 72 65 20 28 4e 2b 31 29 2a  There are (N+1)*
1ab60 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20 74 68  M elements in th
1ab70 65 20 61 72 72 61 79 2e 20 20 54 68 65 20 66 69  e array.  The fi
1ab80 72 73 74 20 4d 20 70 6f 69 6e 74 65 72 73 20 70  rst M pointers p
1ab90 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d  oint.** to zero-
1aba0 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e  terminated strin
1abb0 67 73 20 74 68 61 74 20 20 63 6f 6e 74 61 69 6e  gs that  contain
1abc0 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 74 68   the names of th
1abd0 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68  e columns..** Th
1abe0 65 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e 74 72  e remaining entr
1abf0 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20 74 6f  ies all point to
1ac00 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 2e 20   query results. 
1ac10 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20 72 65 73   NULL values res
1ac20 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70  ult.** in NULL p
1ac30 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c 20 6f 74  ointers.  All ot
1ac40 68 65 72 20 76 61 6c 75 65 73 20 61 72 65 20 69  her values are i
1ac50 6e 20 74 68 65 69 72 20 55 54 46 2d 38 20 7a 65  n their UTF-8 ze
1ac60 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ro-terminated.**
1ac70 20 73 74 72 69 6e 67 20 72 65 70 72 65 73 65 6e   string represen
1ac80 74 61 74 69 6f 6e 20 61 73 20 72 65 74 75 72 6e  tation as return
1ac90 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63  ed by [sqlite3_c
1aca0 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a  olumn_text()]..*
1acb0 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61  *.** A result ta
1acc0 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73 69 73  ble might consis
1acd0 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  t of one or more
1ace0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
1acf0 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20 6e 6f  ons..** It is no
1ad00 74 20 73 61 66 65 20 74 6f 20 70 61 73 73 20 61  t safe to pass a
1ad10 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 64 69   result table di
1ad20 72 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c 69 74  rectly to [sqlit
1ad30 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 20 41  e3_free()]..** A
1ad40 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 73 68   result table sh
1ad50 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f 63 61  ould be dealloca
1ad60 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ted using [sqlit
1ad70 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d  e3_free_table()]
1ad80 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73 20 61 6e 20  ..**.** ^(As an 
1ad90 65 78 61 6d 70 6c 65 20 6f 66 20 74 68 65 20 72  example of the r
1ada0 65 73 75 6c 74 20 74 61 62 6c 65 20 66 6f 72 6d  esult table form
1adb0 61 74 2c 20 73 75 70 70 6f 73 65 20 61 20 71 75  at, suppose a qu
1adc0 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73  ery result.** is
1add0 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a   as follows:.**.
1ade0 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
1adf0 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e  pre>.**        N
1ae00 61 6d 65 20 20 20 20 20 20 20 20 7c 20 41 67 65  ame        | Age
1ae10 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d  .**        -----
1ae20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
1ae30 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c 69  --.**        Ali
1ae40 63 65 20 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a  ce       | 43.**
1ae50 20 20 20 20 20 20 20 20 42 6f 62 20 20 20 20 20          Bob     
1ae60 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20      | 28.**     
1ae70 20 20 20 43 69 6e 64 79 20 20 20 20 20 20 20 7c     Cindy       |
1ae80 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62   21.** </pre></b
1ae90 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
1aea0 20 54 68 65 72 65 20 61 72 65 20 74 77 6f 20 63   There are two c
1aeb0 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e 64  olumn (M==2) and
1aec0 20 74 68 72 65 65 20 72 6f 77 73 20 28 4e 3d 3d   three rows (N==
1aed0 33 29 2e 20 20 54 68 75 73 20 74 68 65 0a 2a 2a  3).  Thus the.**
1aee0 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 68 61   result table ha
1aef0 73 20 38 20 65 6e 74 72 69 65 73 2e 20 20 53 75  s 8 entries.  Su
1af00 70 70 6f 73 65 20 74 68 65 20 72 65 73 75 6c 74  ppose the result
1af10 20 74 61 62 6c 65 20 69 73 20 73 74 6f 72 65 64   table is stored
1af20 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61 79 20  .** in an array 
1af30 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c 74 2e 20  names azResult. 
1af40 20 54 68 65 6e 20 61 7a 52 65 73 75 6c 74 20 68   Then azResult h
1af50 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e 74 65 6e  olds this conten
1af60 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  t:.**.** <blockq
1af70 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20  uote><pre>.**   
1af80 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
1af90 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a  1;0] = "Name";.*
1afa0 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
1afb0 74 26 23 39 31 3b 31 5d 20 3d 20 22 41 67 65 22  t&#91;1] = "Age"
1afc0 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
1afd0 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20 22 41  sult&#91;2] = "A
1afe0 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20  lice";.**       
1aff0 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 33 5d   azResult&#91;3]
1b000 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20 20 20   = "43";.**     
1b010 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
1b020 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 20  4] = "Bob";.**  
1b030 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
1b040 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a  91;5] = "28";.**
1b050 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
1b060 26 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e 64 79  &#91;6] = "Cindy
1b070 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
1b080 65 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d 20 22  esult&#91;7] = "
1b090 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  21";.** </pre></
1b0a0 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a  blockquote>)^.**
1b0b0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1b0c0 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 66 75 6e  _get_table() fun
1b0d0 63 74 69 6f 6e 20 65 76 61 6c 75 61 74 65 73 20  ction evaluates 
1b0e0 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73  one or more.** s
1b0f0 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74  emicolon-separat
1b100 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ed SQL statement
1b110 73 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74 65  s in the zero-te
1b120 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a  rminated UTF-8.*
1b130 2a 20 73 74 72 69 6e 67 20 6f 66 20 69 74 73 20  * string of its 
1b140 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e  2nd parameter an
1b150 64 20 72 65 74 75 72 6e 73 20 61 20 72 65 73 75  d returns a resu
1b160 6c 74 20 74 61 62 6c 65 20 74 6f 20 74 68 65 0a  lt table to the.
1b170 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69 76 65 6e  ** pointer given
1b180 20 69 6e 20 69 74 73 20 33 72 64 20 70 61 72 61   in its 3rd para
1b190 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74  meter..**.** Aft
1b1a0 65 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  er the applicati
1b1b0 6f 6e 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  on has finished 
1b1c0 77 69 74 68 20 74 68 65 20 72 65 73 75 6c 74 20  with the result 
1b1d0 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 67 65 74  from sqlite3_get
1b1e0 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a 20 69 74 20  _table(),.** it 
1b1f0 6d 75 73 74 20 70 61 73 73 20 74 68 65 20 72 65  must pass the re
1b200 73 75 6c 74 20 74 61 62 6c 65 20 70 6f 69 6e 74  sult table point
1b210 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72  er to sqlite3_fr
1b220 65 65 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f 72  ee_table() in or
1b230 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c 65 61 73  der to.** releas
1b240 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 68 61  e the memory tha
1b250 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64 2e 20  t was malloced. 
1b260 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20   Because of the 
1b270 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  way the.** [sqli
1b280 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 61  te3_malloc()] ha
1b290 70 70 65 6e 73 20 77 69 74 68 69 6e 20 73 71 6c  ppens within sql
1b2a0 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
1b2b0 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a  , the calling.**
1b2c0 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e   function must n
1b2d0 6f 74 20 74 72 79 20 74 6f 20 63 61 6c 6c 20 5b  ot try to call [
1b2e0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
1b2f0 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a  directly.  Only.
1b300 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ** [sqlite3_free
1b310 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 61 62 6c  _table()] is abl
1b320 65 20 74 6f 20 72 65 6c 65 61 73 65 20 74 68 65  e to release the
1b330 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c 79   memory properly
1b340 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a   and safely..**.
1b350 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67  ** The sqlite3_g
1b360 65 74 5f 74 61 62 6c 65 28 29 20 69 6e 74 65 72  et_table() inter
1b370 66 61 63 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e  face is implemen
1b380 74 65 64 20 61 73 20 61 20 77 72 61 70 70 65 72  ted as a wrapper
1b390 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69   around.** [sqli
1b3a0 74 65 33 5f 65 78 65 63 28 29 5d 2e 20 20 54 68  te3_exec()].  Th
1b3b0 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  e sqlite3_get_ta
1b3c0 62 6c 65 28 29 20 72 6f 75 74 69 6e 65 20 64 6f  ble() routine do
1b3d0 65 73 20 6e 6f 74 20 68 61 76 65 20 61 63 63 65  es not have acce
1b3e0 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69 6e 74  ss.** to any int
1b3f0 65 72 6e 61 6c 20 64 61 74 61 20 73 74 72 75 63  ernal data struc
1b400 74 75 72 65 73 20 6f 66 20 53 51 4c 69 74 65 2e  tures of SQLite.
1b410 20 20 49 74 20 75 73 65 73 20 6f 6e 6c 79 20 74    It uses only t
1b420 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69 6e 74  he public.** int
1b430 65 72 66 61 63 65 20 64 65 66 69 6e 65 64 20 68  erface defined h
1b440 65 72 65 2e 20 20 41 73 20 61 20 63 6f 6e 73 65  ere.  As a conse
1b450 71 75 65 6e 63 65 2c 20 65 72 72 6f 72 73 20 74  quence, errors t
1b460 68 61 74 20 6f 63 63 75 72 20 69 6e 20 74 68 65  hat occur in the
1b470 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c 61 79 65  .** wrapper laye
1b480 72 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65  r outside of the
1b490 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c 69 74   internal [sqlit
1b4a0 65 33 5f 65 78 65 63 28 29 5d 20 63 61 6c 6c 20  e3_exec()] call 
1b4b0 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65  are not.** refle
1b4c0 63 74 65 64 20 69 6e 20 73 75 62 73 65 71 75 65  cted in subseque
1b4d0 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  nt calls to [sql
1b4e0 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20  ite3_errcode()] 
1b4f0 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  or.** [sqlite3_e
1b500 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a 53 51 4c  rrmsg()]..*/.SQL
1b510 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
1b520 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20  te3_get_table(. 
1b530 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
1b540 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65         /* An ope
1b550 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20  n database */.  
1b560 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c  const char *zSql
1b570 2c 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20  ,     /* SQL to 
1b580 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a  be evaluated */.
1b590 20 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52 65 73    char ***pazRes
1b5a0 75 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73 75 6c  ult,    /* Resul
1b5b0 74 73 20 6f 66 20 74 68 65 20 71 75 65 72 79 20  ts of the query 
1b5c0 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f 77 2c  */.  int *pnRow,
1b5d0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75             /* Nu
1b5e0 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 72  mber of result r
1b5f0 6f 77 73 20 77 72 69 74 74 65 6e 20 68 65 72 65  ows written here
1b600 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43 6f 6c   */.  int *pnCol
1b610 75 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a 20 4e  umn,        /* N
1b620 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20  umber of result 
1b630 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e 20  columns written 
1b640 68 65 72 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a  here */.  char *
1b650 2a 70 7a 45 72 72 6d 73 67 20 20 20 20 20 20 20  *pzErrmsg       
1b660 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69  /* Error msg wri
1b670 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a  tten here */.);.
1b680 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
1b690 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62  sqlite3_free_tab
1b6a0 6c 65 28 63 68 61 72 20 2a 2a 72 65 73 75 6c 74  le(char **result
1b6b0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1b6c0 45 46 3a 20 46 6f 72 6d 61 74 74 65 64 20 53 74  EF: Formatted St
1b6d0 72 69 6e 67 20 50 72 69 6e 74 69 6e 67 20 46 75  ring Printing Fu
1b6e0 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68  nctions.**.** Th
1b6f0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
1b700 20 77 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f 66 20   work-alikes of 
1b710 74 68 65 20 22 70 72 69 6e 74 66 28 29 22 20 66  the "printf()" f
1b720 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f  amily of functio
1b730 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73  ns.** from the s
1b740 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72  tandard C librar
1b750 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  y..**.** ^The sq
1b760 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20  lite3_mprintf() 
1b770 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 6d 70 72  and sqlite3_vmpr
1b780 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 73 20  intf() routines 
1b790 77 72 69 74 65 20 74 68 65 69 72 0a 2a 2a 20 72  write their.** r
1b7a0 65 73 75 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f  esults into memo
1b7b0 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ry obtained from
1b7c0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
1b7d0 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72 69  ()]..** The stri
1b7e0 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ngs returned by 
1b7f0 74 68 65 73 65 20 74 77 6f 20 72 6f 75 74 69 6e  these two routin
1b800 65 73 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20  es should be.** 
1b810 72 65 6c 65 61 73 65 64 20 62 79 20 5b 73 71 6c  released by [sql
1b820 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 20 20 5e  ite3_free()].  ^
1b830 42 6f 74 68 20 72 6f 75 74 69 6e 65 73 20 72 65  Both routines re
1b840 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70  turn a.** NULL p
1b850 6f 69 6e 74 65 72 20 69 66 20 5b 73 71 6c 69 74  ointer if [sqlit
1b860 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 73 20  e3_malloc()] is 
1b870 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61  unable to alloca
1b880 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d  te enough.** mem
1b890 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20  ory to hold the 
1b8a0 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67  resulting string
1b8b0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71  ..**.** ^(The sq
1b8c0 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
1b8d0 20 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69   routine is simi
1b8e0 6c 61 72 20 74 6f 20 22 73 6e 70 72 69 6e 74 66  lar to "snprintf
1b8f0 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20  ()" from.** the 
1b900 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61  standard C libra
1b910 72 79 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20  ry.  The result 
1b920 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  is written into 
1b930 74 68 65 0a 2a 2a 20 62 75 66 66 65 72 20 73 75  the.** buffer su
1b940 70 70 6c 69 65 64 20 61 73 20 74 68 65 20 73 65  pplied as the se
1b950 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 77  cond parameter w
1b960 68 6f 73 65 20 73 69 7a 65 20 69 73 20 67 69 76  hose size is giv
1b970 65 6e 20 62 79 0a 2a 2a 20 74 68 65 20 66 69 72  en by.** the fir
1b980 73 74 20 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f  st parameter. No
1b990 74 65 20 74 68 61 74 20 74 68 65 20 6f 72 64 65  te that the orde
1b9a0 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72 73  r of the.** firs
1b9b0 74 20 74 77 6f 20 70 61 72 61 6d 65 74 65 72 73  t two parameters
1b9c0 20 69 73 20 72 65 76 65 72 73 65 64 20 66 72 6f   is reversed fro
1b9d0 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e 29 5e 20  m snprintf().)^ 
1b9e0 20 54 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68   This is an.** h
1b9f0 69 73 74 6f 72 69 63 61 6c 20 61 63 63 69 64 65  istorical accide
1ba00 6e 74 20 74 68 61 74 20 63 61 6e 6e 6f 74 20 62  nt that cannot b
1ba10 65 20 66 69 78 65 64 20 77 69 74 68 6f 75 74 20  e fixed without 
1ba20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b  breaking.** back
1ba30 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c  wards compatibil
1ba40 69 74 79 2e 20 20 5e 28 4e 6f 74 65 20 61 6c 73  ity.  ^(Note als
1ba50 6f 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f 73  o that sqlite3_s
1ba60 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74  nprintf().** ret
1ba70 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
1ba80 6f 20 69 74 73 20 62 75 66 66 65 72 20 69 6e 73  o its buffer ins
1ba90 74 65 61 64 20 6f 66 20 74 68 65 20 6e 75 6d 62  tead of the numb
1baa0 65 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74  er of.** charact
1bab0 65 72 73 20 61 63 74 75 61 6c 6c 79 20 77 72 69  ers actually wri
1bac0 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 62 75  tten into the bu
1bad0 66 66 65 72 2e 29 5e 20 20 57 65 20 61 64 6d 69  ffer.)^  We admi
1bae0 74 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75  t that.** the nu
1baf0 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65  mber of characte
1bb00 72 73 20 77 72 69 74 74 65 6e 20 77 6f 75 6c 64  rs written would
1bb10 20 62 65 20 61 20 6d 6f 72 65 20 75 73 65 66 75   be a more usefu
1bb20 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75  l return.** valu
1bb30 65 20 62 75 74 20 77 65 20 63 61 6e 6e 6f 74 20  e but we cannot 
1bb40 63 68 61 6e 67 65 20 74 68 65 20 69 6d 70 6c 65  change the imple
1bb50 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c  mentation of sql
1bb60 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a  ite3_snprintf().
1bb70 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74 20 62  ** now without b
1bb80 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62  reaking compatib
1bb90 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73  ility..**.** ^As
1bba0 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 62 75 66   long as the buf
1bbb0 66 65 72 20 73 69 7a 65 20 69 73 20 67 72 65 61  fer size is grea
1bbc0 74 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73  ter than zero, s
1bbd0 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
1bbe0 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 73 20  ).** guarantees 
1bbf0 74 68 61 74 20 74 68 65 20 62 75 66 66 65 72 20  that the buffer 
1bc00 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74  is always zero-t
1bc10 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65  erminated.  ^The
1bc20 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65   first.** parame
1bc30 74 65 72 20 22 6e 22 20 69 73 20 74 68 65 20 74  ter "n" is the t
1bc40 6f 74 61 6c 20 73 69 7a 65 20 6f 66 20 74 68 65  otal size of the
1bc50 20 62 75 66 66 65 72 2c 20 69 6e 63 6c 75 64 69   buffer, includi
1bc60 6e 67 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20  ng space for.** 
1bc70 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  the zero termina
1bc80 74 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e  tor.  So the lon
1bc90 67 65 73 74 20 73 74 72 69 6e 67 20 74 68 61 74  gest string that
1bca0 20 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65   can be complete
1bcb0 6c 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77 69  ly.** written wi
1bcc0 6c 6c 20 62 65 20 6e 2d 31 20 63 68 61 72 61 63  ll be n-1 charac
1bcd0 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ters..**.** ^The
1bce0 20 73 71 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e   sqlite3_vsnprin
1bcf0 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20  tf() routine is 
1bd00 61 20 76 61 72 61 72 67 73 20 76 65 72 73 69 6f  a varargs versio
1bd10 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70  n of sqlite3_snp
1bd20 72 69 6e 74 66 28 29 2e 0a 2a 2a 0a 2a 2a 20 54  rintf()..**.** T
1bd30 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 6c  hese routines al
1bd40 6c 20 69 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d 65  l implement some
1bd50 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 6f 72 6d   additional form
1bd60 61 74 74 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e  atting.** option
1bd70 73 20 74 68 61 74 20 61 72 65 20 75 73 65 66 75  s that are usefu
1bd80 6c 20 66 6f 72 20 63 6f 6e 73 74 72 75 63 74 69  l for constructi
1bd90 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ng SQL statement
1bda0 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74 68 65  s..** All of the
1bdb0 20 75 73 75 61 6c 20 70 72 69 6e 74 66 28 29 20   usual printf() 
1bdc0 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f  formatting optio
1bdd0 6e 73 20 61 70 70 6c 79 2e 20 20 49 6e 20 61 64  ns apply.  In ad
1bde0 64 69 74 69 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a  dition, there.**
1bdf0 20 69 73 20 61 72 65 20 22 25 71 22 2c 20 22 25   is are "%q", "%
1be00 51 22 2c 20 61 6e 64 20 22 25 7a 22 20 6f 70 74  Q", and "%z" opt
1be10 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  ions..**.** ^(Th
1be20 65 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72 6b  e %q option work
1be30 73 20 6c 69 6b 65 20 25 73 20 69 6e 20 74 68 61  s like %s in tha
1be40 74 20 69 74 20 73 75 62 73 74 69 74 75 74 65 73  t it substitutes
1be50 20 61 20 6e 75 6c 6c 2d 74 65 72 6d 69 6e 61 74   a null-terminat
1be60 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f  ed.** string fro
1be70 6d 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 6c  m the argument l
1be80 69 73 74 2e 20 20 42 75 74 20 25 71 20 61 6c 73  ist.  But %q als
1be90 6f 20 64 6f 75 62 6c 65 73 20 65 76 65 72 79 20  o doubles every 
1bea0 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 2e 0a  '\'' character..
1beb0 2a 2a 20 25 71 20 69 73 20 64 65 73 69 67 6e 65  ** %q is designe
1bec0 64 20 66 6f 72 20 75 73 65 20 69 6e 73 69 64 65  d for use inside
1bed0 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61   a string litera
1bee0 6c 2e 29 5e 20 20 42 79 20 64 6f 75 62 6c 69 6e  l.)^  By doublin
1bef0 67 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63  g each '\''.** c
1bf00 68 61 72 61 63 74 65 72 20 69 74 20 65 73 63 61  haracter it esca
1bf10 70 65 73 20 74 68 61 74 20 63 68 61 72 61 63 74  pes that charact
1bf20 65 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74  er and allows it
1bf30 20 74 6f 20 62 65 20 69 6e 73 65 72 74 65 64 20   to be inserted 
1bf40 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69  into.** the stri
1bf50 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78  ng..**.** For ex
1bf60 61 6d 70 6c 65 2c 20 61 73 73 75 6d 65 20 74 68  ample, assume th
1bf70 65 20 73 74 72 69 6e 67 20 76 61 72 69 61 62 6c  e string variabl
1bf80 65 20 7a 54 65 78 74 20 63 6f 6e 74 61 69 6e 73  e zText contains
1bf90 20 74 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73   text as follows
1bfa0 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
1bfb0 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68  ote><pre>.**  ch
1bfc0 61 72 20 2a 7a 54 65 78 74 20 3d 20 22 49 74 27  ar *zText = "It'
1bfd0 73 20 61 20 68 61 70 70 79 20 64 61 79 21 22 3b  s a happy day!";
1bfe0 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
1bff0 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e  kquote>.**.** On
1c000 65 20 63 61 6e 20 75 73 65 20 74 68 69 73 20 74  e can use this t
1c010 65 78 74 20 69 6e 20 61 6e 20 53 51 4c 20 73 74  ext in an SQL st
1c020 61 74 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f  atement as follo
1c030 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
1c040 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
1c050 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c  char *zSQL = sql
1c060 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e  ite3_mprintf("IN
1c070 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20  SERT INTO table 
1c080 56 41 4c 55 45 53 28 27 25 71 27 29 22 2c 20 7a  VALUES('%q')", z
1c090 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74  Text);.**  sqlit
1c0a0 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c  e3_exec(db, zSQL
1c0b0 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20  , 0, 0, 0);.**  
1c0c0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51  sqlite3_free(zSQ
1c0d0 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  L);.** </pre></b
1c0e0 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
1c0f0 20 42 65 63 61 75 73 65 20 74 68 65 20 25 71 20   Because the %q 
1c100 66 6f 72 6d 61 74 20 73 74 72 69 6e 67 20 69 73  format string is
1c110 20 75 73 65 64 2c 20 74 68 65 20 27 5c 27 27 20   used, the '\'' 
1c120 63 68 61 72 61 63 74 65 72 20 69 6e 20 7a 54 65  character in zTe
1c130 78 74 0a 2a 2a 20 69 73 20 65 73 63 61 70 65 64  xt.** is escaped
1c140 20 61 6e 64 20 74 68 65 20 53 51 4c 20 67 65 6e   and the SQL gen
1c150 65 72 61 74 65 64 20 69 73 20 61 73 20 66 6f 6c  erated is as fol
1c160 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lows:.**.** <blo
1c170 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
1c180 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61    INSERT INTO ta
1c190 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 27  ble1 VALUES('It'
1c1a0 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27  's a happy day!'
1c1b0 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ).** </pre></blo
1c1c0 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54  ckquote>.**.** T
1c1d0 68 69 73 20 69 73 20 63 6f 72 72 65 63 74 2e 20  his is correct. 
1c1e0 20 48 61 64 20 77 65 20 75 73 65 64 20 25 73 20   Had we used %s 
1c1f0 69 6e 73 74 65 61 64 20 6f 66 20 25 71 2c 20 74  instead of %q, t
1c200 68 65 20 67 65 6e 65 72 61 74 65 64 20 53 51 4c  he generated SQL
1c210 0a 2a 2a 20 77 6f 75 6c 64 20 68 61 76 65 20 6c  .** would have l
1c220 6f 6f 6b 65 64 20 6c 69 6b 65 20 74 68 69 73 3a  ooked like this:
1c230 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
1c240 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53  te><pre>.**  INS
1c250 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20  ERT INTO table1 
1c260 56 41 4c 55 45 53 28 27 49 74 27 73 20 61 20 68  VALUES('It's a h
1c270 61 70 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20  appy day!');.** 
1c280 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
1c290 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73  te>.**.** This s
1c2a0 65 63 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69 73  econd example is
1c2b0 20 61 6e 20 53 51 4c 20 73 79 6e 74 61 78 20 65   an SQL syntax e
1c2c0 72 72 6f 72 2e 20 20 41 73 20 61 20 67 65 6e 65  rror.  As a gene
1c2d0 72 61 6c 20 72 75 6c 65 20 79 6f 75 20 73 68 6f  ral rule you sho
1c2e0 75 6c 64 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73  uld.** always us
1c2f0 65 20 25 71 20 69 6e 73 74 65 61 64 20 6f 66 20  e %q instead of 
1c300 25 73 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e  %s when insertin
1c310 67 20 74 65 78 74 20 69 6e 74 6f 20 61 20 73 74  g text into a st
1c320 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a  ring literal..**
1c330 0a 2a 2a 20 5e 28 54 68 65 20 25 51 20 6f 70 74  .** ^(The %Q opt
1c340 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25  ion works like %
1c350 71 20 65 78 63 65 70 74 20 69 74 20 61 6c 73 6f  q except it also
1c360 20 61 64 64 73 20 73 69 6e 67 6c 65 20 71 75 6f   adds single quo
1c370 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68  tes around.** th
1c380 65 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65  e outside of the
1c390 20 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e 20 20   total string.  
1c3a0 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 69 66  Additionally, if
1c3b0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69   the parameter i
1c3c0 6e 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e  n the.** argumen
1c3d0 74 20 6c 69 73 74 20 69 73 20 61 20 4e 55 4c 4c  t list is a NULL
1c3e0 20 70 6f 69 6e 74 65 72 2c 20 25 51 20 73 75 62   pointer, %Q sub
1c3f0 73 74 69 74 75 74 65 73 20 74 68 65 20 74 65 78  stitutes the tex
1c400 74 20 22 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75  t "NULL" (withou
1c410 74 0a 2a 2a 20 73 69 6e 67 6c 65 20 71 75 6f 74  t.** single quot
1c420 65 73 29 2e 29 5e 20 20 53 6f 2c 20 66 6f 72 20  es).)^  So, for 
1c430 65 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75  example, one cou
1c440 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ld say:.**.** <b
1c450 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
1c460 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d  **  char *zSQL =
1c470 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66   sqlite3_mprintf
1c480 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61  ("INSERT INTO ta
1c490 62 6c 65 20 56 41 4c 55 45 53 28 25 51 29 22 2c  ble VALUES(%Q)",
1c4a0 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c   zText);.**  sql
1c4b0 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53  ite3_exec(db, zS
1c4c0 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a  QL, 0, 0, 0);.**
1c4d0 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a    sqlite3_free(z
1c4e0 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  SQL);.** </pre><
1c4f0 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
1c500 2a 2a 20 54 68 65 20 63 6f 64 65 20 61 62 6f 76  ** The code abov
1c510 65 20 77 69 6c 6c 20 72 65 6e 64 65 72 20 61 20  e will render a 
1c520 63 6f 72 72 65 63 74 20 53 51 4c 20 73 74 61 74  correct SQL stat
1c530 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 7a 53 51  ement in the zSQ
1c540 4c 0a 2a 2a 20 76 61 72 69 61 62 6c 65 20 65 76  L.** variable ev
1c550 65 6e 20 69 66 20 74 68 65 20 7a 54 65 78 74 20  en if the zText 
1c560 76 61 72 69 61 62 6c 65 20 69 73 20 61 20 4e 55  variable is a NU
1c570 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
1c580 2a 20 5e 28 54 68 65 20 22 25 7a 22 20 66 6f 72  * ^(The "%z" for
1c590 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 77  matting option w
1c5a0 6f 72 6b 73 20 6c 69 6b 65 20 22 25 73 22 20 62  orks like "%s" b
1c5b0 75 74 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 61  ut with the.** a
1c5c0 64 64 69 74 69 6f 6e 20 74 68 61 74 20 61 66 74  ddition that aft
1c5d0 65 72 20 74 68 65 20 73 74 72 69 6e 67 20 68 61  er the string ha
1c5e0 73 20 62 65 65 6e 20 72 65 61 64 20 61 6e 64 20  s been read and 
1c5f0 63 6f 70 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74  copied into.** t
1c600 68 65 20 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69  he result, [sqli
1c610 74 65 33 5f 66 72 65 65 28 29 5d 20 69 73 20 63  te3_free()] is c
1c620 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 69 6e 70  alled on the inp
1c630 75 74 20 73 74 72 69 6e 67 2e 29 5e 0a 2a 2f 0a  ut string.)^.*/.
1c640 53 51 4c 49 54 45 5f 41 50 49 20 63 68 61 72 20  SQLITE_API char 
1c650 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66  *sqlite3_mprintf
1c660 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e  (const char*,...
1c670 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 68  );.SQLITE_API ch
1c680 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 6d 70 72  ar *sqlite3_vmpr
1c690 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a  intf(const char*
1c6a0 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 53 51 4c 49  , va_list);.SQLI
1c6b0 54 45 5f 41 50 49 20 63 68 61 72 20 2a 73 71 6c  TE_API char *sql
1c6c0 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 69 6e  ite3_snprintf(in
1c6d0 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68  t,char*,const ch
1c6e0 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 53 51 4c 49 54  ar*, ...);.SQLIT
1c6f0 45 5f 41 50 49 20 63 68 61 72 20 2a 73 71 6c 69  E_API char *sqli
1c700 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 69 6e  te3_vsnprintf(in
1c710 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68  t,char*,const ch
1c720 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 0a  ar*, va_list);..
1c730 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1c740 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f  Memory Allocatio
1c750 6e 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a  n Subsystem.**.*
1c760 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72  * The SQLite cor
1c770 65 20 75 73 65 73 20 74 68 65 73 65 20 74 68 72  e uses these thr
1c780 65 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20  ee routines for 
1c790 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a  all of its own.*
1c7a0 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72  * internal memor
1c7b0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65  y allocation nee
1c7c0 64 73 2e 20 22 43 6f 72 65 22 20 69 6e 20 74 68  ds. "Core" in th
1c7d0 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65  e previous sente
1c7e0 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20  nce.** does not 
1c7f0 69 6e 63 6c 75 64 65 20 6f 70 65 72 61 74 69 6e  include operatin
1c800 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 69  g-system specifi
1c810 63 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  c VFS implementa
1c820 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69  tion.  The.** Wi
1c830 6e 64 6f 77 73 20 56 46 53 20 75 73 65 73 20 6e  ndows VFS uses n
1c840 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61  ative malloc() a
1c850 6e 64 20 66 72 65 65 28 29 20 66 6f 72 20 73 6f  nd free() for so
1c860 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a  me operations..*
1c870 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1c880 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69  3_malloc() routi
1c890 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ne returns a poi
1c8a0 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a  nter to a block.
1c8b0 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20  ** of memory at 
1c8c0 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e  least N bytes in
1c8d0 20 6c 65 6e 67 74 68 2c 20 77 68 65 72 65 20 4e   length, where N
1c8e0 20 69 73 20 74 68 65 20 70 61 72 61 6d 65 74 65   is the paramete
1c8f0 72 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65  r..** ^If sqlite
1c900 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e  3_malloc() is un
1c910 61 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20 73  able to obtain s
1c920 75 66 66 69 63 69 65 6e 74 20 66 72 65 65 0a 2a  ufficient free.*
1c930 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65 74  * memory, it ret
1c940 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  urns a NULL poin
1c950 74 65 72 2e 20 20 5e 49 66 20 74 68 65 20 70 61  ter.  ^If the pa
1c960 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20  rameter N to.** 
1c970 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1c980 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61   is zero or nega
1c990 74 69 76 65 20 74 68 65 6e 20 73 71 6c 69 74 65  tive then sqlite
1c9a0 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75 72  3_malloc() retur
1c9b0 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69  ns.** a NULL poi
1c9c0 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c  nter..**.** ^Cal
1c9d0 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65  ling sqlite3_fre
1c9e0 65 28 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74  e() with a point
1c9f0 65 72 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65  er previously re
1ca00 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c  turned.** by sql
1ca10 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72  ite3_malloc() or
1ca20 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1ca30 28 29 20 72 65 6c 65 61 73 65 73 20 74 68 61 74  () releases that
1ca40 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68   memory so.** th
1ca50 61 74 20 69 74 20 6d 69 67 68 74 20 62 65 20 72  at it might be r
1ca60 65 75 73 65 64 2e 20 20 5e 54 68 65 20 73 71 6c  eused.  ^The sql
1ca70 69 74 65 33 5f 66 72 65 65 28 29 20 72 6f 75 74  ite3_free() rout
1ca80 69 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f  ine is.** a no-o
1ca90 70 20 69 66 20 69 73 20 63 61 6c 6c 65 64 20 77  p if is called w
1caa0 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  ith a NULL point
1cab0 65 72 2e 20 20 50 61 73 73 69 6e 67 20 61 20 4e  er.  Passing a N
1cac0 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74  ULL pointer.** t
1cad0 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  o sqlite3_free()
1cae0 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 20 20 41   is harmless.  A
1caf0 66 74 65 72 20 62 65 69 6e 67 20 66 72 65 65 64  fter being freed
1cb00 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75  , memory.** shou
1cb10 6c 64 20 6e 65 69 74 68 65 72 20 62 65 20 72 65  ld neither be re
1cb20 61 64 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20  ad nor written. 
1cb30 20 45 76 65 6e 20 72 65 61 64 69 6e 67 20 70 72   Even reading pr
1cb40 65 76 69 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a  eviously freed.*
1cb50 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20 72  * memory might r
1cb60 65 73 75 6c 74 20 69 6e 20 61 20 73 65 67 6d 65  esult in a segme
1cb70 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72  ntation fault or
1cb80 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72   other severe er
1cb90 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63  ror..** Memory c
1cba0 6f 72 72 75 70 74 69 6f 6e 2c 20 61 20 73 65 67  orruption, a seg
1cbb0 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c  mentation fault,
1cbc0 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 65   or other severe
1cbd0 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20   error.** might 
1cbe0 72 65 73 75 6c 74 20 69 66 20 73 71 6c 69 74 65  result if sqlite
1cbf0 33 5f 66 72 65 65 28 29 20 69 73 20 63 61 6c 6c  3_free() is call
1cc00 65 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55  ed with a non-NU
1cc10 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 61 74 0a  LL pointer that.
1cc20 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74 61 69  ** was not obtai
1cc30 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ned from sqlite3
1cc40 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c  _malloc() or sql
1cc50 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a  ite3_realloc()..
1cc60 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69  **.** ^(The sqli
1cc70 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 6e  te3_realloc() in
1cc80 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73  terface attempts
1cc90 20 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20   to resize a.** 
1cca0 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c  prior memory all
1ccb0 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 61 74  ocation to be at
1ccc0 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 2c 20   least N bytes, 
1ccd0 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a  where N is the.*
1cce0 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  * second paramet
1ccf0 65 72 2e 20 20 54 68 65 20 6d 65 6d 6f 72 79 20  er.  The memory 
1cd00 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65  allocation to be
1cd10 20 72 65 73 69 7a 65 64 20 69 73 20 74 68 65 20   resized is the 
1cd20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74  first.** paramet
1cd30 65 72 2e 29 5e 20 5e 20 49 66 20 74 68 65 20 66  er.)^ ^ If the f
1cd40 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
1cd50 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  o sqlite3_reallo
1cd60 63 28 29 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c  c().** is a NULL
1cd70 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 69 74   pointer then it
1cd80 73 20 62 65 68 61 76 69 6f 72 20 69 73 20 69 64  s behavior is id
1cd90 65 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69  entical to calli
1cda0 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61  ng.** sqlite3_ma
1cdb0 6c 6c 6f 63 28 4e 29 20 77 68 65 72 65 20 4e 20  lloc(N) where N 
1cdc0 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  is the second pa
1cdd0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
1cde0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a  e3_realloc()..**
1cdf0 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20   ^If the second 
1ce00 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
1ce10 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69  ite3_realloc() i
1ce20 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67  s zero or.** neg
1ce30 61 74 69 76 65 20 74 68 65 6e 20 74 68 65 20 62  ative then the b
1ce40 65 68 61 76 69 6f 72 20 69 73 20 65 78 61 63 74  ehavior is exact
1ce50 6c 79 20 74 68 65 20 73 61 6d 65 20 61 73 20 63  ly the same as c
1ce60 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65  alling.** sqlite
1ce70 33 5f 66 72 65 65 28 50 29 20 77 68 65 72 65 20  3_free(P) where 
1ce80 50 20 69 73 20 74 68 65 20 66 69 72 73 74 20 70  P is the first p
1ce90 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
1cea0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a  te3_realloc()..*
1ceb0 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  * ^sqlite3_reall
1cec0 6f 63 28 29 20 72 65 74 75 72 6e 73 20 61 20 70  oc() returns a p
1ced0 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f  ointer to a memo
1cee0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a  ry allocation.**
1cef0 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62   of at least N b
1cf00 79 74 65 73 20 69 6e 20 73 69 7a 65 20 6f 72 20  ytes in size or 
1cf10 4e 55 4c 4c 20 69 66 20 73 75 66 66 69 63 69 65  NULL if sufficie
1cf20 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20 75 6e 61  nt memory is una
1cf30 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66  vailable..** ^If
1cf40 20 4d 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f   M is the size o
1cf50 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f  f the prior allo
1cf60 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e  cation, then min
1cf70 28 4e 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f  (N,M) bytes.** o
1cf80 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f  f the prior allo
1cf90 63 61 74 69 6f 6e 20 61 72 65 20 63 6f 70 69 65  cation are copie
1cfa0 64 20 69 6e 74 6f 20 74 68 65 20 62 65 67 69 6e  d into the begin
1cfb0 6e 69 6e 67 20 6f 66 20 62 75 66 66 65 72 20 72  ning of buffer r
1cfc0 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71  eturned.** by sq
1cfd0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20  lite3_realloc() 
1cfe0 61 6e 64 20 74 68 65 20 70 72 69 6f 72 20 61 6c  and the prior al
1cff0 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65  location is free
1d000 64 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65  d..** ^If sqlite
1d010 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75  3_realloc() retu
1d020 72 6e 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74  rns NULL, then t
1d030 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  he prior allocat
1d040 69 6f 6e 0a 2a 2a 20 69 73 20 6e 6f 74 20 66 72  ion.** is not fr
1d050 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  eed..**.** ^The 
1d060 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e 65 64 20  memory returned 
1d070 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  by sqlite3_mallo
1d080 63 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  c() and sqlite3_
1d090 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20  realloc().** is 
1d0a0 61 6c 77 61 79 73 20 61 6c 69 67 6e 65 64 20 74  always aligned t
1d0b0 6f 20 61 74 20 6c 65 61 73 74 20 61 6e 20 38 20  o at least an 8 
1d0c0 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2c 20 6f  byte boundary, o
1d0d0 72 20 74 6f 20 61 0a 2a 2a 20 34 20 62 79 74 65  r to a.** 4 byte
1d0e0 20 62 6f 75 6e 64 61 72 79 20 69 66 20 74 68 65   boundary if the
1d0f0 20 5b 53 51 4c 49 54 45 5f 34 5f 42 59 54 45 5f   [SQLITE_4_BYTE_
1d100 41 4c 49 47 4e 45 44 5f 4d 41 4c 4c 4f 43 5d 20  ALIGNED_MALLOC] 
1d110 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20  compile-time.** 
1d120 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a  option is used..
1d130 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20  **.** In SQLite 
1d140 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e  version 3.5.0 an
1d150 64 20 33 2e 35 2e 31 2c 20 69 74 20 77 61 73 20  d 3.5.1, it was 
1d160 70 6f 73 73 69 62 6c 65 20 74 6f 20 64 65 66 69  possible to defi
1d170 6e 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49 54 45  ne.** the SQLITE
1d180 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c  _OMIT_MEMORY_ALL
1d190 4f 43 41 54 49 4f 4e 20 77 68 69 63 68 20 77 6f  OCATION which wo
1d1a0 75 6c 64 20 63 61 75 73 65 20 74 68 65 20 62 75  uld cause the bu
1d1b0 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d  ilt-in.** implem
1d1c0 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 73  entation of thes
1d1d0 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65  e routines to be
1d1e0 20 6f 6d 69 74 74 65 64 2e 20 20 54 68 61 74 20   omitted.  That 
1d1f0 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73  capability.** is
1d200 20 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69   no longer provi
1d210 64 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74  ded.  Only built
1d220 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  -in memory alloc
1d230 61 74 6f 72 73 20 63 61 6e 20 62 65 20 75 73 65  ators can be use
1d240 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 57 69 6e  d..**.** The Win
1d250 64 6f 77 73 20 4f 53 20 69 6e 74 65 72 66 61 63  dows OS interfac
1d260 65 20 6c 61 79 65 72 20 63 61 6c 6c 73 0a 2a 2a  e layer calls.**
1d270 20 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c   the system mall
1d280 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20  oc() and free() 
1d290 64 69 72 65 63 74 6c 79 20 77 68 65 6e 20 63 6f  directly when co
1d2a0 6e 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65  nverting.** file
1d2b0 6e 61 6d 65 73 20 62 65 74 77 65 65 6e 20 74 68  names between th
1d2c0 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67  e UTF-8 encoding
1d2d0 20 75 73 65 64 20 62 79 20 53 51 4c 69 74 65 0a   used by SQLite.
1d2e0 2a 2a 20 61 6e 64 20 77 68 61 74 65 76 65 72 20  ** and whatever 
1d2f0 66 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e  filename encodin
1d300 67 20 69 73 20 75 73 65 64 20 62 79 20 74 68 65  g is used by the
1d310 20 70 61 72 74 69 63 75 6c 61 72 20 57 69 6e 64   particular Wind
1d320 6f 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74  ows.** installat
1d330 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c  ion.  Memory all
1d340 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 73 20 61  ocation errors a
1d350 72 65 20 64 65 74 65 63 74 65 64 2c 20 62 75 74  re detected, but
1d360 0a 2a 2a 20 74 68 65 79 20 61 72 65 20 72 65 70  .** they are rep
1d370 6f 72 74 65 64 20 62 61 63 6b 20 61 73 20 5b 53  orted back as [S
1d380 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20  QLITE_CANTOPEN] 
1d390 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f  or.** [SQLITE_IO
1d3a0 45 52 52 5d 20 72 61 74 68 65 72 20 74 68 61 6e  ERR] rather than
1d3b0 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e   [SQLITE_NOMEM].
1d3c0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74  .**.** The point
1d3d0 65 72 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  er arguments to 
1d3e0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
1d3f0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65   and [sqlite3_re
1d400 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73 74  alloc()].** must
1d410 20 62 65 20 65 69 74 68 65 72 20 4e 55 4c 4c 20   be either NULL 
1d420 6f 72 20 65 6c 73 65 20 70 6f 69 6e 74 65 72 73  or else pointers
1d430 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61   obtained from a
1d440 20 70 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61   prior.** invoca
1d450 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33  tion of [sqlite3
1d460 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73  _malloc()] or [s
1d470 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1d480 5d 20 74 68 61 74 20 68 61 76 65 0a 2a 2a 20 6e  ] that have.** n
1d490 6f 74 20 79 65 74 20 62 65 65 6e 20 72 65 6c 65  ot yet been rele
1d4a0 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ased..**.** The 
1d4b0 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
1d4c0 20 6e 6f 74 20 72 65 61 64 20 6f 72 20 77 72 69   not read or wri
1d4d0 74 65 20 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a  te any part of.*
1d4e0 2a 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d  * a block of mem
1d4f0 6f 72 79 20 61 66 74 65 72 20 69 74 20 68 61 73  ory after it has
1d500 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64 20 75   been released u
1d510 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
1d520 5f 66 72 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c  _free()] or [sql
1d530 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e  ite3_realloc()].
1d540 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  .*/.SQLITE_API v
1d550 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c  oid *sqlite3_mal
1d560 6c 6f 63 28 69 6e 74 29 3b 0a 53 51 4c 49 54 45  loc(int);.SQLITE
1d570 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74  _API void *sqlit
1d580 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64 2a  e3_realloc(void*
1d590 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41  , int);.SQLITE_A
1d5a0 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  PI void sqlite3_
1d5b0 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a  free(void*);../*
1d5c0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65  .** CAPI3REF: Me
1d5d0 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53  mory Allocator S
1d5e0 74 61 74 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20  tatistics.**.** 
1d5f0 53 51 4c 69 74 65 20 70 72 6f 76 69 64 65 73 20  SQLite provides 
1d600 74 68 65 73 65 20 74 77 6f 20 69 6e 74 65 72 66  these two interf
1d610 61 63 65 73 20 66 6f 72 20 72 65 70 6f 72 74 69  aces for reporti
1d620 6e 67 20 6f 6e 20 74 68 65 20 73 74 61 74 75 73  ng on the status
1d630 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  .** of the [sqli
1d640 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b  te3_malloc()], [
1d650 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2c  sqlite3_free()],
1d660 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65   and [sqlite3_re
1d670 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74  alloc()].** rout
1d680 69 6e 65 73 2c 20 77 68 69 63 68 20 66 6f 72 6d  ines, which form
1d690 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65   the built-in me
1d6a0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
1d6b0 73 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a  subsystem..**.**
1d6c0 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d   ^The [sqlite3_m
1d6d0 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 72 6f  emory_used()] ro
1d6e0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
1d6f0 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
1d700 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 63  s.** of memory c
1d710 75 72 72 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e  urrently outstan
1d720 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62  ding (malloced b
1d730 75 74 20 6e 6f 74 20 66 72 65 65 64 29 2e 0a 2a  ut not freed)..*
1d740 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  * ^The [sqlite3_
1d750 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
1d760 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75  ()] routine retu
1d770 72 6e 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a  rns the maximum.
1d780 2a 2a 20 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c  ** value of [sql
1d790 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
1d7a0 28 29 5d 20 73 69 6e 63 65 20 74 68 65 20 68 69  ()] since the hi
1d7b0 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a  gh-water mark.**
1d7c0 20 77 61 73 20 6c 61 73 74 20 72 65 73 65 74 2e   was last reset.
1d7d0 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65    ^The values re
1d7e0 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
1d7f0 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
1d800 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  ] and.** [sqlite
1d810 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
1d820 65 72 28 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e  er()] include an
1d830 79 20 6f 76 65 72 68 65 61 64 0a 2a 2a 20 61 64  y overhead.** ad
1d840 64 65 64 20 62 79 20 53 51 4c 69 74 65 20 69 6e  ded by SQLite in
1d850 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74   its implementat
1d860 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ion of [sqlite3_
1d870 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75  malloc()],.** bu
1d880 74 20 6e 6f 74 20 6f 76 65 72 68 65 61 64 20 61  t not overhead a
1d890 64 64 65 64 20 62 79 20 74 68 65 20 61 6e 79 20  dded by the any 
1d8a0 75 6e 64 65 72 6c 79 69 6e 67 20 73 79 73 74 65  underlying syste
1d8b0 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20 72 6f 75  m library.** rou
1d8c0 74 69 6e 65 73 20 74 68 61 74 20 5b 73 71 6c 69  tines that [sqli
1d8d0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61  te3_malloc()] ma
1d8e0 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54  y call..**.** ^T
1d8f0 68 65 20 6d 65 6d 6f 72 79 20 68 69 67 68 2d 77  he memory high-w
1d900 61 74 65 72 20 6d 61 72 6b 20 69 73 20 72 65 73  ater mark is res
1d910 65 74 20 74 6f 20 74 68 65 20 63 75 72 72 65 6e  et to the curren
1d920 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73  t value of.** [s
1d930 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
1d940 65 64 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c  ed()] if and onl
1d950 79 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74  y if the paramet
1d960 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  er to.** [sqlite
1d970 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
1d980 65 72 28 29 5d 20 69 73 20 74 72 75 65 2e 20 20  er()] is true.  
1d990 5e 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 72  ^The value retur
1d9a0 6e 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74  ned.** by [sqlit
1d9b0 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
1d9c0 74 65 72 28 31 29 5d 20 69 73 20 74 68 65 20 68  ter(1)] is the h
1d9d0 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a  igh-water mark.*
1d9e0 2a 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 72  * prior to the r
1d9f0 65 73 65 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  eset..*/.SQLITE_
1da00 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  API sqlite3_int6
1da10 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79  4 sqlite3_memory
1da20 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a 53 51 4c  _used(void);.SQL
1da30 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f  ITE_API sqlite3_
1da40 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65  int64 sqlite3_me
1da50 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 69  mory_highwater(i
1da60 6e 74 20 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a  nt resetFlag);..
1da70 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1da80 50 73 65 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75  Pseudo-Random Nu
1da90 6d 62 65 72 20 47 65 6e 65 72 61 74 6f 72 0a 2a  mber Generator.*
1daa0 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74  *.** SQLite cont
1dab0 61 69 6e 73 20 61 20 68 69 67 68 2d 71 75 61 6c  ains a high-qual
1dac0 69 74 79 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f  ity pseudo-rando
1dad0 6d 20 6e 75 6d 62 65 72 20 67 65 6e 65 72 61 74  m number generat
1dae0 6f 72 20 28 50 52 4e 47 29 20 75 73 65 64 20 74  or (PRNG) used t
1daf0 6f 0a 2a 2a 20 73 65 6c 65 63 74 20 72 61 6e 64  o.** select rand
1db00 6f 6d 20 5b 52 4f 57 49 44 20 7c 20 52 4f 57 49  om [ROWID | ROWI
1db10 44 73 5d 20 77 68 65 6e 20 69 6e 73 65 72 74 69  Ds] when inserti
1db20 6e 67 20 6e 65 77 20 72 65 63 6f 72 64 73 20 69  ng new records i
1db30 6e 74 6f 20 61 20 74 61 62 6c 65 20 74 68 61 74  nto a table that
1db40 0a 2a 2a 20 61 6c 72 65 61 64 79 20 75 73 65 73  .** already uses
1db50 20 74 68 65 20 6c 61 72 67 65 73 74 20 70 6f 73   the largest pos
1db60 73 69 62 6c 65 20 5b 52 4f 57 49 44 5d 2e 20 20  sible [ROWID].  
1db70 54 68 65 20 50 52 4e 47 20 69 73 20 61 6c 73 6f  The PRNG is also
1db80 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65   used for.** the
1db90 20 62 75 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d   build-in random
1dba0 28 29 20 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f  () and randomblo
1dbb0 62 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  b() SQL function
1dbc0 73 2e 20 20 54 68 69 73 20 69 6e 74 65 72 66 61  s.  This interfa
1dbd0 63 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70  ce allows.** app
1dbe0 6c 69 63 61 74 69 6f 6e 73 20 74 6f 20 61 63 63  lications to acc
1dbf0 65 73 73 20 74 68 65 20 73 61 6d 65 20 50 52 4e  ess the same PRN
1dc00 47 20 66 6f 72 20 6f 74 68 65 72 20 70 75 72 70  G for other purp
1dc10 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63  oses..**.** ^A c
1dc20 61 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74  all to this rout
1dc30 69 6e 65 20 73 74 6f 72 65 73 20 4e 20 62 79 74  ine stores N byt
1dc40 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73  es of randomness
1dc50 20 69 6e 74 6f 20 62 75 66 66 65 72 20 50 2e 0a   into buffer P..
1dc60 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
1dc70 20 74 69 6d 65 20 74 68 69 73 20 72 6f 75 74 69   time this routi
1dc80 6e 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 65  ne is invoked (e
1dc90 69 74 68 65 72 20 69 6e 74 65 72 6e 61 6c 6c 79  ither internally
1dca0 20 6f 72 20 62 79 0a 2a 2a 20 74 68 65 20 61 70   or by.** the ap
1dcb0 70 6c 69 63 61 74 69 6f 6e 29 20 74 68 65 20 50  plication) the P
1dcc0 52 4e 47 20 69 73 20 73 65 65 64 65 64 20 75 73  RNG is seeded us
1dcd0 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f  ing randomness o
1dce0 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
1dcf0 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20  the xRandomness 
1dd00 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 64 65  method of the de
1dd10 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76  fault [sqlite3_v
1dd20 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e  fs] object..** ^
1dd30 4f 6e 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e  On all subsequen
1dd40 74 20 69 6e 76 6f 63 61 74 69 6f 6e 73 2c 20 74  t invocations, t
1dd50 68 65 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d  he pseudo-random
1dd60 6e 65 73 73 20 69 73 20 67 65 6e 65 72 61 74 65  ness is generate
1dd70 64 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c 79 20  d.** internally 
1dd80 61 6e 64 20 77 69 74 68 6f 75 74 20 72 65 63 6f  and without reco
1dd90 75 72 73 65 20 74 6f 20 74 68 65 20 5b 73 71 6c  urse to the [sql
1dda0 69 74 65 33 5f 76 66 73 5d 20 78 52 61 6e 64 6f  ite3_vfs] xRando
1ddb0 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e  mness.** method.
1ddc0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  .*/.SQLITE_API v
1ddd0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 61 6e 64  oid sqlite3_rand
1dde0 6f 6d 6e 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f  omness(int N, vo
1ddf0 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  id *P);../*.** C
1de00 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65  API3REF: Compile
1de10 2d 54 69 6d 65 20 41 75 74 68 6f 72 69 7a 61 74  -Time Authorizat
1de20 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a  ion Callbacks.**
1de30 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e  .** ^This routin
1de40 65 20 72 65 67 69 73 74 65 72 73 20 61 6e 20 61  e registers an a
1de50 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1de60 63 6b 20 77 69 74 68 20 61 20 70 61 72 74 69 63  ck with a partic
1de70 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73  ular.** [databas
1de80 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73  e connection], s
1de90 75 70 70 6c 69 65 64 20 69 6e 20 74 68 65 20 66  upplied in the f
1dea0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  irst argument..*
1deb0 2a 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65  * ^The authorize
1dec0 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  r callback is in
1ded0 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 74 61  voked as SQL sta
1dee0 74 65 6d 65 6e 74 73 20 61 72 65 20 62 65 69 6e  tements are bein
1def0 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79  g compiled.** by
1df00 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1df10 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69  e()] or its vari
1df20 61 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f 70 72  ants [sqlite3_pr
1df30 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20  epare_v2()],.** 
1df40 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1df50 31 36 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  16()] and [sqlit
1df60 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
1df70 29 5d 2e 20 20 5e 41 74 20 76 61 72 69 6f 75 73  )].  ^At various
1df80 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72 69 6e  .** points durin
1df90 67 20 74 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f  g the compilatio
1dfa0 6e 20 70 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f  n process, as lo
1dfb0 67 69 63 20 69 73 20 62 65 69 6e 67 20 63 72 65  gic is being cre
1dfc0 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f  ated.** to perfo
1dfd0 72 6d 20 76 61 72 69 6f 75 73 20 61 63 74 69 6f  rm various actio
1dfe0 6e 73 2c 20 74 68 65 20 61 75 74 68 6f 72 69 7a  ns, the authoriz
1dff0 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  er callback is i
1e000 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65  nvoked to.** see
1e010 20 69 66 20 74 68 6f 73 65 20 61 63 74 69 6f 6e   if those action
1e020 73 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20  s are allowed.  
1e030 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20  ^The authorizer 
1e040 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a  callback should.
1e050 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ** return [SQLIT
1e060 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20 74  E_OK] to allow t
1e070 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51 4c 49  he action, [SQLI
1e080 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 64 69  TE_IGNORE] to di
1e090 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 70  sallow the.** sp
1e0a0 65 63 69 66 69 63 20 61 63 74 69 6f 6e 20 62 75  ecific action bu
1e0b0 74 20 61 6c 6c 6f 77 20 74 68 65 20 53 51 4c 20  t allow the SQL 
1e0c0 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 63 6f 6e  statement to con
1e0d0 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a 20 63  tinue to be.** c
1e0e0 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53 51 4c  ompiled, or [SQL
1e0f0 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63 61 75  ITE_DENY] to cau
1e100 73 65 20 74 68 65 20 65 6e 74 69 72 65 20 53 51  se the entire SQ
1e110 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62  L statement to b
1e120 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20 77 69  e.** rejected wi
1e130 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 49  th an error.  ^I
1e140 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  f the authorizer
1e150 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
1e160 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65 20 6f  s.** any value o
1e170 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
1e180 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49  E_IGNORE], [SQLI
1e190 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49  TE_OK], or [SQLI
1e1a0 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e  TE_DENY].** then
1e1b0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72   the [sqlite3_pr
1e1c0 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65  epare_v2()] or e
1e1d0 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74  quivalent call t
1e1e0 68 61 74 20 74 72 69 67 67 65 72 65 64 0a 2a 2a  hat triggered.**
1e1f0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
1e200 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61  will fail with a
1e210 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e  n error message.
1e220 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20  .**.** When the 
1e230 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
1e240 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68   [SQLITE_OK], th
1e250 61 74 20 6d 65 61 6e 73 20 74 68 65 20 6f 70 65  at means the ope
1e260 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75 65 73  ration.** reques
1e270 74 65 64 20 69 73 20 6f 6b 2e 20 20 5e 57 68 65  ted is ok.  ^Whe
1e280 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  n the callback r
1e290 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44  eturns [SQLITE_D
1e2a0 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73 71  ENY], the.** [sq
1e2b0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1e2c0 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e  ()] or equivalen
1e2d0 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67  t call that trig
1e2e0 67 65 72 65 64 20 74 68 65 0a 2a 2a 20 61 75 74  gered the.** aut
1e2f0 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69  horizer will fai
1e300 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20  l with an error 
1e310 6d 65 73 73 61 67 65 20 65 78 70 6c 61 69 6e 69  message explaini
1e320 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63 63 65 73  ng that.** acces
1e330 73 20 69 73 20 64 65 6e 69 65 64 2e 20 0a 2a 2a  s is denied. .**
1e340 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70  .** ^The first p
1e350 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
1e360 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1e370 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66  ack is a copy of
1e380 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61   the third.** pa
1e390 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73  rameter to the s
1e3a0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
1e3b0 72 69 7a 65 72 28 29 20 69 6e 74 65 72 66 61 63  rizer() interfac
1e3c0 65 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70  e. ^The second p
1e3d0 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74  arameter.** to t
1e3e0 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  he callback is a
1e3f0 6e 20 69 6e 74 65 67 65 72 20 5b 53 51 4c 49 54  n integer [SQLIT
1e400 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20  E_COPY | action 
1e410 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63 69  code] that speci
1e420 66 69 65 73 0a 2a 2a 20 74 68 65 20 70 61 72 74  fies.** the part
1e430 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 20 74 6f  icular action to
1e440 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 20   be authorized. 
1e450 5e 54 68 65 20 74 68 69 72 64 20 74 68 72 6f 75  ^The third throu
1e460 67 68 20 73 69 78 74 68 20 70 61 72 61 6d 65 74  gh sixth paramet
1e470 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61  ers.** to the ca
1e480 6c 6c 62 61 63 6b 20 61 72 65 20 7a 65 72 6f 2d  llback are zero-
1e490 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e  terminated strin
1e4a0 67 73 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 20  gs that contain 
1e4b0 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65  additional.** de
1e4c0 74 61 69 6c 73 20 61 62 6f 75 74 20 74 68 65 20  tails about the 
1e4d0 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74  action to be aut
1e4e0 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  horized..**.** ^
1e4f0 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f  If the action co
1e500 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 52 45  de is [SQLITE_RE
1e510 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63  AD].** and the c
1e520 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
1e530 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20  [SQLITE_IGNORE] 
1e540 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65  then the.** [pre
1e550 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
1e560 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63 6f   statement is co
1e570 6e 73 74 72 75 63 74 65 64 20 74 6f 20 73 75 62  nstructed to sub
1e580 73 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c  stitute.** a NUL
1e590 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c 61 63 65  L value in place
1e5a0 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f   of the table co
1e5b0 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64 20  lumn that would 
1e5c0 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61  have.** been rea
1e5d0 64 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  d if [SQLITE_OK]
1e5e0 20 68 61 64 20 62 65 65 6e 20 72 65 74 75 72 6e   had been return
1e5f0 65 64 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45  ed.  The [SQLITE
1e600 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75  _IGNORE].** retu
1e610 72 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  rn can be used t
1e620 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74 72 75 73  o deny an untrus
1e630 74 65 64 20 75 73 65 72 20 61 63 63 65 73 73 20  ted user access 
1e640 74 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a  to individual.**
1e650 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61   columns of a ta
1e660 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ble..** ^If the 
1e670 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b  action code is [
1e680 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20 61  SQLITE_DELETE] a
1e690 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  nd the callback 
1e6a0 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49  returns.** [SQLI
1e6b0 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20  TE_IGNORE] then 
1e6c0 74 68 65 20 5b 44 45 4c 45 54 45 5d 20 6f 70 65  the [DELETE] ope
1e6d0 72 61 74 69 6f 6e 20 70 72 6f 63 65 65 64 73 20  ration proceeds 
1e6e0 62 75 74 20 74 68 65 0a 2a 2a 20 5b 74 72 75 6e  but the.** [trun
1e6f0 63 61 74 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f  cate optimizatio
1e700 6e 5d 20 69 73 20 64 69 73 61 62 6c 65 64 20 61  n] is disabled a
1e710 6e 64 20 61 6c 6c 20 72 6f 77 73 20 61 72 65 20  nd all rows are 
1e720 64 65 6c 65 74 65 64 20 69 6e 64 69 76 69 64 75  deleted individu
1e730 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61  ally..**.** An a
1e740 75 74 68 6f 72 69 7a 65 72 20 69 73 20 75 73 65  uthorizer is use
1e750 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f  d when [sqlite3_
1e760 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72  prepare | prepar
1e770 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74  ing].** SQL stat
1e780 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75  ements from an u
1e790 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 2c  ntrusted source,
1e7a0 20 74 6f 20 65 6e 73 75 72 65 20 74 68 61 74 20   to ensure that 
1e7b0 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
1e7c0 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79  ts.** do not try
1e7d0 20 74 6f 20 61 63 63 65 73 73 20 64 61 74 61 20   to access data 
1e7e0 74 68 65 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c  they are not all
1e7f0 6f 77 65 64 20 74 6f 20 73 65 65 2c 20 6f 72 20  owed to see, or 
1e800 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74  that they do not
1e810 0a 2a 2a 20 74 72 79 20 74 6f 20 65 78 65 63 75  .** try to execu
1e820 74 65 20 6d 61 6c 69 63 69 6f 75 73 20 73 74 61  te malicious sta
1e830 74 65 6d 65 6e 74 73 20 74 68 61 74 20 64 61 6d  tements that dam
1e840 61 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65  age the database
1e850 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c  .  For.** exampl
1e860 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  e, an applicatio
1e870 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75 73  n may allow a us
1e880 65 72 20 74 6f 20 65 6e 74 65 72 20 61 72 62 69  er to enter arbi
1e890 74 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65  trary.** SQL que
1e8a0 72 69 65 73 20 66 6f 72 20 65 76 61 6c 75 61 74  ries for evaluat
1e8b0 69 6f 6e 20 62 79 20 61 20 64 61 74 61 62 61 73  ion by a databas
1e8c0 65 2e 20 20 42 75 74 20 74 68 65 20 61 70 70 6c  e.  But the appl
1e8d0 69 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20  ication does.** 
1e8e0 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 75 73 65  not want the use
1e8f0 72 20 74 6f 20 62 65 20 61 62 6c 65 20 74 6f 20  r to be able to 
1e900 6d 61 6b 65 20 61 72 62 69 74 72 61 72 79 20 63  make arbitrary c
1e910 68 61 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a  hanges to the.**
1e920 20 64 61 74 61 62 61 73 65 2e 20 20 41 6e 20 61   database.  An a
1e930 75 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20  uthorizer could 
1e940 74 68 65 6e 20 62 65 20 70 75 74 20 69 6e 20 70  then be put in p
1e950 6c 61 63 65 20 77 68 69 6c 65 20 74 68 65 0a 2a  lace while the.*
1e960 2a 20 75 73 65 72 2d 65 6e 74 65 72 65 64 20 53  * user-entered S
1e970 51 4c 20 69 73 20 62 65 69 6e 67 20 5b 73 71 6c  QL is being [sql
1e980 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70  ite3_prepare | p
1e990 72 65 70 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a  repared] that.**
1e9a0 20 64 69 73 61 6c 6c 6f 77 73 20 65 76 65 72 79   disallows every
1e9b0 74 68 69 6e 67 20 65 78 63 65 70 74 20 5b 53 45  thing except [SE
1e9c0 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 73  LECT] statements
1e9d0 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74  ..**.** Applicat
1e9e0 69 6f 6e 73 20 74 68 61 74 20 6e 65 65 64 20 74  ions that need t
1e9f0 6f 20 70 72 6f 63 65 73 73 20 53 51 4c 20 66 72  o process SQL fr
1ea00 6f 6d 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75  om untrusted sou
1ea10 72 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c  rces.** might al
1ea20 73 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65  so consider lowe
1ea30 72 69 6e 67 20 72 65 73 6f 75 72 63 65 20 6c 69  ring resource li
1ea40 6d 69 74 73 20 75 73 69 6e 67 20 5b 73 71 6c 69  mits using [sqli
1ea50 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20  te3_limit()].** 
1ea60 61 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64 61 74  and limiting dat
1ea70 61 62 61 73 65 20 73 69 7a 65 20 75 73 69 6e 67  abase size using
1ea80 20 74 68 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63   the [max_page_c
1ea90 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a  ount] [PRAGMA].*
1eaa0 2a 20 69 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f  * in addition to
1eab0 20 75 73 69 6e 67 20 61 6e 20 61 75 74 68 6f 72   using an author
1eac0 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e  izer..**.** ^(On
1ead0 6c 79 20 61 20 73 69 6e 67 6c 65 20 61 75 74 68  ly a single auth
1eae0 6f 72 69 7a 65 72 20 63 61 6e 20 62 65 20 69 6e  orizer can be in
1eaf0 20 70 6c 61 63 65 20 6f 6e 20 61 20 64 61 74 61   place on a data
1eb00 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
1eb10 2a 2a 20 61 74 20 61 20 74 69 6d 65 2e 20 20 45  ** at a time.  E
1eb20 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  ach call to sqli
1eb30 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
1eb40 65 72 20 6f 76 65 72 72 69 64 65 73 20 74 68 65  er overrides the
1eb50 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 63 61 6c  .** previous cal
1eb60 6c 2e 29 5e 20 20 5e 44 69 73 61 62 6c 65 20 74  l.)^  ^Disable t
1eb70 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 62 79  he authorizer by
1eb80 20 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55   installing a NU
1eb90 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20  LL callback..** 
1eba0 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 69  The authorizer i
1ebb0 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65  s disabled by de
1ebc0 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  fault..**.** The
1ebd0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1ebe0 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f  back must not do
1ebf0 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77   anything that w
1ec00 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68  ill modify.** th
1ec10 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
1ec20 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b  ction that invok
1ec30 65 64 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  ed the authorize
1ec40 72 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e  r callback..** N
1ec50 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65  ote that [sqlite
1ec60 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
1ec70 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  and [sqlite3_ste
1ec80 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79  p()] both modify
1ec90 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61   their.** databa
1eca0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66  se connections f
1ecb0 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f  or the meaning o
1ecc0 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68  f "modify" in th
1ecd0 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a  is paragraph..**
1ece0 0a 2a 2a 20 5e 57 68 65 6e 20 5b 73 71 6c 69 74  .** ^When [sqlit
1ecf0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
1ed00 20 69 73 20 75 73 65 64 20 74 6f 20 70 72 65 70   is used to prep
1ed10 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74 2c  are a statement,
1ed20 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e   the.** statemen
1ed30 74 20 6d 69 67 68 74 20 62 65 20 72 65 2d 70 72  t might be re-pr
1ed40 65 70 61 72 65 64 20 64 75 72 69 6e 67 20 5b 73  epared during [s
1ed50 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 64  qlite3_step()] d
1ed60 75 65 20 74 6f 20 61 20 0a 2a 2a 20 73 63 68 65  ue to a .** sche
1ed70 6d 61 20 63 68 61 6e 67 65 2e 20 20 48 65 6e 63  ma change.  Henc
1ed80 65 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  e, the applicati
1ed90 6f 6e 20 73 68 6f 75 6c 64 20 65 6e 73 75 72 65  on should ensure
1eda0 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 63 6f 72   that the.** cor
1edb0 72 65 63 74 20 61 75 74 68 6f 72 69 7a 65 72 20  rect authorizer 
1edc0 63 61 6c 6c 62 61 63 6b 20 72 65 6d 61 69 6e 73  callback remains
1edd0 20 69 6e 20 70 6c 61 63 65 20 64 75 72 69 6e 67   in place during
1ede0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74   the [sqlite3_st
1edf0 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f  ep()]..**.** ^No
1ee00 74 65 20 74 68 61 74 20 74 68 65 20 61 75 74 68  te that the auth
1ee10 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1ee20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20  is invoked only 
1ee30 64 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74  during.** [sqlit
1ee40 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72  e3_prepare()] or
1ee50 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 20 20   its variants.  
1ee60 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73  Authorization is
1ee70 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65   not.** performe
1ee80 64 20 64 75 72 69 6e 67 20 73 74 61 74 65 6d 65  d during stateme
1ee90 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e  nt evaluation in
1eea0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
1eeb0 5d 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20 61 73 20  ], unless.** as 
1eec0 73 74 61 74 65 64 20 69 6e 20 74 68 65 20 70 72  stated in the pr
1eed0 65 76 69 6f 75 73 20 70 61 72 61 67 72 61 70 68  evious paragraph
1eee0 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  , sqlite3_step()
1eef0 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69   invokes.** sqli
1ef00 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1ef10 20 74 6f 20 72 65 70 72 65 70 61 72 65 20 61 20   to reprepare a 
1ef20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20  statement after 
1ef30 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e  a schema change.
1ef40 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
1ef50 6e 74 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  nt sqlite3_set_a
1ef60 75 74 68 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c  uthorizer(.  sql
1ef70 69 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78  ite3*,.  int (*x
1ef80 41 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c  Auth)(void*,int,
1ef90 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73  const char*,cons
1efa0 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68  t char*,const ch
1efb0 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29  ar*,const char*)
1efc0 2c 0a 20 20 76 6f 69 64 20 2a 70 55 73 65 72 44  ,.  void *pUserD
1efd0 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ata.);../*.** CA
1efe0 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a  PI3REF: Authoriz
1eff0 65 72 20 52 65 74 75 72 6e 20 43 6f 64 65 73 0a  er Return Codes.
1f000 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74  **.** The [sqlit
1f010 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
1f020 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63  r | authorizer c
1f030 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
1f040 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e  ] must.** return
1f050 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f   either [SQLITE_
1f060 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68  OK] or one of th
1f070 65 73 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74  ese two constant
1f080 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f  s in order.** to
1f090 20 73 69 67 6e 61 6c 20 53 51 4c 69 74 65 20 77   signal SQLite w
1f0a0 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
1f0b0 65 20 61 63 74 69 6f 6e 20 69 73 20 70 65 72 6d  e action is perm
1f0c0 69 74 74 65 64 2e 20 20 53 65 65 20 74 68 65 0a  itted.  See the.
1f0d0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  ** [sqlite3_set_
1f0e0 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74  authorizer | aut
1f0f0 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74  horizer document
1f100 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74  ation] for addit
1f110 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61  ional.** informa
1f120 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65  tion..**.** Note
1f130 20 74 68 61 74 20 53 51 4c 49 54 45 5f 49 47 4e   that SQLITE_IGN
1f140 4f 52 45 20 69 73 20 61 6c 73 6f 20 75 73 65 64  ORE is also used
1f150 20 61 73 20 61 20 5b 53 51 4c 49 54 45 5f 52 4f   as a [SQLITE_RO
1f160 4c 4c 42 41 43 4b 20 7c 20 72 65 74 75 72 6e 20  LLBACK | return 
1f170 63 6f 64 65 5d 0a 2a 2a 20 66 72 6f 6d 20 74 68  code].** from th
1f180 65 20 5b 73 71 6c 69 74 65 33 5f 76 74 61 62 5f  e [sqlite3_vtab_
1f190 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d 20 69  on_conflict()] i
1f1a0 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 64 65  nterface..*/.#de
1f1b0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e 59  fine SQLITE_DENY
1f1c0 20 20 20 31 20 20 20 2f 2a 20 41 62 6f 72 74 20     1   /* Abort 
1f1d0 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
1f1e0 74 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20  t with an error 
1f1f0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1f200 45 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a 20  E_IGNORE 2   /* 
1f210 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63 65  Don't allow acce
1f220 73 73 2c 20 62 75 74 20 64 6f 6e 27 74 20 67 65  ss, but don't ge
1f230 6e 65 72 61 74 65 20 61 6e 20 65 72 72 6f 72 20  nerate an error 
1f240 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
1f250 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 41  EF: Authorizer A
1f260 63 74 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a  ction Codes.**.*
1f270 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  * The [sqlite3_s
1f280 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d  et_authorizer()]
1f290 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73   interface regis
1f2a0 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20  ters a callback 
1f2b0 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74  function.** that
1f2c0 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61   is invoked to a
1f2d0 75 74 68 6f 72 69 7a 65 20 63 65 72 74 61 69 6e  uthorize certain
1f2e0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61   SQL statement a
1f2f0 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20  ctions.  The.** 
1f300 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
1f310 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
1f320 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 63   is an integer c
1f330 6f 64 65 20 74 68 61 74 20 73 70 65 63 69 66 69  ode that specifi
1f340 65 73 0a 2a 2a 20 77 68 61 74 20 61 63 74 69 6f  es.** what actio
1f350 6e 20 69 73 20 62 65 69 6e 67 20 61 75 74 68 6f  n is being autho
1f360 72 69 7a 65 64 2e 20 20 54 68 65 73 65 20 61 72  rized.  These ar
1f370 65 20 74 68 65 20 69 6e 74 65 67 65 72 20 61 63  e the integer ac
1f380 74 69 6f 6e 20 63 6f 64 65 73 20 74 68 61 74 0a  tion codes that.
1f390 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  ** the authorize
1f3a0 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62  r callback may b
1f3b0 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20  e passed..**.** 
1f3c0 54 68 65 73 65 20 61 63 74 69 6f 6e 20 63 6f 64  These action cod
1f3d0 65 20 76 61 6c 75 65 73 20 73 69 67 6e 69 66 79  e values signify
1f3e0 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70   what kind of op
1f3f0 65 72 61 74 69 6f 6e 20 69 73 20 74 6f 20 62 65  eration is to be
1f400 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e 20  .** authorized. 
1f410 20 54 68 65 20 33 72 64 20 61 6e 64 20 34 74 68   The 3rd and 4th
1f420 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74   parameters to t
1f430 68 65 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e  he authorization
1f440 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  .** callback fun
1f450 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61  ction will be pa
1f460 72 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c  rameters or NULL
1f470 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68   depending on wh
1f480 69 63 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20  ich of these.** 
1f490 63 6f 64 65 73 20 69 73 20 75 73 65 64 20 61 73  codes is used as
1f4a0 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
1f4b0 6d 65 74 65 72 2e 20 20 5e 28 54 68 65 20 35 74  meter.  ^(The 5t
1f4c0 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
1f4d0 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72  he.** authorizer
1f4e0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65   callback is the
1f4f0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74   name of the dat
1f500 61 62 61 73 65 20 28 22 6d 61 69 6e 22 2c 20 22  abase ("main", "
1f510 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e 29 20  temp",.** etc.) 
1f520 69 66 20 61 70 70 6c 69 63 61 62 6c 65 2e 29 5e  if applicable.)^
1f530 20 20 5e 54 68 65 20 36 74 68 20 70 61 72 61 6d    ^The 6th param
1f540 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68  eter to the auth
1f550 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a  orizer callback.
1f560 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  ** is the name o
1f570 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74  f the inner-most
1f580 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 65 77   trigger or view
1f590 20 74 68 61 74 20 69 73 20 72 65 73 70 6f 6e 73   that is respons
1f5a0 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20  ible for.** the 
1f5b0 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 6f  access attempt o
1f5c0 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 20 61  r NULL if this a
1f5d0 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 69 73  ccess attempt is
1f5e0 20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a   directly from.*
1f5f0 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20  * top-level SQL 
1f600 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a  code..*/./******
1f610 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1f620 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1f630 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a  ***** 3rd ******
1f640 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a  ****** 4th *****
1f650 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20  ******/.#define 
1f660 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 49 4e  SQLITE_CREATE_IN
1f670 44 45 58 20 20 20 20 20 20 20 20 20 20 31 20 20  DEX          1  
1f680 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
1f690 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
1f6a0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1f6b0 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 41 42  QLITE_CREATE_TAB
1f6c0 4c 45 20 20 20 20 20 20 20 20 20 20 32 20 20 20  LE          2   
1f6d0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
1f6e0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1f6f0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1f700 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50  LITE_CREATE_TEMP
1f710 5f 49 4e 44 45 58 20 20 20 20 20 33 20 20 20 2f  _INDEX     3   /
1f720 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
1f730 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
1f740 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1f750 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f  ITE_CREATE_TEMP_
1f760 54 41 42 4c 45 20 20 20 20 20 34 20 20 20 2f 2a  TABLE     4   /*
1f770 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1f780 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1f790 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1f7a0 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54  TE_CREATE_TEMP_T
1f7b0 52 49 47 47 45 52 20 20 20 35 20 20 20 2f 2a 20  RIGGER   5   /* 
1f7c0 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20  Trigger Name    
1f7d0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1f7e0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1f7f0 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 56 49  E_CREATE_TEMP_VI
1f800 45 57 20 20 20 20 20 20 36 20 20 20 2f 2a 20 56  EW      6   /* V
1f810 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e  iew Name       N
1f820 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1f830 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1f840 5f 43 52 45 41 54 45 5f 54 52 49 47 47 45 52 20  _CREATE_TRIGGER 
1f850 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 54 72         7   /* Tr
1f860 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61  igger Name    Ta
1f870 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
1f880 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1f890 43 52 45 41 54 45 5f 56 49 45 57 20 20 20 20 20  CREATE_VIEW     
1f8a0 20 20 20 20 20 20 38 20 20 20 2f 2a 20 56 69 65        8   /* Vie
1f8b0 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c  w Name       NUL
1f8c0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1f8d0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1f8e0 45 4c 45 54 45 20 20 20 20 20 20 20 20 20 20 20  ELETE           
1f8f0 20 20 20 20 20 39 20 20 20 2f 2a 20 54 61 62 6c       9   /* Tabl
1f900 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
1f910 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1f920 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
1f930 4f 50 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20  OP_INDEX        
1f940 20 20 20 31 30 20 20 20 2f 2a 20 49 6e 64 65 78     10   /* Index
1f950 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65   Name      Table
1f960 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
1f970 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
1f980 50 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20  P_TABLE         
1f990 20 20 31 31 20 20 20 2f 2a 20 54 61 62 6c 65 20    11   /* Table 
1f9a0 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
1f9b0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1f9c0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
1f9d0 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20  _TEMP_INDEX     
1f9e0 20 31 32 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e   12   /* Index N
1f9f0 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e  ame      Table N
1fa00 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
1fa10 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
1fa20 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 20  TEMP_TABLE      
1fa30 31 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  13   /* Table Na
1fa40 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
1fa50 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1fa60 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
1fa70 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 20 31  EMP_TRIGGER    1
1fa80 34 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e  4   /* Trigger N
1fa90 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  ame    Table Nam
1faa0 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
1fab0 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45  e SQLITE_DROP_TE
1fac0 4d 50 5f 56 49 45 57 20 20 20 20 20 20 20 31 35  MP_VIEW       15
1fad0 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20     /* View Name 
1fae0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1faf0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1fb00 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49   SQLITE_DROP_TRI
1fb10 47 47 45 52 20 20 20 20 20 20 20 20 20 31 36 20  GGER         16 
1fb20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d    /* Trigger Nam
1fb30 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  e    Table Name 
1fb40 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1fb50 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45 57  SQLITE_DROP_VIEW
1fb60 20 20 20 20 20 20 20 20 20 20 20 20 31 37 20 20              17  
1fb70 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20   /* View Name   
1fb80 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1fb90 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1fba0 51 4c 49 54 45 5f 49 4e 53 45 52 54 20 20 20 20  QLITE_INSERT    
1fbb0 20 20 20 20 20 20 20 20 20 20 20 31 38 20 20 20             18   
1fbc0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
1fbd0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1fbe0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1fbf0 4c 49 54 45 5f 50 52 41 47 4d 41 20 20 20 20 20  LITE_PRAGMA     
1fc00 20 20 20 20 20 20 20 20 20 20 31 39 20 20 20 2f            19   /
1fc10 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65 20 20 20  * Pragma Name   
1fc20 20 20 31 73 74 20 61 72 67 20 6f 72 20 4e 55 4c    1st arg or NUL
1fc30 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  L */.#define SQL
1fc40 49 54 45 5f 52 45 41 44 20 20 20 20 20 20 20 20  ITE_READ        
1fc50 20 20 20 20 20 20 20 20 20 32 30 20 20 20 2f 2a           20   /*
1fc60 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1fc70 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20   Column Name    
1fc80 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1fc90 54 45 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20  TE_SELECT       
1fca0 20 20 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20          21   /* 
1fcb0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1fcc0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1fcd0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1fce0 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20 20 20  E_TRANSACTION   
1fcf0 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20 4f         22   /* O
1fd00 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20 4e  peration       N
1fd10 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1fd20 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1fd30 5f 55 50 44 41 54 45 20 20 20 20 20 20 20 20 20  _UPDATE         
1fd40 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 54 61        23   /* Ta
1fd50 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f  ble Name      Co
1fd60 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f  lumn Name     */
1fd70 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1fd80 41 54 54 41 43 48 20 20 20 20 20 20 20 20 20 20  ATTACH          
1fd90 20 20 20 20 20 32 34 20 20 20 2f 2a 20 46 69 6c       24   /* Fil
1fda0 65 6e 61 6d 65 20 20 20 20 20 20 20 20 4e 55 4c  ename        NUL
1fdb0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1fdc0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1fdd0 45 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20  ETACH           
1fde0 20 20 20 20 32 35 20 20 20 2f 2a 20 44 61 74 61      25   /* Data
1fdf0 62 61 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c  base Name   NULL
1fe00 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1fe10 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c  define SQLITE_AL
1fe20 54 45 52 5f 54 41 42 4c 45 20 20 20 20 20 20 20  TER_TABLE       
1fe30 20 20 20 32 36 20 20 20 2f 2a 20 44 61 74 61 62     26   /* Datab
1fe40 61 73 65 20 4e 61 6d 65 20 20 20 54 61 62 6c 65  ase Name   Table
1fe50 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
1fe60 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 49  efine SQLITE_REI
1fe70 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20 20  NDEX            
1fe80 20 20 32 37 20 20 20 2f 2a 20 49 6e 64 65 78 20    27   /* Index 
1fe90 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
1fea0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1feb0 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c  fine SQLITE_ANAL
1fec0 59 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20  YZE             
1fed0 20 32 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   28   /* Table N
1fee0 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
1fef0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1ff00 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
1ff10 45 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20  E_VTABLE        
1ff20 32 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  29   /* Table Na
1ff30 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e  me      Module N
1ff40 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  ame     */.#defi
1ff50 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56  ne SQLITE_DROP_V
1ff60 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 33  TABLE          3
1ff70 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  0   /* Table Nam
1ff80 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61  e      Module Na
1ff90 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  me     */.#defin
1ffa0 65 20 53 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f  e SQLITE_FUNCTIO
1ffb0 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 33 31  N             31
1ffc0 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20     /* NULL      
1ffd0 20 20 20 20 20 20 46 75 6e 63 74 69 6f 6e 20 4e        Function N
1ffe0 61 6d 65 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  ame   */.#define
1fff0 20 53 51 4c 49 54 45 5f 53 41 56 45 50 4f 49 4e   SQLITE_SAVEPOIN
20000 54 20 20 20 20 20 20 20 20 20 20 20 20 33 32 20  T            32 
20010 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20    /* Operation  
20020 20 20 20 20 20 53 61 76 65 70 6f 69 6e 74 20 4e       Savepoint N
20030 61 6d 65 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ame  */.#define 
20040 53 51 4c 49 54 45 5f 43 4f 50 59 20 20 20 20 20  SQLITE_COPY     
20050 20 20 20 20 20 20 20 20 20 20 20 20 20 30 20 20               0  
20060 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73   /* No longer us
20070 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ed */../*.** CAP
20080 49 33 52 45 46 3a 20 54 72 61 63 69 6e 67 20 41  I3REF: Tracing A
20090 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e  nd Profiling Fun
200a0 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65  ctions.**.** The
200b0 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 67 69  se routines regi
200c0 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75  ster callback fu
200d0 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 63 61 6e  nctions that can
200e0 20 62 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20   be used for.** 
200f0 74 72 61 63 69 6e 67 20 61 6e 64 20 70 72 6f 66  tracing and prof
20100 69 6c 69 6e 67 20 74 68 65 20 65 78 65 63 75 74  iling the execut
20110 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61 74 65  ion of SQL state
20120 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ments..**.** ^Th
20130 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
20140 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62  ion registered b
20150 79 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28  y sqlite3_trace(
20160 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a  ) is invoked at.
20170 2a 2a 20 76 61 72 69 6f 75 73 20 74 69 6d 65 73  ** various times
20180 20 77 68 65 6e 20 61 6e 20 53 51 4c 20 73 74 61   when an SQL sta
20190 74 65 6d 65 6e 74 20 69 73 20 62 65 69 6e 67 20  tement is being 
201a0 72 75 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  run by [sqlite3_
201b0 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65  step()]..** ^The
201c0 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29   sqlite3_trace()
201d0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
201e0 6f 6b 65 64 20 77 69 74 68 20 61 20 55 54 46 2d  oked with a UTF-
201f0 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74  8 rendering of t
20200 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d  he.** SQL statem
20210 65 6e 74 20 74 65 78 74 20 61 73 20 74 68 65 20  ent text as the 
20220 73 74 61 74 65 6d 65 6e 74 20 66 69 72 73 74 20  statement first 
20230 62 65 67 69 6e 73 20 65 78 65 63 75 74 69 6e 67  begins executing
20240 2e 0a 2a 2a 20 5e 28 41 64 64 69 74 69 6f 6e 61  ..** ^(Additiona
20250 6c 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28  l sqlite3_trace(
20260 29 20 63 61 6c 6c 62 61 63 6b 73 20 6d 69 67 68  ) callbacks migh
20270 74 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20 65 61  t occur.** as ea
20280 63 68 20 74 72 69 67 67 65 72 65 64 20 73 75 62  ch triggered sub
20290 70 72 6f 67 72 61 6d 20 69 73 20 65 6e 74 65 72  program is enter
202a0 65 64 2e 20 20 54 68 65 20 63 61 6c 6c 62 61 63  ed.  The callbac
202b0 6b 73 20 66 6f 72 20 74 72 69 67 67 65 72 73 0a  ks for triggers.
202c0 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55 54 46  ** contain a UTF
202d0 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 74  -8 SQL comment t
202e0 68 61 74 20 69 64 65 6e 74 69 66 69 65 73 20 74  hat identifies t
202f0 68 65 20 74 72 69 67 67 65 72 2e 29 5e 0a 2a 2a  he trigger.)^.**
20300 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63  .** ^The callbac
20310 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73  k function regis
20320 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33  tered by sqlite3
20330 5f 70 72 6f 66 69 6c 65 28 29 20 69 73 20 69 6e  _profile() is in
20340 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61 63 68  voked.** as each
20350 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66   SQL statement f
20360 69 6e 69 73 68 65 73 2e 20 20 5e 54 68 65 20 70  inishes.  ^The p
20370 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20  rofile callback 
20380 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20  contains.** the 
20390 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65  original stateme
203a0 6e 74 20 74 65 78 74 20 61 6e 64 20 61 6e 20 65  nt text and an e
203b0 73 74 69 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d  stimate of wall-
203c0 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66  clock time.** of
203d0 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61 74 20 73   how long that s
203e0 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f  tatement took to
203f0 20 72 75 6e 2e 20 20 5e 54 68 65 20 70 72 6f 66   run.  ^The prof
20400 69 6c 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  ile callback.** 
20410 74 69 6d 65 20 69 73 20 69 6e 20 75 6e 69 74 73  time is in units
20420 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c   of nanoseconds,
20430 20 68 6f 77 65 76 65 72 20 74 68 65 20 63 75 72   however the cur
20440 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74  rent implementat
20450 69 6f 6e 0a 2a 2a 20 69 73 20 6f 6e 6c 79 20 63  ion.** is only c
20460 61 70 61 62 6c 65 20 6f 66 20 6d 69 6c 6c 69 73  apable of millis
20470 65 63 6f 6e 64 20 72 65 73 6f 6c 75 74 69 6f 6e  econd resolution
20480 20 73 6f 20 74 68 65 20 73 69 78 20 6c 65 61 73   so the six leas
20490 74 20 73 69 67 6e 69 66 69 63 61 6e 74 0a 2a 2a  t significant.**
204a0 20 64 69 67 69 74 73 20 69 6e 20 74 68 65 20 74   digits in the t
204b0 69 6d 65 20 61 72 65 20 6d 65 61 6e 69 6e 67 6c  ime are meaningl
204c0 65 73 73 2e 20 20 46 75 74 75 72 65 20 76 65 72  ess.  Future ver
204d0 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 0a  sions of SQLite.
204e0 2a 2a 20 6d 69 67 68 74 20 70 72 6f 76 69 64 65  ** might provide
204f0 20 67 72 65 61 74 65 72 20 72 65 73 6f 6c 75 74   greater resolut
20500 69 6f 6e 20 6f 6e 20 74 68 65 20 70 72 6f 66 69  ion on the profi
20510 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20 20 54  ler callback.  T
20520 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72  he.** sqlite3_pr
20530 6f 66 69 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e  ofile() function
20540 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 65   is considered e
20550 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20  xperimental and 
20560 69 73 0a 2a 2a 20 73 75 62 6a 65 63 74 20 74 6f  is.** subject to
20570 20 63 68 61 6e 67 65 20 69 6e 20 66 75 74 75 72   change in futur
20580 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
20590 4c 69 74 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  Lite..*/.SQLITE_
205a0 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  API void *sqlite
205b0 33 5f 74 72 61 63 65 28 73 71 6c 69 74 65 33 2a  3_trace(sqlite3*
205c0 2c 20 76 6f 69 64 28 2a 78 54 72 61 63 65 29 28  , void(*xTrace)(
205d0 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72  void*,const char
205e0 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51 4c 49  *), void*);.SQLI
205f0 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 45 58  TE_API SQLITE_EX
20600 50 45 52 49 4d 45 4e 54 41 4c 20 76 6f 69 64 20  PERIMENTAL void 
20610 2a 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65  *sqlite3_profile
20620 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f  (sqlite3*,.   vo
20630 69 64 28 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f  id(*xProfile)(vo
20640 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  id*,const char*,
20650 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 2c  sqlite3_uint64),
20660 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20   void*);../*.** 
20670 43 41 50 49 33 52 45 46 3a 20 51 75 65 72 79 20  CAPI3REF: Query 
20680 50 72 6f 67 72 65 73 73 20 43 61 6c 6c 62 61 63  Progress Callbac
20690 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ks.**.** ^The sq
206a0 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68  lite3_progress_h
206b0 61 6e 64 6c 65 72 28 44 2c 4e 2c 58 2c 50 29 20  andler(D,N,X,P) 
206c0 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73  interface causes
206d0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a   the callback.**
206e0 20 66 75 6e 63 74 69 6f 6e 20 58 20 74 6f 20 62   function X to b
206f0 65 20 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64  e invoked period
20700 69 63 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f  ically during lo
20710 6e 67 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73  ng running calls
20720 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
20730 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65  exec()], [sqlite
20740 33 5f 73 74 65 70 28 29 5d 20 61 6e 64 20 5b 73  3_step()] and [s
20750 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
20760 28 29 5d 20 66 6f 72 0a 2a 2a 20 64 61 74 61 62  ()] for.** datab
20770 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44  ase connection D
20780 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 75 73  .  An example us
20790 65 20 66 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e  e for this.** in
207a0 74 65 72 66 61 63 65 20 69 73 20 74 6f 20 6b 65  terface is to ke
207b0 65 70 20 61 20 47 55 49 20 75 70 64 61 74 65 64  ep a GUI updated
207c0 20 64 75 72 69 6e 67 20 61 20 6c 61 72 67 65 20   during a large 
207d0 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  query..**.** ^Th
207e0 65 20 70 61 72 61 6d 65 74 65 72 20 50 20 69 73  e parameter P is
207f0 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 20   passed through 
20800 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61  as the only para
20810 6d 65 74 65 72 20 74 6f 20 74 68 65 20 0a 2a 2a  meter to the .**
20820 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
20830 6f 6e 20 58 2e 20 20 5e 54 68 65 20 70 61 72 61  on X.  ^The para
20840 6d 65 74 65 72 20 4e 20 69 73 20 74 68 65 20 6e  meter N is the n
20850 75 6d 62 65 72 20 6f 66 20 0a 2a 2a 20 5b 76 69  umber of .** [vi
20860 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 69 6e  rtual machine in
20870 73 74 72 75 63 74 69 6f 6e 73 5d 20 74 68 61 74  structions] that
20880 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 20 62   are evaluated b
20890 65 74 77 65 65 6e 20 73 75 63 63 65 73 73 69 76  etween successiv
208a0 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73  e.** invocations
208b0 20 6f 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   of the callback
208c0 20 58 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20   X..**.** ^Only 
208d0 61 20 73 69 6e 67 6c 65 20 70 72 6f 67 72 65 73  a single progres
208e0 73 20 68 61 6e 64 6c 65 72 20 6d 61 79 20 62 65  s handler may be
208f0 20 64 65 66 69 6e 65 64 20 61 74 20 6f 6e 65 20   defined at one 
20900 74 69 6d 65 20 70 65 72 0a 2a 2a 20 5b 64 61 74  time per.** [dat
20910 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
20920 5d 3b 20 73 65 74 74 69 6e 67 20 61 20 6e 65 77  ]; setting a new
20930 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
20940 72 20 63 61 6e 63 65 6c 73 20 74 68 65 0a 2a 2a  r cancels the.**
20950 20 6f 6c 64 20 6f 6e 65 2e 20 20 5e 53 65 74 74   old one.  ^Sett
20960 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20 58 20  ing parameter X 
20970 74 6f 20 4e 55 4c 4c 20 64 69 73 61 62 6c 65 73  to NULL disables
20980 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 68 61   the progress ha
20990 6e 64 6c 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 70  ndler..** ^The p
209a0 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20  rogress handler 
209b0 69 73 20 61 6c 73 6f 20 64 69 73 61 62 6c 65 64  is also disabled
209c0 20 62 79 20 73 65 74 74 69 6e 67 20 4e 20 74 6f   by setting N to
209d0 20 61 20 76 61 6c 75 65 20 6c 65 73 73 0a 2a 2a   a value less.**
209e0 20 74 68 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e   than 1..**.** ^
209f0 49 66 20 74 68 65 20 70 72 6f 67 72 65 73 73 20  If the progress 
20a00 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
20a10 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 6f   non-zero, the o
20a20 70 65 72 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 69  peration is.** i
20a30 6e 74 65 72 72 75 70 74 65 64 2e 20 20 54 68 69  nterrupted.  Thi
20a40 73 20 66 65 61 74 75 72 65 20 63 61 6e 20 62 65  s feature can be
20a50 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65   used to impleme
20a60 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63 65 6c 22  nt a.** "Cancel"
20a70 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20 47 55 49   button on a GUI
20a80 20 70 72 6f 67 72 65 73 73 20 64 69 61 6c 6f 67   progress dialog
20a90 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20   box..**.** The 
20aa0 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
20ab0 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e   callback must n
20ac0 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74  ot do anything t
20ad0 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a  hat will modify.
20ae0 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
20af0 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20  connection that 
20b00 69 6e 76 6f 6b 65 64 20 74 68 65 20 70 72 6f 67  invoked the prog
20b10 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a  ress handler..**
20b20 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69   Note that [sqli
20b30 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
20b40 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73  ] and [sqlite3_s
20b50 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69  tep()] both modi
20b60 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61  fy their.** data
20b70 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
20b80 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67   for the meaning
20b90 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20   of "modify" in 
20ba0 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a  this paragraph..
20bb0 2a 2a 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  **.*/.SQLITE_API
20bc0 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 70 72   void sqlite3_pr
20bd0 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 73  ogress_handler(s
20be0 71 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e  qlite3*, int, in
20bf0 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69  t(*)(void*), voi
20c00 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d*);../*.** CAPI
20c10 33 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20  3REF: Opening A 
20c20 4e 65 77 20 44 61 74 61 62 61 73 65 20 43 6f 6e  New Database Con
20c30 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54  nection.**.** ^T
20c40 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 70  hese routines op
20c50 65 6e 20 61 6e 20 53 51 4c 69 74 65 20 64 61 74  en an SQLite dat
20c60 61 62 61 73 65 20 66 69 6c 65 20 61 73 20 73 70  abase file as sp
20c70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 0a  ecified by the .
20c80 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75  ** filename argu
20c90 6d 65 6e 74 2e 20 5e 54 68 65 20 66 69 6c 65 6e  ment. ^The filen
20ca0 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ame argument is 
20cb0 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55  interpreted as U
20cc0 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69  TF-8 for.** sqli
20cd0 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73  te3_open() and s
20ce0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
20cf0 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36 20 69   and as UTF-16 i
20d00 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74  n the native byt
20d10 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20 73  e.** order for s
20d20 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e  qlite3_open16().
20d30 20 5e 28 41 20 5b 64 61 74 61 62 61 73 65 20 63   ^(A [database c
20d40 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c  onnection] handl
20d50 65 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20  e is usually.** 
20d60 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 70 44  returned in *ppD
20d70 62 2c 20 65 76 65 6e 20 69 66 20 61 6e 20 65 72  b, even if an er
20d80 72 6f 72 20 6f 63 63 75 72 73 2e 20 20 54 68 65  ror occurs.  The
20d90 20 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e 20   only exception 
20da0 69 73 20 74 68 61 74 0a 2a 2a 20 69 66 20 53 51  is that.** if SQ
20db0 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74  Lite is unable t
20dc0 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72  o allocate memor
20dd0 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73  y to hold the [s
20de0 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a  qlite3] object,.
20df0 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62  ** a NULL will b
20e00 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a  e written into *
20e10 70 70 44 62 20 69 6e 73 74 65 61 64 20 6f 66 20  ppDb instead of 
20e20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
20e30 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62   [sqlite3].** ob
20e40 6a 65 63 74 2e 29 5e 20 5e 28 49 66 20 74 68 65  ject.)^ ^(If the
20e50 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
20e60 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63 72 65 61  ned (and/or crea
20e70 74 65 64 29 20 73 75 63 63 65 73 73 66 75 6c 6c  ted) successfull
20e80 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49  y, then.** [SQLI
20e90 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e  TE_OK] is return
20ea0 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 61  ed.  Otherwise a
20eb0 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  n [error code] i
20ec0 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 5e 54  s returned.)^ ^T
20ed0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  he.** [sqlite3_e
20ee0 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c  rrmsg()] or [sql
20ef0 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d  ite3_errmsg16()]
20f00 20 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 62 65   routines can be
20f10 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a   used to obtain.
20f20 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61  ** an English la
20f30 6e 67 75 61 67 65 20 64 65 73 63 72 69 70 74 69  nguage descripti
20f40 6f 6e 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20  on of the error 
20f50 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c  following a fail
20f60 75 72 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66  ure of any.** of
20f70 20 74 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65   the sqlite3_ope
20f80 6e 28 29 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  n() routines..**
20f90 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74  .** ^The default
20fa0 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 74 68   encoding for th
20fb0 65 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20  e database will 
20fc0 62 65 20 55 54 46 2d 38 20 69 66 0a 2a 2a 20 73  be UTF-8 if.** s
20fd0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72  qlite3_open() or
20fe0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
20ff0 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 6e 64  () is called and
21000 0a 2a 2a 20 55 54 46 2d 31 36 20 69 6e 20 74 68  .** UTF-16 in th
21010 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  e native byte or
21020 64 65 72 20 69 66 20 73 71 6c 69 74 65 33 5f 6f  der if sqlite3_o
21030 70 65 6e 31 36 28 29 20 69 73 20 75 73 65 64 2e  pen16() is used.
21040 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f  .**.** Whether o
21050 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f  r not an error o
21060 63 63 75 72 73 20 77 68 65 6e 20 69 74 20 69 73  ccurs when it is
21070 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75 72 63   opened, resourc
21080 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64  es.** associated
21090 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62   with the [datab
210a0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
210b0 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62 65  handle should be
210c0 20 72 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20   released by.** 
210d0 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73  passing it to [s
210e0 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20  qlite3_close()] 
210f0 77 68 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f  when it is no lo
21100 6e 67 65 72 20 72 65 71 75 69 72 65 64 2e 0a 2a  nger required..*
21110 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
21120 5f 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74 65 72  _open_v2() inter
21130 66 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20  face works like 
21140 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a  sqlite3_open().*
21150 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74  * except that it
21160 20 61 63 63 65 70 74 73 20 74 77 6f 20 61 64 64   accepts two add
21170 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65  itional paramete
21180 72 73 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  rs for additiona
21190 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65  l control.** ove
211a0 72 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61  r the new databa
211b0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20  se connection.  
211c0 5e 28 54 68 65 20 66 6c 61 67 73 20 70 61 72 61  ^(The flags para
211d0 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 73 71 6c 69  meter to.** sqli
211e0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 63 61  te3_open_v2() ca
211f0 6e 20 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a  n take one of.**
21200 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74   the following t
21210 68 72 65 65 20 76 61 6c 75 65 73 2c 20 6f 70 74  hree values, opt
21220 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64  ionally combined
21230 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53   with the .** [S
21240 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54  QLITE_OPEN_NOMUT
21250 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45  EX], [SQLITE_OPE
21260 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53  N_FULLMUTEX], [S
21270 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45  QLITE_OPEN_SHARE
21280 44 43 41 43 48 45 5d 2c 0a 2a 2a 20 5b 53 51 4c  DCACHE],.** [SQL
21290 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45  ITE_OPEN_PRIVATE
212a0 43 41 43 48 45 5d 2c 20 61 6e 64 2f 6f 72 20 5b  CACHE], and/or [
212b0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d  SQLITE_OPEN_URI]
212c0 20 66 6c 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20   flags:)^.**.** 
212d0 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53  <dl>.** ^(<dt>[S
212e0 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
212f0 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  NLY]</dt>.** <dd
21300 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73  >The database is
21310 20 6f 70 65 6e 65 64 20 69 6e 20 72 65 61 64 2d   opened in read-
21320 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20 49 66 20 74  only mode.  If t
21330 68 65 20 64 61 74 61 62 61 73 65 20 64 6f 65 73  he database does
21340 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20   not.** already 
21350 65 78 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 20  exist, an error 
21360 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64  is returned.</dd
21370 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e  >)^.**.** ^(<dt>
21380 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
21390 44 57 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20  DWRITE]</dt>.** 
213a0 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65  <dd>The database
213b0 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72   is opened for r
213c0 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69  eading and writi
213d0 6e 67 20 69 66 20 70 6f 73 73 69 62 6c 65 2c 20  ng if possible, 
213e0 6f 72 20 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e  or reading.** on
213f0 6c 79 20 69 66 20 74 68 65 20 66 69 6c 65 20 69  ly if the file i
21400 73 20 77 72 69 74 65 20 70 72 6f 74 65 63 74 65  s write protecte
21410 64 20 62 79 20 74 68 65 20 6f 70 65 72 61 74 69  d by the operati
21420 6e 67 20 73 79 73 74 65 6d 2e 20 20 49 6e 20 65  ng system.  In e
21430 69 74 68 65 72 0a 2a 2a 20 63 61 73 65 20 74 68  ither.** case th
21440 65 20 64 61 74 61 62 61 73 65 20 6d 75 73 74 20  e database must 
21450 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20 6f  already exist, o
21460 74 68 65 72 77 69 73 65 20 61 6e 20 65 72 72 6f  therwise an erro
21470 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f  r is returned.</
21480 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64  dd>)^.**.** ^(<d
21490 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  t>[SQLITE_OPEN_R
214a0 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c  EADWRITE] | [SQL
214b0 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d  ITE_OPEN_CREATE]
214c0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
214d0 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
214e0 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20  ned for reading 
214f0 61 6e 64 20 77 72 69 74 69 6e 67 2c 20 61 6e 64  and writing, and
21500 20 69 73 20 63 72 65 61 74 65 64 20 69 66 0a 2a   is created if.*
21510 2a 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c  * it does not al
21520 72 65 61 64 79 20 65 78 69 73 74 2e 20 54 68 69  ready exist. Thi
21530 73 20 69 73 20 74 68 65 20 62 65 68 61 76 69 6f  s is the behavio
21540 72 20 74 68 61 74 20 69 73 20 61 6c 77 61 79 73  r that is always
21550 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 73 71 6c   used for.** sql
21560 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20  ite3_open() and 
21570 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
21580 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c  .</dd>)^.** </dl
21590 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33  >.**.** If the 3
215a0 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
215b0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
215c0 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20  ) is not one of 
215d0 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69  the.** combinati
215e0 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20  ons shown above 
215f0 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69  optionally combi
21600 6e 65 64 20 77 69 74 68 20 6f 74 68 65 72 0a 2a  ned with other.*
21610 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  * [SQLITE_OPEN_R
21620 45 41 44 4f 4e 4c 59 20 7c 20 53 51 4c 49 54 45  EADONLY | SQLITE
21630 5f 4f 50 45 4e 5f 2a 20 62 69 74 73 5d 0a 2a 2a  _OPEN_* bits].**
21640 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
21650 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  or is undefined.
21660 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b  .**.** ^If the [
21670 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55  SQLITE_OPEN_NOMU
21680 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74  TEX] flag is set
21690 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  , then the datab
216a0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
216b0 2a 20 6f 70 65 6e 73 20 69 6e 20 74 68 65 20 6d  * opens in the m
216c0 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72  ulti-thread [thr
216d0 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 73 20  eading mode] as 
216e0 6c 6f 6e 67 20 61 73 20 74 68 65 20 73 69 6e 67  long as the sing
216f0 6c 65 2d 74 68 72 65 61 64 0a 2a 2a 20 6d 6f 64  le-thread.** mod
21700 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 73  e has not been s
21710 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69  et at compile-ti
21720 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65  me or start-time
21730 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53  .  ^If the.** [S
21740 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d  QLITE_OPEN_FULLM
21750 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65  UTEX] flag is se
21760 74 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  t then the datab
21770 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f  ase connection o
21780 70 65 6e 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73  pens.** in the s
21790 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61  erialized [threa
217a0 64 69 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 73  ding mode] unles
217b0 73 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 20  s single-thread 
217c0 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c  was.** previousl
217d0 79 20 73 65 6c 65 63 74 65 64 20 61 74 20 63 6f  y selected at co
217e0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74  mpile-time or st
217f0 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68  art-time..** ^Th
21800 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53  e [SQLITE_OPEN_S
21810 48 41 52 45 44 43 41 43 48 45 5d 20 66 6c 61 67  HAREDCACHE] flag
21820 20 63 61 75 73 65 73 20 74 68 65 20 64 61 74 61   causes the data
21830 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
21840 74 6f 20 62 65 0a 2a 2a 20 65 6c 69 67 69 62 6c  to be.** eligibl
21850 65 20 74 6f 20 75 73 65 20 5b 73 68 61 72 65 64  e to use [shared
21860 20 63 61 63 68 65 20 6d 6f 64 65 5d 2c 20 72 65   cache mode], re
21870 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74  gardless of whet
21880 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65  her or not share
21890 64 0a 2a 2a 20 63 61 63 68 65 20 69 73 20 65 6e  d.** cache is en
218a0 61 62 6c 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  abled using [sql
218b0 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72  ite3_enable_shar
218c0 65 64 5f 63 61 63 68 65 28 29 5d 2e 20 20 5e 54  ed_cache()].  ^T
218d0 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  he.** [SQLITE_OP
218e0 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d  EN_PRIVATECACHE]
218f0 20 66 6c 61 67 20 63 61 75 73 65 73 20 74 68 65   flag causes the
21900 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
21910 74 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70  tion to not.** p
21920 61 72 74 69 63 69 70 61 74 65 20 69 6e 20 5b 73  articipate in [s
21930 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65  hared cache mode
21940 5d 20 65 76 65 6e 20 69 66 20 69 74 20 69 73 20  ] even if it is 
21950 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  enabled..**.** ^
21960 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  The fourth param
21970 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
21980 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 74 68 65  open_v2() is the
21990 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20   name of the.** 
219a0 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
219b0 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65  ject that define
219c0 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20  s the operating 
219d0 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65  system interface
219e0 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77   that.** the new
219f0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
21a00 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e  tion should use.
21a10 20 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68    ^If the fourth
21a20 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a   parameter is.**
21a30 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
21a40 74 68 65 6e 20 74 68 65 20 64 65 66 61 75 6c 74  then the default
21a50 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
21a60 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e 0a 2a  bject is used..*
21a70 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c  *.** ^If the fil
21a80 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72  ename is ":memor
21a90 79 3a 22 2c 20 74 68 65 6e 20 61 20 70 72 69 76  y:", then a priv
21aa0 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 20 69  ate, temporary i
21ab0 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73  n-memory databas
21ac0 65 0a 2a 2a 20 69 73 20 63 72 65 61 74 65 64 20  e.** is created 
21ad0 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 69  for the connecti
21ae0 6f 6e 2e 20 20 5e 54 68 69 73 20 69 6e 2d 6d 65  on.  ^This in-me
21af0 6d 6f 72 79 20 64 61 74 61 62 61 73 65 20 77 69  mory database wi
21b00 6c 6c 20 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a  ll vanish when.*
21b10 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  * the database c
21b20 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f  onnection is clo
21b30 73 65 64 2e 20 20 46 75 74 75 72 65 20 76 65 72  sed.  Future ver
21b40 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20  sions of SQLite 
21b50 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73  might.** make us
21b60 65 20 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c 20  e of additional 
21b70 73 70 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65  special filename
21b80 73 20 74 68 61 74 20 62 65 67 69 6e 20 77 69 74  s that begin wit
21b90 68 20 74 68 65 20 22 3a 22 20 63 68 61 72 61 63  h the ":" charac
21ba0 74 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65  ter..** It is re
21bb0 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 77  commended that w
21bc0 68 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 66  hen a database f
21bd0 69 6c 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79  ilename actually
21be0 20 64 6f 65 73 20 62 65 67 69 6e 20 77 69 74 68   does begin with
21bf0 0a 2a 2a 20 61 20 22 3a 22 20 63 68 61 72 61 63  .** a ":" charac
21c00 74 65 72 20 79 6f 75 20 73 68 6f 75 6c 64 20 70  ter you should p
21c10 72 65 66 69 78 20 74 68 65 20 66 69 6c 65 6e 61  refix the filena
21c20 6d 65 20 77 69 74 68 20 61 20 70 61 74 68 6e 61  me with a pathna
21c30 6d 65 20 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e  me such as.** ".
21c40 2f 22 20 74 6f 20 61 76 6f 69 64 20 61 6d 62 69  /" to avoid ambi
21c50 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  guity..**.** ^If
21c60 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73   the filename is
21c70 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
21c80 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65  , then a private
21c90 2c 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f  , temporary.** o
21ca0 6e 2d 64 69 73 6b 20 64 61 74 61 62 61 73 65 20  n-disk database 
21cb0 77 69 6c 6c 20 62 65 20 63 72 65 61 74 65 64 2e  will be created.
21cc0 20 20 5e 54 68 69 73 20 70 72 69 76 61 74 65 20    ^This private 
21cd0 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65  database will be
21ce0 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  .** automaticall
21cf0 79 20 64 65 6c 65 74 65 64 20 61 73 20 73 6f 6f  y deleted as soo
21d00 6e 20 61 73 20 74 68 65 20 64 61 74 61 62 61 73  n as the databas
21d10 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
21d20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b  closed..**.** [[
21d30 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 69 6e  URI filenames in
21d40 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d   sqlite3_open()]
21d50 5d 20 3c 68 33 3e 55 52 49 20 46 69 6c 65 6e 61  ] <h3>URI Filena
21d60 6d 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e  mes</h3>.**.** ^
21d70 49 66 20 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65  If [URI filename
21d80 5d 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e  ] interpretation
21d90 20 69 73 20 65 6e 61 62 6c 65 64 2c 20 61 6e 64   is enabled, and
21da0 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72   the filename ar
21db0 67 75 6d 65 6e 74 0a 2a 2a 20 62 65 67 69 6e 73  gument.** begins
21dc0 20 77 69 74 68 20 22 66 69 6c 65 3a 22 2c 20 74   with "file:", t
21dd0 68 65 6e 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  hen the filename
21de0 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20   is interpreted 
21df0 61 73 20 61 20 55 52 49 2e 20 5e 55 52 49 0a 2a  as a URI. ^URI.*
21e00 2a 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72  * filename inter
21e10 70 72 65 74 61 74 69 6f 6e 20 69 73 20 65 6e 61  pretation is ena
21e20 62 6c 65 64 20 69 66 20 74 68 65 20 5b 53 51 4c  bled if the [SQL
21e30 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c  ITE_OPEN_URI] fl
21e40 61 67 20 69 73 0a 2a 2a 20 73 65 74 20 69 6e 20  ag is.** set in 
21e50 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d  the fourth argum
21e60 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f  ent to sqlite3_o
21e70 70 65 6e 5f 76 32 28 29 2c 20 6f 72 20 69 66 20  pen_v2(), or if 
21e80 69 74 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 65  it has.** been e
21e90 6e 61 62 6c 65 64 20 67 6c 6f 62 61 6c 6c 79 20  nabled globally 
21ea0 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54  using the [SQLIT
21eb0 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 20 6f 70  E_CONFIG_URI] op
21ec0 74 69 6f 6e 20 77 69 74 68 20 74 68 65 0a 2a 2a  tion with the.**
21ed0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
21ee0 28 29 5d 20 6d 65 74 68 6f 64 20 6f 72 20 62 79  ()] method or by
21ef0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 55 53 45   the [SQLITE_USE
21f00 5f 55 52 49 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  _URI] compile-ti
21f10 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 41 73  me option..** As
21f20 20 6f 66 20 53 51 4c 69 74 65 20 76 65 72 73 69   of SQLite versi
21f30 6f 6e 20 33 2e 37 2e 37 2c 20 55 52 49 20 66 69  on 3.7.7, URI fi
21f40 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74  lename interpret
21f50 61 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20  ation is turned 
21f60 6f 66 66 0a 2a 2a 20 62 79 20 64 65 66 61 75 6c  off.** by defaul
21f70 74 2c 20 62 75 74 20 66 75 74 75 72 65 20 72 65  t, but future re
21f80 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65  leases of SQLite
21f90 20 6d 69 67 68 74 20 65 6e 61 62 6c 65 20 55 52   might enable UR
21fa0 49 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 69 6e  I filename.** in
21fb0 74 65 72 70 72 65 74 61 74 69 6f 6e 20 62 79 20  terpretation by 
21fc0 64 65 66 61 75 6c 74 2e 20 20 53 65 65 20 22 5b  default.  See "[
21fd0 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 5d 22 20  URI filenames]" 
21fe0 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  for additional.*
21ff0 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  * information..*
22000 2a 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d  *.** URI filenam
22010 65 73 20 61 72 65 20 70 61 72 73 65 64 20 61 63  es are parsed ac
22020 63 6f 72 64 69 6e 67 20 74 6f 20 52 46 43 20 33  cording to RFC 3
22030 39 38 36 2e 20 5e 49 66 20 74 68 65 20 55 52 49  986. ^If the URI
22040 20 63 6f 6e 74 61 69 6e 73 20 61 6e 0a 2a 2a 20   contains an.** 
22050 61 75 74 68 6f 72 69 74 79 2c 20 74 68 65 6e 20  authority, then 
22060 69 74 20 6d 75 73 74 20 62 65 20 65 69 74 68 65  it must be eithe
22070 72 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e  r an empty strin
22080 67 20 6f 72 20 74 68 65 20 73 74 72 69 6e 67 20  g or the string 
22090 0a 2a 2a 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2e  .** "localhost".
220a0 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72 69   ^If the authori
220b0 74 79 20 69 73 20 6e 6f 74 20 61 6e 20 65 6d 70  ty is not an emp
220c0 74 79 20 73 74 72 69 6e 67 20 6f 72 20 22 6c 6f  ty string or "lo
220d0 63 61 6c 68 6f 73 74 22 2c 20 61 6e 20 0a 2a 2a  calhost", an .**
220e0 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e   error is return
220f0 65 64 20 74 6f 20 74 68 65 20 63 61 6c 6c 65 72  ed to the caller
22100 2e 20 5e 54 68 65 20 66 72 61 67 6d 65 6e 74 20  . ^The fragment 
22110 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55  component of a U
22120 52 49 2c 20 69 66 20 0a 2a 2a 20 70 72 65 73 65  RI, if .** prese
22130 6e 74 2c 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a  nt, is ignored..
22140 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73  **.** ^SQLite us
22150 65 73 20 74 68 65 20 70 61 74 68 20 63 6f 6d 70  es the path comp
22160 6f 6e 65 6e 74 20 6f 66 20 74 68 65 20 55 52 49  onent of the URI
22170 20 61 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   as the name of 
22180 74 68 65 20 64 69 73 6b 20 66 69 6c 65 0a 2a 2a  the disk file.**
22190 20 77 68 69 63 68 20 63 6f 6e 74 61 69 6e 73 20   which contains 
221a0 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 5e 49  the database. ^I
221b0 66 20 74 68 65 20 70 61 74 68 20 62 65 67 69 6e  f the path begin
221c0 73 20 77 69 74 68 20 61 20 27 2f 27 20 63 68 61  s with a '/' cha
221d0 72 61 63 74 65 72 2c 20 0a 2a 2a 20 74 68 65 6e  racter, .** then
221e0 20 69 74 20 69 73 20 69 6e 74 65 72 70 72 65 74   it is interpret
221f0 65 64 20 61 73 20 61 6e 20 61 62 73 6f 6c 75 74  ed as an absolut
22200 65 20 70 61 74 68 2e 20 5e 49 66 20 74 68 65 20  e path. ^If the 
22210 70 61 74 68 20 64 6f 65 73 20 6e 6f 74 20 62 65  path does not be
22220 67 69 6e 20 0a 2a 2a 20 77 69 74 68 20 61 20 27  gin .** with a '
22230 2f 27 20 28 6d 65 61 6e 69 6e 67 20 74 68 61 74  /' (meaning that
22240 20 74 68 65 20 61 75 74 68 6f 72 69 74 79 20 73   the authority s
22250 65 63 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65  ection is omitte
22260 64 20 66 72 6f 6d 20 74 68 65 20 55 52 49 29 0a  d from the URI).
22270 2a 2a 20 74 68 65 6e 20 74 68 65 20 70 61 74 68  ** then the path
22280 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20   is interpreted 
22290 61 73 20 61 20 72 65 6c 61 74 69 76 65 20 70 61  as a relative pa
222a0 74 68 2e 20 0a 2a 2a 20 5e 4f 6e 20 77 69 6e 64  th. .** ^On wind
222b0 6f 77 73 2c 20 74 68 65 20 66 69 72 73 74 20 63  ows, the first c
222c0 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 6e 20 61  omponent of an a
222d0 62 73 6f 6c 75 74 65 20 70 61 74 68 20 0a 2a 2a  bsolute path .**
222e0 20 69 73 20 61 20 64 72 69 76 65 20 73 70 65 63   is a drive spec
222f0 69 66 69 63 61 74 69 6f 6e 20 28 65 2e 67 2e 20  ification (e.g. 
22300 22 43 3a 22 29 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 63  "C:")..**.** [[c
22310 6f 72 65 20 55 52 49 20 71 75 65 72 79 20 70 61  ore URI query pa
22320 72 61 6d 65 74 65 72 73 5d 5d 0a 2a 2a 20 54 68  rameters]].** Th
22330 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e  e query componen
22340 74 20 6f 66 20 61 20 55 52 49 20 6d 61 79 20 63  t of a URI may c
22350 6f 6e 74 61 69 6e 20 70 61 72 61 6d 65 74 65 72  ontain parameter
22360 73 20 74 68 61 74 20 61 72 65 20 69 6e 74 65 72  s that are inter
22370 70 72 65 74 65 64 0a 2a 2a 20 65 69 74 68 65 72  preted.** either
22380 20 62 79 20 53 51 4c 69 74 65 20 69 74 73 65 6c   by SQLite itsel
22390 66 2c 20 6f 72 20 62 79 20 61 20 5b 56 46 53 20  f, or by a [VFS 
223a0 7c 20 63 75 73 74 6f 6d 20 56 46 53 20 69 6d 70  | custom VFS imp
223b0 6c 65 6d 65 6e 74 61 74 69 6f 6e 5d 2e 0a 2a 2a  lementation]..**
223c0 20 53 51 4c 69 74 65 20 69 6e 74 65 72 70 72 65   SQLite interpre
223d0 74 73 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  ts the following
223e0 20 74 68 72 65 65 20 71 75 65 72 79 20 70 61 72   three query par
223f0 61 6d 65 74 65 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ameters:.**.** <
22400 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62  ul>.**   <li> <b
22410 3e 76 66 73 3c 2f 62 3e 3a 20 5e 54 68 65 20 22  >vfs</b>: ^The "
22420 76 66 73 22 20 70 61 72 61 6d 65 74 65 72 20 6d  vfs" parameter m
22430 61 79 20 62 65 20 75 73 65 64 20 74 6f 20 73 70  ay be used to sp
22440 65 63 69 66 79 20 74 68 65 20 6e 61 6d 65 20 6f  ecify the name o
22450 66 0a 2a 2a 20 20 20 20 20 61 20 56 46 53 20 6f  f.**     a VFS o
22460 62 6a 65 63 74 20 74 68 61 74 20 70 72 6f 76 69  bject that provi
22470 64 65 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e  des the operatin
22480 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61  g system interfa
22490 63 65 20 74 68 61 74 20 73 68 6f 75 6c 64 0a 2a  ce that should.*
224a0 2a 20 20 20 20 20 62 65 20 75 73 65 64 20 74 6f  *     be used to
224b0 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74 61   access the data
224c0 62 61 73 65 20 66 69 6c 65 20 6f 6e 20 64 69 73  base file on dis
224d0 6b 2e 20 5e 49 66 20 74 68 69 73 20 6f 70 74 69  k. ^If this opti
224e0 6f 6e 20 69 73 20 73 65 74 20 74 6f 0a 2a 2a 20  on is set to.** 
224f0 20 20 20 20 61 6e 20 65 6d 70 74 79 20 73 74 72      an empty str
22500 69 6e 67 20 74 68 65 20 64 65 66 61 75 6c 74 20  ing the default 
22510 56 46 53 20 6f 62 6a 65 63 74 20 69 73 20 75 73  VFS object is us
22520 65 64 2e 20 5e 53 70 65 63 69 66 79 69 6e 67 20  ed. ^Specifying 
22530 61 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20 20  an unknown.**   
22540 20 20 56 46 53 20 69 73 20 61 6e 20 65 72 72 6f    VFS is an erro
22550 72 2e 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f  r. ^If sqlite3_o
22560 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64  pen_v2() is used
22570 20 61 6e 64 20 74 68 65 20 76 66 73 20 6f 70 74   and the vfs opt
22580 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 70 72  ion is.**     pr
22590 65 73 65 6e 74 2c 20 74 68 65 6e 20 74 68 65 20  esent, then the 
225a0 56 46 53 20 73 70 65 63 69 66 69 65 64 20 62 79  VFS specified by
225b0 20 74 68 65 20 6f 70 74 69 6f 6e 20 74 61 6b 65   the option take
225c0 73 20 70 72 65 63 65 64 65 6e 63 65 20 6f 76 65  s precedence ove
225d0 72 0a 2a 2a 20 20 20 20 20 74 68 65 20 76 61 6c  r.**     the val
225e0 75 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  ue passed as the
225f0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
22600 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65  r to sqlite3_ope
22610 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20  n_v2()..**.**   
22620 3c 6c 69 3e 20 3c 62 3e 6d 6f 64 65 3c 2f 62 3e  <li> <b>mode</b>
22630 3a 20 5e 28 54 68 65 20 6d 6f 64 65 20 70 61 72  : ^(The mode par
22640 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73 65  ameter may be se
22650 74 20 74 6f 20 65 69 74 68 65 72 20 22 72 6f 22  t to either "ro"
22660 2c 20 22 72 77 22 20 6f 72 0a 2a 2a 20 20 20 20  , "rw" or.**    
22670 20 22 72 77 63 22 2e 20 41 74 74 65 6d 70 74 69   "rwc". Attempti
22680 6e 67 20 74 6f 20 73 65 74 20 69 74 20 74 6f 20  ng to set it to 
22690 61 6e 79 20 6f 74 68 65 72 20 76 61 6c 75 65 20  any other value 
226a0 69 73 20 61 6e 20 65 72 72 6f 72 29 5e 2e 20 0a  is an error)^. .
226b0 2a 2a 20 20 20 20 20 5e 49 66 20 22 72 6f 22 20  **     ^If "ro" 
226c0 69 73 20 73 70 65 63 69 66 69 65 64 2c 20 74 68  is specified, th
226d0 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
226e0 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65  is opened for re
226f0 61 64 2d 6f 6e 6c 79 20 0a 2a 2a 20 20 20 20 20  ad-only .**     
22700 61 63 63 65 73 73 2c 20 6a 75 73 74 20 61 73 20  access, just as 
22710 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  if the [SQLITE_O
22720 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20 66 6c  PEN_READONLY] fl
22730 61 67 20 68 61 64 20 62 65 65 6e 20 73 65 74 20  ag had been set 
22740 69 6e 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 74  in the .**     t
22750 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  hird argument to
22760 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
22770 5f 76 32 28 29 2e 20 5e 49 66 20 74 68 65 20 6d  _v2(). ^If the m
22780 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 20 73 65  ode option is se
22790 74 20 74 6f 20 0a 2a 2a 20 20 20 20 20 22 72 77  t to .**     "rw
227a0 22 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61  ", then the data
227b0 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66  base is opened f
227c0 6f 72 20 72 65 61 64 2d 77 72 69 74 65 20 28 62  or read-write (b
227d0 75 74 20 6e 6f 74 20 63 72 65 61 74 65 29 20 0a  ut not create) .
227e0 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c 20 61  **     access, a
227f0 73 20 69 66 20 53 51 4c 49 54 45 5f 4f 50 45 4e  s if SQLITE_OPEN
22800 5f 52 45 41 44 57 52 49 54 45 20 28 62 75 74 20  _READWRITE (but 
22810 6e 6f 74 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  not SQLITE_OPEN_
22820 43 52 45 41 54 45 29 20 68 61 64 20 0a 2a 2a 20  CREATE) had .** 
22830 20 20 20 20 62 65 65 6e 20 73 65 74 2e 20 5e 56      been set. ^V
22840 61 6c 75 65 20 22 72 77 63 22 20 69 73 20 65 71  alue "rwc" is eq
22850 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74  uivalent to sett
22860 69 6e 67 20 62 6f 74 68 20 0a 2a 2a 20 20 20 20  ing both .**    
22870 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41   SQLITE_OPEN_REA
22880 44 57 52 49 54 45 20 61 6e 64 20 53 51 4c 49 54  DWRITE and SQLIT
22890 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2e 20 5e  E_OPEN_CREATE. ^
228a0 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  If sqlite3_open_
228b0 76 32 28 29 20 69 73 20 0a 2a 2a 20 20 20 20 20  v2() is .**     
228c0 75 73 65 64 2c 20 69 74 20 69 73 20 61 6e 20 65  used, it is an e
228d0 72 72 6f 72 20 74 6f 20 73 70 65 63 69 66 79 20  rror to specify 
228e0 61 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20  a value for the 
228f0 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 72 20 74  mode parameter t
22900 68 61 74 20 69 73 20 0a 2a 2a 20 20 20 20 20 6c  hat is .**     l
22910 65 73 73 20 72 65 73 74 72 69 63 74 69 76 65 20  ess restrictive 
22920 74 68 61 6e 20 74 68 61 74 20 73 70 65 63 69 66  than that specif
22930 69 65 64 20 62 79 20 74 68 65 20 66 6c 61 67 73  ied by the flags
22940 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 74   passed as the t
22950 68 69 72 64 20 0a 2a 2a 20 20 20 20 20 70 61 72  hird .**     par
22960 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 20 20  ameter..**.**   
22970 3c 6c 69 3e 20 3c 62 3e 63 61 63 68 65 3c 2f 62  <li> <b>cache</b
22980 3e 3a 20 5e 54 68 65 20 63 61 63 68 65 20 70 61  >: ^The cache pa
22990 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73  rameter may be s
229a0 65 74 20 74 6f 20 65 69 74 68 65 72 20 22 73 68  et to either "sh
229b0 61 72 65 64 22 20 6f 72 0a 2a 2a 20 20 20 20 20  ared" or.**     
229c0 22 70 72 69 76 61 74 65 22 2e 20 5e 53 65 74 74  "private". ^Sett
229d0 69 6e 67 20 69 74 20 74 6f 20 22 73 68 61 72 65  ing it to "share
229e0 64 22 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74  d" is equivalent
229f0 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65 0a   to setting the.
22a00 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50  **     SQLITE_OP
22a10 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 62  EN_SHAREDCACHE b
22a20 69 74 20 69 6e 20 74 68 65 20 66 6c 61 67 73 20  it in the flags 
22a30 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20  argument passed 
22a40 74 6f 0a 2a 2a 20 20 20 20 20 73 71 6c 69 74 65  to.**     sqlite
22a50 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 53 65  3_open_v2(). ^Se
22a60 74 74 69 6e 67 20 74 68 65 20 63 61 63 68 65 20  tting the cache 
22a70 70 61 72 61 6d 65 74 65 72 20 74 6f 20 22 70 72  parameter to "pr
22a80 69 76 61 74 65 22 20 69 73 20 0a 2a 2a 20 20 20  ivate" is .**   
22a90 20 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20    equivalent to 
22aa0 73 65 74 74 69 6e 67 20 74 68 65 20 53 51 4c 49  setting the SQLI
22ab0 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43  TE_OPEN_PRIVATEC
22ac0 41 43 48 45 20 62 69 74 2e 0a 2a 2a 20 20 20 20  ACHE bit..**    
22ad0 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65   ^If sqlite3_ope
22ae0 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64 20 61  n_v2() is used a
22af0 6e 64 20 74 68 65 20 22 63 61 63 68 65 22 20 70  nd the "cache" p
22b00 61 72 61 6d 65 74 65 72 20 69 73 20 70 72 65 73  arameter is pres
22b10 65 6e 74 20 69 6e 0a 2a 2a 20 20 20 20 20 61 20  ent in.**     a 
22b20 55 52 49 20 66 69 6c 65 6e 61 6d 65 2c 20 69 74  URI filename, it
22b30 73 20 76 61 6c 75 65 20 6f 76 65 72 72 69 64 65  s value override
22b40 73 20 61 6e 79 20 62 65 68 61 76 69 6f 75 72 20  s any behaviour 
22b50 72 65 71 75 65 73 74 65 64 20 62 79 20 73 65 74  requested by set
22b60 74 69 6e 67 0a 2a 2a 20 20 20 20 20 53 51 4c 49  ting.**     SQLI
22b70 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43  TE_OPEN_PRIVATEC
22b80 41 43 48 45 20 6f 72 20 53 51 4c 49 54 45 5f 4f  ACHE or SQLITE_O
22b90 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20  PEN_SHAREDCACHE 
22ba0 66 6c 61 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  flag..** </ul>.*
22bb0 2a 0a 2a 2a 20 5e 53 70 65 63 69 66 79 69 6e 67  *.** ^Specifying
22bc0 20 61 6e 20 75 6e 6b 6e 6f 77 6e 20 70 61 72 61   an unknown para
22bd0 6d 65 74 65 72 20 69 6e 20 74 68 65 20 71 75 65  meter in the que
22be0 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20  ry component of 
22bf0 61 20 55 52 49 20 69 73 20 6e 6f 74 20 61 6e 0a  a URI is not an.
22c00 2a 2a 20 65 72 72 6f 72 2e 20 20 46 75 74 75 72  ** error.  Futur
22c10 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
22c20 4c 69 74 65 20 6d 69 67 68 74 20 75 6e 64 65 72  Lite might under
22c30 73 74 61 6e 64 20 61 64 64 69 74 69 6f 6e 61 6c  stand additional
22c40 20 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65   query.** parame
22c50 74 65 72 73 2e 20 20 53 65 65 20 22 5b 71 75 65  ters.  See "[que
22c60 72 79 20 70 61 72 61 6d 65 74 65 72 73 20 77 69  ry parameters wi
22c70 74 68 20 73 70 65 63 69 61 6c 20 6d 65 61 6e 69  th special meani
22c80 6e 67 20 74 6f 20 53 51 4c 69 74 65 5d 22 20 66  ng to SQLite]" f
22c90 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c  or.** additional
22ca0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a   information..**
22cb0 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61  .** [[URI filena
22cc0 6d 65 20 65 78 61 6d 70 6c 65 73 5d 5d 20 3c 68  me examples]] <h
22cd0 33 3e 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 65  3>URI filename e
22ce0 78 61 6d 70 6c 65 73 3c 2f 68 33 3e 0a 2a 2a 0a  xamples</h3>.**.
22cf0 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72  ** <table border
22d00 3d 22 31 22 20 61 6c 69 67 6e 3d 63 65 6e 74 65  ="1" align=cente
22d10 72 20 63 65 6c 6c 70 61 64 64 69 6e 67 3d 35 3e  r cellpadding=5>
22d20 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 55 52 49  .** <tr><th> URI
22d30 20 66 69 6c 65 6e 61 6d 65 73 20 3c 74 68 3e 20   filenames <th> 
22d40 52 65 73 75 6c 74 73 0a 2a 2a 20 3c 74 72 3e 3c  Results.** <tr><
22d50 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62  td> file:data.db
22d60 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20   <td> .**       
22d70 20 20 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65     Open the file
22d80 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68   "data.db" in th
22d90 65 20 63 75 72 72 65 6e 74 20 64 69 72 65 63 74  e current direct
22da0 6f 72 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  ory..** <tr><td>
22db0 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64   file:/home/fred
22dc0 2f 64 61 74 61 2e 64 62 3c 62 72 3e 0a 2a 2a 20  /data.db<br>.** 
22dd0 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f           file://
22de0 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e  /home/fred/data.
22df0 64 62 20 3c 62 72 3e 20 0a 2a 2a 20 20 20 20 20  db <br> .**     
22e00 20 20 20 20 20 66 69 6c 65 3a 2f 2f 6c 6f 63 61       file://loca
22e10 6c 68 6f 73 74 2f 68 6f 6d 65 2f 66 72 65 64 2f  lhost/home/fred/
22e20 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 3c 74 64  data.db <br> <td
22e30 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f  > .**          O
22e40 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  pen the database
22e50 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65   file "/home/fre
22e60 64 2f 64 61 74 61 2e 64 62 22 2e 0a 2a 2a 20 3c  d/data.db"..** <
22e70 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 2f 64  tr><td> file://d
22e80 61 72 6b 73 74 61 72 2f 68 6f 6d 65 2f 66 72 65  arkstar/home/fre
22e90 64 2f 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a  d/data.db <td> .
22ea0 2a 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20 65  **          An e
22eb0 72 72 6f 72 2e 20 22 64 61 72 6b 73 74 61 72 22  rror. "darkstar"
22ec0 20 69 73 20 6e 6f 74 20 61 20 72 65 63 6f 67 6e   is not a recogn
22ed0 69 7a 65 64 20 61 75 74 68 6f 72 69 74 79 2e 0a  ized authority..
22ee0 2a 2a 20 3c 74 72 3e 3c 74 64 20 73 74 79 6c 65  ** <tr><td style
22ef0 3d 22 77 68 69 74 65 2d 73 70 61 63 65 3a 6e 6f  ="white-space:no
22f00 77 72 61 70 22 3e 20 0a 2a 2a 20 20 20 20 20 20  wrap"> .**      
22f10 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 43 3a 2f 44      file:///C:/D
22f20 6f 63 75 6d 65 6e 74 73 25 32 30 61 6e 64 25 32  ocuments%20and%2
22f30 30 53 65 74 74 69 6e 67 73 2f 66 72 65 64 2f 44  0Settings/fred/D
22f40 65 73 6b 74 6f 70 2f 64 61 74 61 2e 64 62 0a 2a  esktop/data.db.*
22f50 2a 20 20 20 20 20 3c 74 64 3e 20 57 69 6e 64 6f  *     <td> Windo
22f60 77 73 20 6f 6e 6c 79 3a 20 4f 70 65 6e 20 74 68  ws only: Open th
22f70 65 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22  e file "data.db"
22f80 20 6f 6e 20 66 72 65 64 27 73 20 64 65 73 6b 74   on fred's deskt
22f90 6f 70 20 6f 6e 20 64 72 69 76 65 0a 2a 2a 20 20  op on drive.**  
22fa0 20 20 20 20 20 20 20 20 43 3a 2e 20 4e 6f 74 65          C:. Note
22fb0 20 74 68 61 74 20 74 68 65 20 25 32 30 20 65 73   that the %20 es
22fc0 63 61 70 69 6e 67 20 69 6e 20 74 68 69 73 20 65  caping in this e
22fd0 78 61 6d 70 6c 65 20 69 73 20 6e 6f 74 20 73 74  xample is not st
22fe0 72 69 63 74 6c 79 20 0a 2a 2a 20 20 20 20 20 20  rictly .**      
22ff0 20 20 20 20 6e 65 63 65 73 73 61 72 79 20 2d 20      necessary - 
23000 73 70 61 63 65 20 63 68 61 72 61 63 74 65 72 73  space characters
23010 20 63 61 6e 20 62 65 20 75 73 65 64 20 6c 69 74   can be used lit
23020 65 72 61 6c 6c 79 0a 2a 2a 20 20 20 20 20 20 20  erally.**       
23030 20 20 20 69 6e 20 55 52 49 20 66 69 6c 65 6e 61     in URI filena
23040 6d 65 73 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  mes..** <tr><td>
23050 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f   file:data.db?mo
23060 64 65 3d 72 6f 26 63 61 63 68 65 3d 70 72 69 76  de=ro&cache=priv
23070 61 74 65 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20  ate <td> .**    
23080 20 20 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 20        Open file 
23090 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65  "data.db" in the
230a0 20 63 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f   current directo
230b0 72 79 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79  ry for read-only
230c0 20 61 63 63 65 73 73 2e 0a 2a 2a 20 20 20 20 20   access..**     
230d0 20 20 20 20 20 52 65 67 61 72 64 6c 65 73 73 20       Regardless 
230e0 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  of whether or no
230f0 74 20 73 68 61 72 65 64 2d 63 61 63 68 65 20 6d  t shared-cache m
23100 6f 64 65 20 69 73 20 65 6e 61 62 6c 65 64 20 62  ode is enabled b
23110 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 65  y.**          de
23120 66 61 75 6c 74 2c 20 75 73 65 20 61 20 70 72 69  fault, use a pri
23130 76 61 74 65 20 63 61 63 68 65 2e 0a 2a 2a 20 3c  vate cache..** <
23140 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f  tr><td> file:/ho
23150 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 3f  me/fred/data.db?
23160 76 66 73 3d 75 6e 69 78 2d 6e 6f 6c 6f 63 6b 20  vfs=unix-nolock 
23170 3c 74 64 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20  <td>.**         
23180 20 4f 70 65 6e 20 66 69 6c 65 20 22 2f 68 6f 6d   Open file "/hom
23190 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 22 2e  e/fred/data.db".
231a0 20 55 73 65 20 74 68 65 20 73 70 65 63 69 61 6c   Use the special
231b0 20 56 46 53 20 22 75 6e 69 78 2d 6e 6f 6c 6f 63   VFS "unix-noloc
231c0 6b 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  k"..** <tr><td> 
231d0 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64  file:data.db?mod
231e0 65 3d 72 65 61 64 6f 6e 6c 79 20 3c 74 64 3e 20  e=readonly <td> 
231f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20  .**          An 
23200 65 72 72 6f 72 2e 20 22 72 65 61 64 6f 6e 6c 79  error. "readonly
23210 22 20 69 73 20 6e 6f 74 20 61 20 76 61 6c 69 64  " is not a valid
23220 20 6f 70 74 69 6f 6e 20 66 6f 72 20 74 68 65 20   option for the 
23230 22 6d 6f 64 65 22 20 70 61 72 61 6d 65 74 65 72  "mode" parameter
23240 2e 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a  ..** </table>.**
23250 0a 2a 2a 20 5e 55 52 49 20 68 65 78 61 64 65 63  .** ^URI hexadec
23260 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71 75  imal escape sequ
23270 65 6e 63 65 73 20 28 25 48 48 29 20 61 72 65 20  ences (%HH) are 
23280 73 75 70 70 6f 72 74 65 64 20 77 69 74 68 69 6e  supported within
23290 20 74 68 65 20 70 61 74 68 20 61 6e 64 0a 2a 2a   the path and.**
232a0 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74   query component
232b0 73 20 6f 66 20 61 20 55 52 49 2e 20 41 20 68 65  s of a URI. A he
232c0 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65  xadecimal escape
232d0 20 73 65 71 75 65 6e 63 65 20 63 6f 6e 73 69 73   sequence consis
232e0 74 73 20 6f 66 20 61 0a 2a 2a 20 70 65 72 63 65  ts of a.** perce
232f0 6e 74 20 73 69 67 6e 20 2d 20 22 25 22 20 2d 20  nt sign - "%" - 
23300 66 6f 6c 6c 6f 77 65 64 20 62 79 20 65 78 61 63  followed by exac
23310 74 6c 79 20 74 77 6f 20 68 65 78 61 64 65 63 69  tly two hexadeci
23320 6d 61 6c 20 64 69 67 69 74 73 20 0a 2a 2a 20 73  mal digits .** s
23330 70 65 63 69 66 79 69 6e 67 20 61 6e 20 6f 63 74  pecifying an oct
23340 65 74 20 76 61 6c 75 65 2e 20 5e 42 65 66 6f 72  et value. ^Befor
23350 65 20 74 68 65 20 70 61 74 68 20 6f 72 20 71 75  e the path or qu
23360 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f  ery components o
23370 66 20 61 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e  f a.** URI filen
23380 61 6d 65 20 61 72 65 20 69 6e 74 65 72 70 72 65  ame are interpre
23390 74 65 64 2c 20 74 68 65 79 20 61 72 65 20 65 6e  ted, they are en
233a0 63 6f 64 65 64 20 75 73 69 6e 67 20 55 54 46 2d  coded using UTF-
233b0 38 20 61 6e 64 20 61 6c 6c 20 0a 2a 2a 20 68 65  8 and all .** he
233c0 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65  xadecimal escape
233d0 20 73 65 71 75 65 6e 63 65 73 20 72 65 70 6c 61   sequences repla
233e0 63 65 64 20 62 79 20 61 20 73 69 6e 67 6c 65 20  ced by a single 
233f0 62 79 74 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20  byte containing 
23400 74 68 65 0a 2a 2a 20 63 6f 72 72 65 73 70 6f 6e  the.** correspon
23410 64 69 6e 67 20 6f 63 74 65 74 2e 20 49 66 20 74  ding octet. If t
23420 68 69 73 20 70 72 6f 63 65 73 73 20 67 65 6e 65  his process gene
23430 72 61 74 65 73 20 61 6e 20 69 6e 76 61 6c 69 64  rates an invalid
23440 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 2c   UTF-8 encoding,
23450 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 73 20  .** the results 
23460 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  are undefined..*
23470 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20  *.** <b>Note to 
23480 57 69 6e 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f  Windows users:</
23490 62 3e 20 20 54 68 65 20 65 6e 63 6f 64 69 6e 67  b>  The encoding
234a0 20 75 73 65 64 20 66 6f 72 20 74 68 65 20 66 69   used for the fi
234b0 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a  lename argument.
234c0 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 70  ** of sqlite3_op
234d0 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  en() and sqlite3
234e0 5f 6f 70 65 6e 5f 76 32 28 29 20 6d 75 73 74 20  _open_v2() must 
234f0 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68  be UTF-8, not wh
23500 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61  atever.** codepa
23510 67 65 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20  ge is currently 
23520 64 65 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61  defined.  Filena
23530 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69  mes containing i
23540 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20  nternational.** 
23550 63 68 61 72 61 63 74 65 72 73 20 6d 75 73 74 20  characters must 
23560 62 65 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20  be converted to 
23570 55 54 46 2d 38 20 70 72 69 6f 72 20 74 6f 20 70  UTF-8 prior to p
23580 61 73 73 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f  assing them into
23590 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  .** sqlite3_open
235a0 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  () or sqlite3_op
235b0 65 6e 5f 76 32 28 29 2e 0a 2a 2f 0a 53 51 4c 49  en_v2()..*/.SQLI
235c0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
235d0 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 74  e3_open(.  const
235e0 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c   char *filename,
235f0 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66     /* Database f
23600 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20  ilename (UTF-8) 
23610 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70  */.  sqlite3 **p
23620 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20  pDb          /* 
23630 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68  OUT: SQLite db h
23640 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 53 51 4c 49  andle */.);.SQLI
23650 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
23660 65 33 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e  e3_open16(.  con
23670 73 74 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d  st void *filenam
23680 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  e,   /* Database
23690 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31   filename (UTF-1
236a0 36 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20  6) */.  sqlite3 
236b0 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20  **ppDb          
236c0 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64  /* OUT: SQLite d
236d0 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 53  b handle */.);.S
236e0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
236f0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 0a 20  lite3_open_v2(. 
23700 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c   const char *fil
23710 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61  ename,   /* Data
23720 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55  base filename (U
23730 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74  TF-8) */.  sqlit
23740 65 33 20 2a 2a 70 70 44 62 2c 20 20 20 20 20 20  e3 **ppDb,      
23750 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74     /* OUT: SQLit
23760 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  e db handle */. 
23770 20 69 6e 74 20 66 6c 61 67 73 2c 20 20 20 20 20   int flags,     
23780 20 20 20 20 20 20 20 20 20 2f 2a 20 46 6c 61 67           /* Flag
23790 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  s */.  const cha
237a0 72 20 2a 7a 56 66 73 20 20 20 20 20 20 20 20 2f  r *zVfs        /
237b0 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53 20 6d 6f  * Name of VFS mo
237c0 64 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f 0a 29  dule to use */.)
237d0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
237e0 46 3a 20 4f 62 74 61 69 6e 20 56 61 6c 75 65 73  F: Obtain Values
237f0 20 46 6f 72 20 55 52 49 20 50 61 72 61 6d 65 74   For URI Paramet
23800 65 72 73 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69  ers.**.** This i
23810 73 20 61 20 75 74 69 6c 69 74 79 20 72 6f 75 74  s a utility rout
23820 69 6e 65 2c 20 75 73 65 66 75 6c 20 74 6f 20 56  ine, useful to V
23830 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
23840 6e 73 2c 20 74 68 61 74 20 63 68 65 63 6b 73 0a  ns, that checks.
23850 2a 2a 20 74 6f 20 73 65 65 20 69 66 20 61 20 64  ** to see if a d
23860 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 61 73  atabase file was
23870 20 61 20 55 52 49 20 74 68 61 74 20 63 6f 6e 74   a URI that cont
23880 61 69 6e 65 64 20 61 20 73 70 65 63 69 66 69 63  ained a specific
23890 20 71 75 65 72 79 20 0a 2a 2a 20 70 61 72 61 6d   query .** param
238a0 65 74 65 72 2c 20 61 6e 64 20 69 66 20 73 6f 20  eter, and if so 
238b0 6f 62 74 61 69 6e 73 20 74 68 65 20 76 61 6c 75  obtains the valu
238c0 65 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 70  e of the query p
238d0 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
238e0 54 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 61 72  The zFilename ar
238f0 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 66 69  gument is the fi
23900 6c 65 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 70  lename pointer p
23910 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78  assed into the x
23920 4f 70 65 6e 28 29 0a 2a 2a 20 6d 65 74 68 6f 64  Open().** method
23930 20 6f 66 20 61 20 56 46 53 20 69 6d 70 6c 65 6d   of a VFS implem
23940 65 6e 74 61 74 69 6f 6e 2e 20 20 54 68 65 20 7a  entation.  The z
23950 50 61 72 61 6d 20 61 72 67 75 6d 65 6e 74 20 69  Param argument i
23960 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
23970 65 0a 2a 2a 20 71 75 65 72 79 20 70 61 72 61 6d  e.** query param
23980 65 74 65 72 20 77 65 20 73 65 65 6b 2e 20 20 54  eter we seek.  T
23990 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75  his routine retu
239a0 72 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66  rns the value of
239b0 20 74 68 65 20 7a 50 61 72 61 6d 0a 2a 2a 20 70   the zParam.** p
239c0 61 72 61 6d 65 74 65 72 20 69 66 20 69 74 20 65  arameter if it e
239d0 78 69 73 74 73 2e 20 20 49 66 20 74 68 65 20 70  xists.  If the p
239e0 61 72 61 6d 65 74 65 72 20 64 6f 65 73 20 6e 6f  arameter does no
239f0 74 20 65 78 69 73 74 2c 20 74 68 69 73 20 72 6f  t exist, this ro
23a00 75 74 69 6e 65 0a 2a 2a 20 72 65 74 75 72 6e 73  utine.** returns
23a10 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
23a20 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 7a 46  .**.** If the zF
23a30 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74  ilename argument
23a40 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f   to this functio
23a50 6e 20 69 73 20 6e 6f 74 20 61 20 70 6f 69 6e 74  n is not a point
23a60 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 0a 2a  er that SQLite.*
23a70 2a 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68  * passed into th
23a80 65 20 78 4f 70 65 6e 20 56 46 53 20 6d 65 74 68  e xOpen VFS meth
23a90 6f 64 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68  od, then the beh
23aa0 61 76 69 6f 72 20 6f 66 20 74 68 69 73 20 72 6f  avior of this ro
23ab0 75 74 69 6e 65 0a 2a 2a 20 69 73 20 75 6e 64 65  utine.** is unde
23ac0 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62  fined and probab
23ad0 6c 79 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a  ly undesirable..
23ae0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  */.SQLITE_API co
23af0 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
23b00 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28  3_uri_parameter(
23b10 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c  const char *zFil
23b20 65 6e 61 6d 65 2c 20 63 6f 6e 73 74 20 63 68 61  ename, const cha
23b30 72 20 2a 7a 50 61 72 61 6d 29 3b 0a 0a 0a 2f 2a  r *zParam);.../*
23b40 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 72  .** CAPI3REF: Er
23b50 72 6f 72 20 43 6f 64 65 73 20 41 6e 64 20 4d 65  ror Codes And Me
23b60 73 73 61 67 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  ssages.**.** ^Th
23b70 65 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64  e sqlite3_errcod
23b80 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  e() interface re
23b90 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 69  turns the numeri
23ba0 63 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20  c [result code] 
23bb0 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  or.** [extended 
23bc0 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72  result code] for
23bd0 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
23be0 20 66 61 69 6c 65 64 20 73 71 6c 69 74 65 33 5f   failed sqlite3_
23bf0 2a 20 41 50 49 20 63 61 6c 6c 0a 2a 2a 20 61 73  * API call.** as
23c00 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20  sociated with a 
23c10 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
23c20 74 69 6f 6e 5d 2e 20 49 66 20 61 20 70 72 69 6f  tion]. If a prio
23c30 72 20 41 50 49 20 63 61 6c 6c 20 66 61 69 6c 65  r API call faile
23c40 64 0a 2a 2a 20 62 75 74 20 74 68 65 20 6d 6f 73  d.** but the mos
23c50 74 20 72 65 63 65 6e 74 20 41 50 49 20 63 61 6c  t recent API cal
23c60 6c 20 73 75 63 63 65 65 64 65 64 2c 20 74 68 65  l succeeded, the
23c70 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72   return value fr
23c80 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 72  om.** sqlite3_er
23c90 72 63 6f 64 65 28 29 20 69 73 20 75 6e 64 65 66  rcode() is undef
23ca0 69 6e 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69  ined.  ^The sqli
23cb0 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72  te3_extended_err
23cc0 63 6f 64 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66  code().** interf
23cd0 61 63 65 20 69 73 20 74 68 65 20 73 61 6d 65 20  ace is the same 
23ce0 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61  except that it a
23cf0 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 74 68  lways returns th
23d00 65 20 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  e .** [extended 
23d10 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 65 76 65  result code] eve
23d20 6e 20 77 68 65 6e 20 65 78 74 65 6e 64 65 64 20  n when extended 
23d30 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65  result codes are
23d40 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a  .** disabled..**
23d50 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
23d60 5f 65 72 72 6d 73 67 28 29 20 61 6e 64 20 73 71  _errmsg() and sq
23d70 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29  lite3_errmsg16()
23d80 20 72 65 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d   return English-
23d90 6c 61 6e 67 75 61 67 65 0a 2a 2a 20 74 65 78 74  language.** text
23da0 20 74 68 61 74 20 64 65 73 63 72 69 62 65 73 20   that describes 
23db0 74 68 65 20 65 72 72 6f 72 2c 20 61 73 20 65 69  the error, as ei
23dc0 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54  ther UTF-8 or UT
23dd0 46 2d 31 36 20 72 65 73 70 65 63 74 69 76 65 6c  F-16 respectivel
23de0 79 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74  y..** ^(Memory t
23df0 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72  o hold the error
23e00 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20   message string 
23e10 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72  is managed inter
23e20 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70  nally..** The ap
23e30 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e  plication does n
23e40 6f 74 20 6e 65 65 64 20 74 6f 20 77 6f 72 72 79  ot need to worry
23e50 20 61 62 6f 75 74 20 66 72 65 65 69 6e 67 20 74   about freeing t
23e60 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f  he result..** Ho
23e70 77 65 76 65 72 2c 20 74 68 65 20 65 72 72 6f 72  wever, the error
23e80 20 73 74 72 69 6e 67 20 6d 69 67 68 74 20 62 65   string might be
23e90 20 6f 76 65 72 77 72 69 74 74 65 6e 20 6f 72 20   overwritten or 
23ea0 64 65 61 6c 6c 6f 63 61 74 65 64 20 62 79 0a 2a  deallocated by.*
23eb0 2a 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  * subsequent cal
23ec0 6c 73 20 74 6f 20 6f 74 68 65 72 20 53 51 4c 69  ls to other SQLi
23ed0 74 65 20 69 6e 74 65 72 66 61 63 65 20 66 75 6e  te interface fun
23ee0 63 74 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20  ctions.)^.**.** 
23ef0 57 68 65 6e 20 74 68 65 20 73 65 72 69 61 6c 69  When the seriali
23f00 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  zed [threading m
23f10 6f 64 65 5d 20 69 73 20 69 6e 20 75 73 65 2c 20  ode] is in use, 
23f20 69 74 20 6d 69 67 68 74 20 62 65 20 74 68 65 0a  it might be the.
23f30 2a 2a 20 63 61 73 65 20 74 68 61 74 20 61 20 73  ** case that a s
23f40 65 63 6f 6e 64 20 65 72 72 6f 72 20 6f 63 63 75  econd error occu
23f50 72 73 20 6f 6e 20 61 20 73 65 70 61 72 61 74 65  rs on a separate
23f60 20 74 68 72 65 61 64 20 69 6e 20 62 65 74 77 65   thread in betwe
23f70 65 6e 0a 2a 2a 20 74 68 65 20 74 69 6d 65 20 6f  en.** the time o
23f80 66 20 74 68 65 20 66 69 72 73 74 20 65 72 72 6f  f the first erro
23f90 72 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 20 74  r and the call t
23fa0 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63  o these interfac
23fb0 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 61 74  es..** When that
23fc0 20 68 61 70 70 65 6e 73 2c 20 74 68 65 20 73 65   happens, the se
23fd0 63 6f 6e 64 20 65 72 72 6f 72 20 77 69 6c 6c 20  cond error will 
23fe0 62 65 20 72 65 70 6f 72 74 65 64 20 73 69 6e 63  be reported sinc
23ff0 65 20 74 68 65 73 65 0a 2a 2a 20 69 6e 74 65 72  e these.** inter
24000 66 61 63 65 73 20 61 6c 77 61 79 73 20 72 65 70  faces always rep
24010 6f 72 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63  ort the most rec
24020 65 6e 74 20 72 65 73 75 6c 74 2e 20 20 54 6f 20  ent result.  To 
24030 61 76 6f 69 64 0a 2a 2a 20 74 68 69 73 2c 20 65  avoid.** this, e
24040 61 63 68 20 74 68 72 65 61 64 20 63 61 6e 20 6f  ach thread can o
24050 62 74 61 69 6e 20 65 78 63 6c 75 73 69 76 65 20  btain exclusive 
24060 75 73 65 20 6f 66 20 74 68 65 20 5b 64 61 74 61  use of the [data
24070 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
24080 20 44 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b 69 6e   D.** by invokin
24090 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  g [sqlite3_mutex
240a0 5f 65 6e 74 65 72 5d 28 5b 73 71 6c 69 74 65 33  _enter]([sqlite3
240b0 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 62  _db_mutex](D)) b
240c0 65 66 6f 72 65 20 62 65 67 69 6e 6e 69 6e 67 0a  efore beginning.
240d0 2a 2a 20 74 6f 20 75 73 65 20 44 20 61 6e 64 20  ** to use D and 
240e0 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65  invoking [sqlite
240f0 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 5d 28 5b  3_mutex_leave]([
24100 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78  sqlite3_db_mutex
24110 5d 28 44 29 29 20 61 66 74 65 72 0a 2a 2a 20 61  ](D)) after.** a
24120 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20  ll calls to the 
24130 69 6e 74 65 72 66 61 63 65 73 20 6c 69 73 74 65  interfaces liste
24140 64 20 68 65 72 65 20 61 72 65 20 63 6f 6d 70 6c  d here are compl
24150 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61  eted..**.** If a
24160 6e 20 69 6e 74 65 72 66 61 63 65 20 66 61 69 6c  n interface fail
24170 73 20 77 69 74 68 20 53 51 4c 49 54 45 5f 4d 49  s with SQLITE_MI
24180 53 55 53 45 2c 20 74 68 61 74 20 6d 65 61 6e 73  SUSE, that means
24190 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a   the interface.*
241a0 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64 20 69 6e  * was invoked in
241b0 63 6f 72 72 65 63 74 6c 79 20 62 79 20 74 68 65  correctly by the
241c0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 49   application.  I
241d0 6e 20 74 68 61 74 20 63 61 73 65 2c 20 74 68 65  n that case, the
241e0 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 61  .** error code a
241f0 6e 64 20 6d 65 73 73 61 67 65 20 6d 61 79 20 6f  nd message may o
24200 72 20 6d 61 79 20 6e 6f 74 20 62 65 20 73 65 74  r may not be set
24210 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
24220 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 72 72 63  int sqlite3_errc
24230 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29  ode(sqlite3 *db)
24240 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
24250 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65   sqlite3_extende
24260 64 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65  d_errcode(sqlite
24270 33 20 2a 64 62 29 3b 0a 53 51 4c 49 54 45 5f 41  3 *db);.SQLITE_A
24280 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  PI const char *s
24290 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 73 71  qlite3_errmsg(sq
242a0 6c 69 74 65 33 2a 29 3b 0a 53 51 4c 49 54 45 5f  lite3*);.SQLITE_
242b0 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  API const void *
242c0 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36  sqlite3_errmsg16
242d0 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
242e0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c  ** CAPI3REF: SQL
242f0 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63   Statement Objec
24300 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  t.** KEYWORDS: {
24310 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
24320 6e 74 7d 20 7b 70 72 65 70 61 72 65 64 20 73 74  nt} {prepared st
24330 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20  atements}.**.** 
24340 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  An instance of t
24350 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70 72 65  his object repre
24360 73 65 6e 74 73 20 61 20 73 69 6e 67 6c 65 20 53  sents a single S
24370 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a  QL statement..**
24380 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20   This object is 
24390 76 61 72 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e 20  variously known 
243a0 61 73 20 61 20 22 70 72 65 70 61 72 65 64 20 73  as a "prepared s
243b0 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 61 0a 2a  tatement" or a.*
243c0 2a 20 22 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20  * "compiled SQL 
243d0 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 73 69  statement" or si
243e0 6d 70 6c 79 20 61 73 20 61 20 22 73 74 61 74 65  mply as a "state
243f0 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ment"..**.** The
24400 20 6c 69 66 65 20 6f 66 20 61 20 73 74 61 74 65   life of a state
24410 6d 65 6e 74 20 6f 62 6a 65 63 74 20 67 6f 65 73  ment object goes
24420 20 73 6f 6d 65 74 68 69 6e 67 20 6c 69 6b 65 20   something like 
24430 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e  this:.**.** <ol>
24440 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65 20  .** <li> Create 
24450 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67  the object using
24460 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
24470 65 5f 76 32 28 29 5d 20 6f 72 20 61 20 72 65 6c  e_v2()] or a rel
24480 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 66 75 6e  ated.**      fun
24490 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 42  ction..** <li> B
244a0 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 5b 68  ind values to [h
244b0 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 5d 20  ost parameters] 
244c0 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65  using the sqlite
244d0 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20  3_bind_*().**   
244e0 20 20 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a     interfaces..*
244f0 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20 53  * <li> Run the S
24500 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73  QL by calling [s
24510 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f  qlite3_step()] o
24520 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73  ne or more times
24530 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20  ..** <li> Reset 
24540 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 75 73  the statement us
24550 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ing [sqlite3_res
24560 65 74 28 29 5d 20 74 68 65 6e 20 67 6f 20 62 61  et()] then go ba
24570 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73 74  ck.**      to st
24580 65 70 20 32 2e 20 20 44 6f 20 74 68 69 73 20 7a  ep 2.  Do this z
24590 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65  ero or more time
245a0 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72  s..** <li> Destr
245b0 6f 79 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73  oy the object us
245c0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  ing [sqlite3_fin
245d0 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f  alize()]..** </o
245e0 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72 20 74  l>.**.** Refer t
245f0 6f 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20  o documentation 
24600 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 6d 65  on individual me
24610 74 68 6f 64 73 20 61 62 6f 76 65 20 66 6f 72 20  thods above for 
24620 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e  additional.** in
24630 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 79  formation..*/.ty
24640 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
24650 69 74 65 33 5f 73 74 6d 74 20 73 71 6c 69 74 65  ite3_stmt sqlite
24660 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43  3_stmt;../*.** C
24670 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d  API3REF: Run-tim
24680 65 20 4c 69 6d 69 74 73 0a 2a 2a 0a 2a 2a 20 5e  e Limits.**.** ^
24690 28 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20  (This interface 
246a0 61 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a 65 20  allows the size 
246b0 6f 66 20 76 61 72 69 6f 75 73 20 63 6f 6e 73 74  of various const
246c0 72 75 63 74 73 20 74 6f 20 62 65 20 6c 69 6d 69  ructs to be limi
246d0 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e  ted.** on a conn
246e0 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63  ection by connec
246f0 74 69 6f 6e 20 62 61 73 69 73 2e 20 20 54 68 65  tion basis.  The
24700 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
24710 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61   is the.** [data
24720 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
24730 20 77 68 6f 73 65 20 6c 69 6d 69 74 20 69 73 20   whose limit is 
24740 74 6f 20 62 65 20 73 65 74 20 6f 72 20 71 75 65  to be set or que
24750 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65  ried.  The.** se
24760 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
24770 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69  s one of the [li
24780 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 5d 20  mit categories] 
24790 74 68 61 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a  that define a.**
247a0 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73 74 72   class of constr
247b0 75 63 74 73 20 74 6f 20 62 65 20 73 69 7a 65 20  ucts to be size 
247c0 6c 69 6d 69 74 65 64 2e 20 20 54 68 65 20 74 68  limited.  The th
247d0 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ird parameter is
247e0 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69   the.** new limi
247f0 74 20 66 6f 72 20 74 68 61 74 20 63 6f 6e 73 74  t for that const
24800 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49  ruct.)^.**.** ^I
24810 66 20 74 68 65 20 6e 65 77 20 6c 69 6d 69 74 20  f the new limit 
24820 69 73 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75  is a negative nu
24830 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d 69 74 20  mber, the limit 
24840 69 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a  is unchanged..**
24850 20 5e 28 46 6f 72 20 65 61 63 68 20 6c 69 6d 69   ^(For each limi
24860 74 20 63 61 74 65 67 6f 72 79 20 53 51 4c 49 54  t category SQLIT
24870 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e 41 4d 45 3c  E_LIMIT_<i>NAME<
24880 2f 69 3e 20 74 68 65 72 65 20 69 73 20 61 20 0a  /i> there is a .
24890 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 68 61 72  ** [limits | har
248a0 64 20 75 70 70 65 72 20 62 6f 75 6e 64 5d 0a 2a  d upper bound].*
248b0 2a 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65  * set at compile
248c0 2d 74 69 6d 65 20 62 79 20 61 20 43 20 70 72 65  -time by a C pre
248d0 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20  processor macro 
248e0 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 6d 69 74  called.** [limit
248f0 73 20 7c 20 53 51 4c 49 54 45 5f 4d 41 58 5f 3c  s | SQLITE_MAX_<
24900 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a 20  i>NAME</i>]..** 
24910 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22 20 69  (The "_LIMIT_" i
24920 6e 20 74 68 65 20 6e 61 6d 65 20 69 73 20 63 68  n the name is ch
24930 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58 5f 22  anged to "_MAX_"
24940 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d 70 74  .))^.** ^Attempt
24950 73 20 74 6f 20 69 6e 63 72 65 61 73 65 20 61 20  s to increase a 
24960 6c 69 6d 69 74 20 61 62 6f 76 65 20 69 74 73 20  limit above its 
24970 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64  hard upper bound
24980 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79   are.** silently
24990 20 74 72 75 6e 63 61 74 65 64 20 74 6f 20 74 68   truncated to th
249a0 65 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75  e hard upper bou
249b0 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 61 72  nd..**.** ^Regar
249c0 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72  dless of whether
249d0 20 6f 72 20 6e 6f 74 20 74 68 65 20 6c 69 6d 69   or not the limi
249e0 74 20 77 61 73 20 63 68 61 6e 67 65 64 2c 20 74  t was changed, t
249f0 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  he .** [sqlite3_
24a00 6c 69 6d 69 74 28 29 5d 20 69 6e 74 65 72 66 61  limit()] interfa
24a10 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 70  ce returns the p
24a20 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20 74 68  rior value of th
24a30 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 48 65 6e  e limit..** ^Hen
24a40 63 65 2c 20 74 6f 20 66 69 6e 64 20 74 68 65 20  ce, to find the 
24a50 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66  current value of
24a60 20 61 20 6c 69 6d 69 74 20 77 69 74 68 6f 75 74   a limit without
24a70 20 63 68 61 6e 67 69 6e 67 20 69 74 2c 0a 2a 2a   changing it,.**
24a80 20 73 69 6d 70 6c 79 20 69 6e 76 6f 6b 65 20 74   simply invoke t
24a90 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 77 69  his interface wi
24aa0 74 68 20 74 68 65 20 74 68 69 72 64 20 70 61 72  th the third par
24ab0 61 6d 65 74 65 72 20 73 65 74 20 74 6f 20 2d 31  ameter set to -1
24ac0 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69 6d 65  ..**.** Run-time
24ad0 20 6c 69 6d 69 74 73 20 61 72 65 20 69 6e 74 65   limits are inte
24ae0 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20  nded for use in 
24af0 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  applications tha
24b00 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68  t manage.** both
24b10 20 74 68 65 69 72 20 6f 77 6e 20 69 6e 74 65 72   their own inter
24b20 6e 61 6c 20 64 61 74 61 62 61 73 65 20 61 6e 64  nal database and
24b30 20 61 6c 73 6f 20 64 61 74 61 62 61 73 65 73 20   also databases 
24b40 74 68 61 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c  that are control
24b50 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73  led.** by untrus
24b60 74 65 64 20 65 78 74 65 72 6e 61 6c 20 73 6f 75  ted external sou
24b70 72 63 65 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c  rces.  An exampl
24b80 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69  e application mi
24b90 67 68 74 20 62 65 20 61 0a 2a 2a 20 77 65 62 20  ght be a.** web 
24ba0 62 72 6f 77 73 65 72 20 74 68 61 74 20 68 61 73  browser that has
24bb0 20 69 74 73 20 6f 77 6e 20 64 61 74 61 62 61 73   its own databas
24bc0 65 73 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 68  es for storing h
24bd0 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 65  istory and.** se
24be0 70 61 72 61 74 65 20 64 61 74 61 62 61 73 65 73  parate databases
24bf0 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 4a   controlled by J
24c00 61 76 61 53 63 72 69 70 74 20 61 70 70 6c 69 63  avaScript applic
24c10 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 65  ations downloade
24c20 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49 6e 74  d.** off the Int
24c30 65 72 6e 65 74 2e 20 20 54 68 65 20 69 6e 74 65  ernet.  The inte
24c40 72 6e 61 6c 20 64 61 74 61 62 61 73 65 73 20 63  rnal databases c
24c50 61 6e 20 62 65 20 67 69 76 65 6e 20 74 68 65 0a  an be given the.
24c60 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66 61 75 6c  ** large, defaul
24c70 74 20 6c 69 6d 69 74 73 2e 20 20 44 61 74 61 62  t limits.  Datab
24c80 61 73 65 73 20 6d 61 6e 61 67 65 64 20 62 79 20  ases managed by 
24c90 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73  external sources
24ca0 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76 65 6e   can.** be given
24cb0 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20 6c 69   much smaller li
24cc0 6d 69 74 73 20 64 65 73 69 67 6e 65 64 20 74 6f  mits designed to
24cd0 20 70 72 65 76 65 6e 74 20 61 20 64 65 6e 69 61   prevent a denia
24ce0 6c 20 6f 66 20 73 65 72 76 69 63 65 0a 2a 2a 20  l of service.** 
24cf0 61 74 74 61 63 6b 2e 20 20 44 65 76 65 6c 6f 70  attack.  Develop
24d00 65 72 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 77  ers might also w
24d10 61 6e 74 20 74 6f 20 75 73 65 20 74 68 65 20 5b  ant to use the [
24d20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
24d30 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e 74  orizer()].** int
24d40 65 72 66 61 63 65 20 74 6f 20 66 75 72 74 68 65  erface to furthe
24d50 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 73  r control untrus
24d60 74 65 64 20 53 51 4c 2e 20 20 54 68 65 20 73 69  ted SQL.  The si
24d70 7a 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  ze of the databa
24d80 73 65 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79  se.** created by
24d90 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73 63   an untrusted sc
24da0 72 69 70 74 20 63 61 6e 20 62 65 20 63 6f 6e 74  ript can be cont
24db0 61 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65 0a  ained using the.
24dc0 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75  ** [max_page_cou
24dd0 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a  nt] [PRAGMA]..**
24de0 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 69 6d 65  .** New run-time
24df0 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65   limit categorie
24e00 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69  s may be added i
24e10 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  n future release
24e20 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  s..*/.SQLITE_API
24e30 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69 6d   int sqlite3_lim
24e40 69 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  it(sqlite3*, int
24e50 20 69 64 2c 20 69 6e 74 20 6e 65 77 56 61 6c 29   id, int newVal)
24e60 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
24e70 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 6d 69  F: Run-Time Limi
24e80 74 20 43 61 74 65 67 6f 72 69 65 73 0a 2a 2a 20  t Categories.** 
24e90 4b 45 59 57 4f 52 44 53 3a 20 7b 6c 69 6d 69 74  KEYWORDS: {limit
24ea0 20 63 61 74 65 67 6f 72 79 7d 20 7b 2a 6c 69 6d   category} {*lim
24eb0 69 74 20 63 61 74 65 67 6f 72 69 65 73 7d 0a 2a  it categories}.*
24ec0 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
24ed0 61 6e 74 73 20 64 65 66 69 6e 65 20 76 61 72 69  ants define vari
24ee0 6f 75 73 20 70 65 72 66 6f 72 6d 61 6e 63 65 20  ous performance 
24ef0 6c 69 6d 69 74 73 0a 2a 2a 20 74 68 61 74 20 63  limits.** that c
24f00 61 6e 20 62 65 20 6c 6f 77 65 72 65 64 20 61 74  an be lowered at
24f10 20 72 75 6e 2d 74 69 6d 65 20 75 73 69 6e 67 20   run-time using 
24f20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29  [sqlite3_limit()
24f30 5d 2e 0a 2a 2a 20 54 68 65 20 73 79 6e 6f 70 73  ]..** The synops
24f40 69 73 20 6f 66 20 74 68 65 20 6d 65 61 6e 69 6e  is of the meanin
24f50 67 73 20 6f 66 20 74 68 65 20 76 61 72 69 6f 75  gs of the variou
24f60 73 20 6c 69 6d 69 74 73 20 69 73 20 73 68 6f 77  s limits is show
24f70 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69  n below..** Addi
24f80 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69  tional informati
24f90 6f 6e 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20  on is available 
24fa0 61 74 20 5b 6c 69 6d 69 74 73 20 7c 20 4c 69 6d  at [limits | Lim
24fb0 69 74 73 20 69 6e 20 53 51 4c 69 74 65 5d 2e 0a  its in SQLite]..
24fc0 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b  **.** <dl>.** [[
24fd0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e  SQLITE_LIMIT_LEN
24fe0 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  GTH]] ^(<dt>SQLI
24ff0 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 3c  TE_LIMIT_LENGTH<
25000 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
25010 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20  maximum size of 
25020 61 6e 79 20 73 74 72 69 6e 67 20 6f 72 20 42 4c  any string or BL
25030 4f 42 20 6f 72 20 74 61 62 6c 65 20 72 6f 77 2c  OB or table row,
25040 20 69 6e 20 62 79 74 65 73 2e 3c 64 64 3e 29 5e   in bytes.<dd>)^
25050 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
25060 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48  LIMIT_SQL_LENGTH
25070 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
25080 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48  LIMIT_SQL_LENGTH
25090 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
250a0 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   maximum length 
250b0 6f 66 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  of an SQL statem
250c0 65 6e 74 2c 20 69 6e 20 62 79 74 65 73 2e 3c 2f  ent, in bytes.</
250d0 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
250e0 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d  LITE_LIMIT_COLUM
250f0 4e 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  N]] ^(<dt>SQLITE
25100 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64  _LIMIT_COLUMN</d
25110 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
25120 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
25130 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74 61 62  columns in a tab
25140 6c 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 72  le definition or
25150 20 69 6e 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c   in the.** resul
25160 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45  t set of a [SELE
25170 43 54 5d 20 6f 72 20 74 68 65 20 6d 61 78 69 6d  CT] or the maxim
25180 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  um number of col
25190 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65 78  umns in an index
251a0 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 4f 52 44  .** or in an ORD
251b0 45 52 20 42 59 20 6f 72 20 47 52 4f 55 50 20 42  ER BY or GROUP B
251c0 59 20 63 6c 61 75 73 65 2e 3c 2f 64 64 3e 29 5e  Y clause.</dd>)^
251d0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
251e0 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48  LIMIT_EXPR_DEPTH
251f0 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
25200 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48  LIMIT_EXPR_DEPTH
25210 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
25220 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f   maximum depth o
25230 66 20 74 68 65 20 70 61 72 73 65 20 74 72 65 65  f the parse tree
25240 20 6f 6e 20 61 6e 79 20 65 78 70 72 65 73 73 69   on any expressi
25250 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  on.</dd>)^.**.**
25260 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
25270 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 5d  COMPOUND_SELECT]
25280 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
25290 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45  IMIT_COMPOUND_SE
252a0 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  LECT</dt>.** <dd
252b0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
252c0 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e 20  ber of terms in 
252d0 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43  a compound SELEC
252e0 54 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64  T statement.</dd
252f0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
25300 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50  TE_LIMIT_VDBE_OP
25310 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
25320 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 3c 2f 64  LIMIT_VDBE_OP</d
25330 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
25340 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
25350 69 6e 73 74 72 75 63 74 69 6f 6e 73 20 69 6e 20  instructions in 
25360 61 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e  a virtual machin
25370 65 20 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 73 65  e program.** use
25380 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61  d to implement a
25390 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e  n SQL statement.
253a0 20 20 54 68 69 73 20 6c 69 6d 69 74 20 69 73 20    This limit is 
253b0 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 0a 2a 2a  not currently.**
253c0 20 65 6e 66 6f 72 63 65 64 2c 20 74 68 6f 75 67   enforced, thoug
253d0 68 20 74 68 61 74 20 6d 69 67 68 74 20 62 65 20  h that might be 
253e0 61 64 64 65 64 20 69 6e 20 73 6f 6d 65 20 66 75  added in some fu
253f0 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 0a  ture release of.
25400 2a 2a 20 53 51 4c 69 74 65 2e 3c 2f 64 64 3e 29  ** SQLite.</dd>)
25410 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
25420 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f  _LIMIT_FUNCTION_
25430 41 52 47 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  ARG]] ^(<dt>SQLI
25440 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f  TE_LIMIT_FUNCTIO
25450 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  N_ARG</dt>.** <d
25460 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
25470 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74  mber of argument
25480 73 20 6f 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e  s on a function.
25490 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
254a0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54  SQLITE_LIMIT_ATT
254b0 41 43 48 45 44 5d 5d 20 5e 28 3c 64 74 3e 53 51  ACHED]] ^(<dt>SQ
254c0 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43  LITE_LIMIT_ATTAC
254d0 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  HED</dt>.** <dd>
254e0 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
254f0 65 72 20 6f 66 20 5b 41 54 54 41 43 48 20 7c 20  er of [ATTACH | 
25500 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73  attached databas
25510 65 73 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  es].)^</dd>.**.*
25520 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
25530 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45  _LIKE_PATTERN_LE
25540 4e 47 54 48 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e  NGTH]].** ^(<dt>
25550 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b  SQLITE_LIMIT_LIK
25560 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48  E_PATTERN_LENGTH
25570 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
25580 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   maximum length 
25590 6f 66 20 74 68 65 20 70 61 74 74 65 72 6e 20 61  of the pattern a
255a0 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b  rgument to the [
255b0 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47 4c 4f  LIKE] or.** [GLO
255c0 42 5d 20 6f 70 65 72 61 74 6f 72 73 2e 3c 2f 64  B] operators.</d
255d0 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
255e0 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42  ITE_LIMIT_VARIAB
255f0 4c 45 5f 4e 55 4d 42 45 52 5d 5d 0a 2a 2a 20 5e  LE_NUMBER]].** ^
25600 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
25610 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45  T_VARIABLE_NUMBE
25620 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  R</dt>.** <dd>Th
25630 65 20 6d 61 78 69 6d 75 6d 20 69 6e 64 65 78 20  e maximum index 
25640 6e 75 6d 62 65 72 20 6f 66 20 61 6e 79 20 5b 70  number of any [p
25650 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 61 6e 20  arameter] in an 
25660 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 29 5e  SQL statement.)^
25670 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
25680 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45  LIMIT_TRIGGER_DE
25690 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  PTH]] ^(<dt>SQLI
256a0 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52  TE_LIMIT_TRIGGER
256b0 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  _DEPTH</dt>.** <
256c0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64  dd>The maximum d
256d0 65 70 74 68 20 6f 66 20 72 65 63 75 72 73 69 6f  epth of recursio
256e0 6e 20 66 6f 72 20 74 72 69 67 67 65 72 73 2e 3c  n for triggers.<
256f0 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a  /dd>)^.** </dl>.
25700 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
25710 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20  E_LIMIT_LENGTH  
25720 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
25730 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    0.#define SQLI
25740 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e  TE_LIMIT_SQL_LEN
25750 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20  GTH             
25760 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c     1.#define SQL
25770 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e  ITE_LIMIT_COLUMN
25780 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
25790 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
257a0 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f  LITE_LIMIT_EXPR_
257b0 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20 20  DEPTH           
257c0 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53       3.#define S
257d0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50  QLITE_LIMIT_COMP
257e0 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20 20 20 20  OUND_SELECT     
257f0 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20        4.#define 
25800 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42  SQLITE_LIMIT_VDB
25810 45 5f 4f 50 20 20 20 20 20 20 20 20 20 20 20 20  E_OP            
25820 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65         5.#define
25830 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55   SQLITE_LIMIT_FU
25840 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20 20 20 20  NCTION_ARG      
25850 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e          6.#defin
25860 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41  e SQLITE_LIMIT_A
25870 54 54 41 43 48 45 44 20 20 20 20 20 20 20 20 20  TTACHED         
25880 20 20 20 20 20 20 20 20 20 37 0a 23 64 65 66 69           7.#defi
25890 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
258a0 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e  LIKE_PATTERN_LEN
258b0 47 54 48 20 20 20 20 20 20 20 38 0a 23 64 65 66  GTH       8.#def
258c0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
258d0 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52  _VARIABLE_NUMBER
258e0 20 20 20 20 20 20 20 20 20 20 20 39 0a 23 64 65             9.#de
258f0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
25900 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 20  T_TRIGGER_DEPTH 
25910 20 20 20 20 20 20 20 20 20 20 20 31 30 0a 0a 2f             10../
25920 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
25930 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20  ompiling An SQL 
25940 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b 45 59  Statement.** KEY
25950 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74 61 74  WORDS: {SQL stat
25960 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d 0a  ement compiler}.
25970 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74 65  **.** To execute
25980 20 61 6e 20 53 51 4c 20 71 75 65 72 79 2c 20 69   an SQL query, i
25990 74 20 6d 75 73 74 20 66 69 72 73 74 20 62 65 20  t must first be 
259a0 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61 20  compiled into a 
259b0 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f  byte-code.** pro
259c0 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f  gram using one o
259d0 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
259e0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73  ..**.** The firs
259f0 74 20 61 72 67 75 6d 65 6e 74 2c 20 22 64 62 22  t argument, "db"
25a00 2c 20 69 73 20 61 20 5b 64 61 74 61 62 61 73 65  , is a [database
25a10 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 74   connection] obt
25a20 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20  ained from a.** 
25a30 70 72 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c  prior successful
25a40 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
25a50 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69  3_open()], [sqli
25a60 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 6f  te3_open_v2()] o
25a70 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70  r.** [sqlite3_op
25a80 65 6e 31 36 28 29 5d 2e 20 20 54 68 65 20 64 61  en16()].  The da
25a90 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
25aa0 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61 76 65 20  n must not have 
25ab0 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a  been closed..**.
25ac0 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72  ** The second ar
25ad0 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c 20  gument, "zSql", 
25ae0 69 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  is the statement
25af0 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c   to be compiled,
25b00 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65   encoded.** as e
25b10 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55  ither UTF-8 or U
25b20 54 46 2d 31 36 2e 20 20 54 68 65 20 73 71 6c 69  TF-16.  The sqli
25b30 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 61 6e  te3_prepare() an
25b40 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  d sqlite3_prepar
25b50 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72 66  e_v2().** interf
25b60 61 63 65 73 20 75 73 65 20 55 54 46 2d 38 2c 20  aces use UTF-8, 
25b70 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70  and sqlite3_prep
25b80 61 72 65 31 36 28 29 20 61 6e 64 20 73 71 6c 69  are16() and sqli
25b90 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
25ba0 28 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31 36  ().** use UTF-16
25bb0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
25bc0 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20 69  nByte argument i
25bd0 73 20 6c 65 73 73 20 74 68 61 6e 20 7a 65 72 6f  s less than zero
25be0 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 73 20 72  , then zSql is r
25bf0 65 61 64 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a  ead up to the.**
25c00 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d   first zero term
25c10 69 6e 61 74 6f 72 2e 20 5e 49 66 20 6e 42 79 74  inator. ^If nByt
25c20 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  e is non-negativ
25c30 65 2c 20 74 68 65 6e 20 69 74 20 69 73 20 74 68  e, then it is th
25c40 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 6e 75 6d  e maximum.** num
25c50 62 65 72 20 6f 66 20 20 62 79 74 65 73 20 72 65  ber of  bytes re
25c60 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 5e  ad from zSql.  ^
25c70 57 68 65 6e 20 6e 42 79 74 65 20 69 73 20 6e 6f  When nByte is no
25c80 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 0a  n-negative, the.
25c90 2a 2a 20 7a 53 71 6c 20 73 74 72 69 6e 67 20 65  ** zSql string e
25ca0 6e 64 73 20 61 74 20 65 69 74 68 65 72 20 74 68  nds at either th
25cb0 65 20 66 69 72 73 74 20 27 5c 30 30 30 27 20 6f  e first '\000' o
25cc0 72 20 27 5c 75 30 30 30 30 27 20 63 68 61 72 61  r '\u0000' chara
25cd0 63 74 65 72 20 6f 72 0a 2a 2a 20 74 68 65 20 6e  cter or.** the n
25ce0 42 79 74 65 2d 74 68 20 62 79 74 65 2c 20 77 68  Byte-th byte, wh
25cf0 69 63 68 65 76 65 72 20 63 6f 6d 65 73 20 66 69  ichever comes fi
25d00 72 73 74 2e 20 49 66 20 74 68 65 20 63 61 6c 6c  rst. If the call
25d10 65 72 20 6b 6e 6f 77 73 0a 2a 2a 20 74 68 61 74  er knows.** that
25d20 20 74 68 65 20 73 75 70 70 6c 69 65 64 20 73 74   the supplied st
25d30 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d  ring is nul-term
25d40 69 6e 61 74 65 64 2c 20 74 68 65 6e 20 74 68 65  inated, then the
25d50 72 65 20 69 73 20 61 20 73 6d 61 6c 6c 0a 2a 2a  re is a small.**
25d60 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 61 64 76   performance adv
25d70 61 6e 74 61 67 65 20 74 6f 20 62 65 20 67 61 69  antage to be gai
25d80 6e 65 64 20 62 79 20 70 61 73 73 69 6e 67 20 61  ned by passing a
25d90 6e 20 6e 42 79 74 65 20 70 61 72 61 6d 65 74 65  n nByte paramete
25da0 72 20 74 68 61 74 0a 2a 2a 20 69 73 20 65 71 75  r that.** is equ
25db0 61 6c 20 74 6f 20 74 68 65 20 6e 75 6d 62 65 72  al to the number
25dc0 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65   of bytes in the
25dd0 20 69 6e 70 75 74 20 73 74 72 69 6e 67 20 3c 69   input string <i
25de0 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a  >including</i>.*
25df0 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69 6e  * the nul-termin
25e00 61 74 6f 72 20 62 79 74 65 73 2e 0a 2a 2a 0a 2a  ator bytes..**.*
25e10 2a 20 5e 49 66 20 70 7a 54 61 69 6c 20 69 73 20  * ^If pzTail is 
25e20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 2a 70  not NULL then *p
25e30 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20 74 6f  zTail is made to
25e40 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 20 66 69   point to the fi
25e50 72 73 74 20 62 79 74 65 0a 2a 2a 20 70 61 73 74  rst byte.** past
25e60 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20   the end of the 
25e70 66 69 72 73 74 20 53 51 4c 20 73 74 61 74 65 6d  first SQL statem
25e80 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68  ent in zSql.  Th
25e90 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 6c  ese routines onl
25ea0 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 68 65  y.** compile the
25eb0 20 66 69 72 73 74 20 73 74 61 74 65 6d 65 6e 74   first statement
25ec0 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a   in zSql, so *pz
25ed0 54 61 69 6c 20 69 73 20 6c 65 66 74 20 70 6f 69  Tail is left poi
25ee0 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20 77 68 61 74  nting to.** what
25ef0 20 72 65 6d 61 69 6e 73 20 75 6e 63 6f 6d 70 69   remains uncompi
25f00 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70 53  led..**.** ^*ppS
25f10 74 6d 74 20 69 73 20 6c 65 66 74 20 70 6f 69 6e  tmt is left poin
25f20 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70 69 6c  ting to a compil
25f30 65 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ed [prepared sta
25f40 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 63 61 6e  tement] that can
25f50 20 62 65 0a 2a 2a 20 65 78 65 63 75 74 65 64 20   be.** executed 
25f60 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73  using [sqlite3_s
25f70 74 65 70 28 29 5d 2e 20 20 5e 49 66 20 74 68 65  tep()].  ^If the
25f80 72 65 20 69 73 20 61 6e 20 65 72 72 6f 72 2c 20  re is an error, 
25f90 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 0a 2a  *ppStmt is set.*
25fa0 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20 5e 49 66 20  * to NULL.  ^If 
25fb0 74 68 65 20 69 6e 70 75 74 20 74 65 78 74 20 63  the input text c
25fc0 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20 28  ontains no SQL (
25fd0 69 66 20 74 68 65 20 69 6e 70 75 74 20 69 73 20  if the input is 
25fe0 61 6e 20 65 6d 70 74 79 0a 2a 2a 20 73 74 72 69  an empty.** stri
25ff0 6e 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 29  ng or a comment)
26000 20 74 68 65 6e 20 2a 70 70 53 74 6d 74 20 69 73   then *ppStmt is
26010 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a   set to NULL..**
26020 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 70 72 6f   The calling pro
26030 63 65 64 75 72 65 20 69 73 20 72 65 73 70 6f 6e  cedure is respon
26040 73 69 62 6c 65 20 66 6f 72 20 64 65 6c 65 74 69  sible for deleti
26050 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 0a  ng the compiled.
26060 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
26070 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
26080 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66 74 65  finalize()] afte
26090 72 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65  r it has finishe
260a0 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a 20 70 70  d with it..** pp
260b0 53 74 6d 74 20 6d 61 79 20 6e 6f 74 20 62 65 20  Stmt may not be 
260c0 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20  NULL..**.** ^On 
260d0 73 75 63 63 65 73 73 2c 20 74 68 65 20 73 71 6c  success, the sql
260e0 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 66  ite3_prepare() f
260f0 61 6d 69 6c 79 20 6f 66 20 72 6f 75 74 69 6e 65  amily of routine
26100 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  s return [SQLITE
26110 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68 65 72 77 69  _OK];.** otherwi
26120 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64  se an [error cod
26130 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  e] is returned..
26140 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
26150 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 61  3_prepare_v2() a
26160 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nd sqlite3_prepa
26170 72 65 31 36 5f 76 32 28 29 20 69 6e 74 65 72 66  re16_v2() interf
26180 61 63 65 73 20 61 72 65 0a 2a 2a 20 72 65 63 6f  aces are.** reco
26190 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20  mmended for all 
261a0 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e 20 54 68  new programs. Th
261b0 65 20 74 77 6f 20 6f 6c 64 65 72 20 69 6e 74 65  e two older inte
261c0 72 66 61 63 65 73 20 61 72 65 20 72 65 74 61 69  rfaces are retai
261d0 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 61 63 6b 77  ned.** for backw
261e0 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
261f0 74 79 2c 20 62 75 74 20 74 68 65 69 72 20 75 73  ty, but their us
26200 65 20 69 73 20 64 69 73 63 6f 75 72 61 67 65 64  e is discouraged
26210 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 22 76 32  ..** ^In the "v2
26220 22 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68  " interfaces, th
26230 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
26240 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73 20  ment.** that is 
26250 72 65 74 75 72 6e 65 64 20 28 74 68 65 20 5b 73  returned (the [s
26260 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a  qlite3_stmt] obj
26270 65 63 74 29 20 63 6f 6e 74 61 69 6e 73 20 61 20  ect) contains a 
26280 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f  copy of the.** o
26290 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74  riginal SQL text
262a0 2e 20 54 68 69 73 20 63 61 75 73 65 73 20 74 68  . This causes th
262b0 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  e [sqlite3_step(
262c0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74 6f 0a  )] interface to.
262d0 2a 2a 20 62 65 68 61 76 65 20 64 69 66 66 65 72  ** behave differ
262e0 65 6e 74 6c 79 20 69 6e 20 74 68 72 65 65 20 77  ently in three w
262f0 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a  ays:.**.** <ol>.
26300 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74  ** <li>.** ^If t
26310 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65  he database sche
26320 6d 61 20 63 68 61 6e 67 65 73 2c 20 69 6e 73 74  ma changes, inst
26330 65 61 64 20 6f 66 20 72 65 74 75 72 6e 69 6e 67  ead of returning
26340 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d   [SQLITE_SCHEMA]
26350 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73   as it.** always
26360 20 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71   used to do, [sq
26370 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69  lite3_step()] wi
26380 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ll automatically
26390 20 72 65 63 6f 6d 70 69 6c 65 20 74 68 65 20 53   recompile the S
263a0 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  QL.** statement 
263b0 61 6e 64 20 74 72 79 20 74 6f 20 72 75 6e 20 69  and try to run i
263c0 74 20 61 67 61 69 6e 2e 0a 2a 2a 20 3c 2f 6c 69  t again..** </li
263d0 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20  >.**.** <li>.** 
263e0 5e 57 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f  ^When an error o
263f0 63 63 75 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f  ccurs, [sqlite3_
26400 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 72 65 74  step()] will ret
26410 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 64  urn one of the d
26420 65 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f  etailed.** [erro
26430 72 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74  r codes] or [ext
26440 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65  ended error code
26450 73 5d 2e 20 20 5e 54 68 65 20 6c 65 67 61 63 79  s].  ^The legacy
26460 20 62 65 68 61 76 69 6f 72 20 77 61 73 20 74 68   behavior was th
26470 61 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  at.** [sqlite3_s
26480 74 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c  tep()] would onl
26490 79 20 72 65 74 75 72 6e 20 61 20 67 65 6e 65 72  y return a gener
264a0 69 63 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ic [SQLITE_ERROR
264b0 5d 20 72 65 73 75 6c 74 20 63 6f 64 65 0a 2a 2a  ] result code.**
264c0 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61   and the applica
264d0 74 69 6f 6e 20 77 6f 75 6c 64 20 68 61 76 65 20  tion would have 
264e0 74 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64  to make a second
264f0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
26500 33 5f 72 65 73 65 74 28 29 5d 0a 2a 2a 20 69 6e  3_reset()].** in
26510 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 74   order to find t
26520 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 63 61  he underlying ca
26530 75 73 65 20 6f 66 20 74 68 65 20 70 72 6f 62 6c  use of the probl
26540 65 6d 2e 20 57 69 74 68 20 74 68 65 20 22 76 32  em. With the "v2
26550 22 20 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e 74  " prepare.** int
26560 65 72 66 61 63 65 73 2c 20 74 68 65 20 75 6e 64  erfaces, the und
26570 65 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20 66  erlying reason f
26580 6f 72 20 74 68 65 20 65 72 72 6f 72 20 69 73 20  or the error is 
26590 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61  returned immedia
265a0 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a  tely..** </li>.*
265b0 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66  *.** <li>.** ^If
265c0 20 74 68 65 20 73 70 65 63 69 66 69 63 20 76 61   the specific va
265d0 6c 75 65 20 62 6f 75 6e 64 20 74 6f 20 5b 70 61  lue bound to [pa
265e0 72 61 6d 65 74 65 72 20 7c 20 68 6f 73 74 20 70  rameter | host p
265f0 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65  arameter] in the
26600 20 0a 2a 2a 20 57 48 45 52 45 20 63 6c 61 75 73   .** WHERE claus
26610 65 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63  e might influenc
26620 65 20 74 68 65 20 63 68 6f 69 63 65 20 6f 66 20  e the choice of 
26630 71 75 65 72 79 20 70 6c 61 6e 20 66 6f 72 20 61  query plan for a
26640 20 73 74 61 74 65 6d 65 6e 74 2c 0a 2a 2a 20 74   statement,.** t
26650 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e  hen the statemen
26660 74 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61  t will be automa
26670 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c  tically recompil
26680 65 64 2c 20 61 73 20 69 66 20 74 68 65 72 65 20  ed, as if there 
26690 68 61 64 20 62 65 65 6e 20 0a 2a 2a 20 61 20 73  had been .** a s
266a0 63 68 65 6d 61 20 63 68 61 6e 67 65 2c 20 6f 6e  chema change, on
266b0 20 74 68 65 20 66 69 72 73 74 20 20 5b 73 71 6c   the first  [sql
266c0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c  ite3_step()] cal
266d0 6c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 20  l following any 
266e0 63 68 61 6e 67 65 0a 2a 2a 20 74 6f 20 74 68 65  change.** to the
266f0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74   [sqlite3_bind_t
26700 65 78 74 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20  ext | bindings] 
26710 6f 66 20 74 68 61 74 20 5b 70 61 72 61 6d 65 74  of that [paramet
26720 65 72 5d 2e 20 0a 2a 2a 20 5e 54 68 65 20 73 70  er]. .** ^The sp
26730 65 63 69 66 69 63 20 76 61 6c 75 65 20 6f 66 20  ecific value of 
26740 57 48 45 52 45 2d 63 6c 61 75 73 65 20 5b 70 61  WHERE-clause [pa
26750 72 61 6d 65 74 65 72 5d 20 6d 69 67 68 74 20 69  rameter] might i
26760 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 0a 2a 2a  nfluence the .**
26770 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79   choice of query
26780 20 70 6c 61 6e 20 69 66 20 74 68 65 20 70 61 72   plan if the par
26790 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6c 65  ameter is the le
267a0 66 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20  ft-hand side of 
267b0 61 20 5b 4c 49 4b 45 5d 0a 2a 2a 20 6f 72 20 5b  a [LIKE].** or [
267c0 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 20 6f  GLOB] operator o
267d0 72 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74  r if the paramet
267e0 65 72 20 69 73 20 63 6f 6d 70 61 72 65 64 20 74  er is compared t
267f0 6f 20 61 6e 20 69 6e 64 65 78 65 64 20 63 6f 6c  o an indexed col
26800 75 6d 6e 0a 2a 2a 20 61 6e 64 20 74 68 65 20 5b  umn.** and the [
26810 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 54  SQLITE_ENABLE_ST
26820 41 54 32 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  AT2] compile-tim
26830 65 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61 62  e option is enab
26840 6c 65 64 2e 0a 2a 2a 20 74 68 65 20 0a 2a 2a 20  led..** the .** 
26850 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a  </li>.** </ol>.*
26860 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
26870 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
26880 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
26890 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
268a0 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a  atabase handle *
268b0 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
268c0 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53  zSql,       /* S
268d0 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54  QL statement, UT
268e0 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20  F-8 encoded */. 
268f0 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20   int nByte,     
26900 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
26910 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53  mum length of zS
26920 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a  ql in bytes. */.
26930 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a    sqlite3_stmt *
26940 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54  *ppStmt,  /* OUT
26950 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  : Statement hand
26960 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  le */.  const ch
26970 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20  ar **pzTail     
26980 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20  /* OUT: Pointer 
26990 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f  to unused portio
269a0 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a  n of zSql */.);.
269b0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
269c0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
269d0 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  2(.  sqlite3 *db
269e0 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
269f0 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
26a00 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
26a10 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
26a20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
26a30 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a  TF-8 encoded */.
26a40 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20    int nByte,    
26a50 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
26a60 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a  imum length of z
26a70 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f  Sql in bytes. */
26a80 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  .  sqlite3_stmt 
26a90 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55  **ppStmt,  /* OU
26aa0 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e  T: Statement han
26ab0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
26ac0 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20  har **pzTail    
26ad0 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72   /* OUT: Pointer
26ae0 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69   to unused porti
26af0 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b  on of zSql */.);
26b00 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
26b10 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
26b20 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  6(.  sqlite3 *db
26b30 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
26b40 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
26b50 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
26b60 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
26b70 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
26b80 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f  TF-16 encoded */
26b90 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20  .  int nByte,   
26ba0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61             /* Ma
26bb0 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
26bc0 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a  zSql in bytes. *
26bd0 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  /.  sqlite3_stmt
26be0 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f   **ppStmt,  /* O
26bf0 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61  UT: Statement ha
26c00 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
26c10 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20  void **pzTail   
26c20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65    /* OUT: Pointe
26c30 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74  r to unused port
26c40 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29  ion of zSql */.)
26c50 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
26c60 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
26c70 31 36 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33  16_v2(.  sqlite3
26c80 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
26c90 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
26ca0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  dle */.  const v
26cb0 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  oid *zSql,      
26cc0 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
26cd0 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65  t, UTF-16 encode
26ce0 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
26cf0 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
26d00 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
26d10 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
26d20 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  s. */.  sqlite3_
26d30 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
26d40 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
26d50 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
26d60 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69  nst void **pzTai
26d70 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
26d80 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
26d90 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
26da0 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.);../*.** CAP
26db0 49 33 52 45 46 3a 20 52 65 74 72 69 65 76 69 6e  I3REF: Retrievin
26dc0 67 20 53 74 61 74 65 6d 65 6e 74 20 53 51 4c 0a  g Statement SQL.
26dd0 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65  **.** ^This inte
26de0 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65  rface can be use
26df0 64 20 74 6f 20 72 65 74 72 69 65 76 65 20 61 20  d to retrieve a 
26e00 73 61 76 65 64 20 63 6f 70 79 20 6f 66 20 74 68  saved copy of th
26e10 65 20 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20 53 51  e original.** SQ
26e20 4c 20 74 65 78 74 20 75 73 65 64 20 74 6f 20 63  L text used to c
26e30 72 65 61 74 65 20 61 20 5b 70 72 65 70 61 72 65  reate a [prepare
26e40 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 66 20  d statement] if 
26e50 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20 77  that statement w
26e60 61 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 75  as.** compiled u
26e70 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c  sing either [sql
26e80 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
26e90 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70  )] or [sqlite3_p
26ea0 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a  repare16_v2()]..
26eb0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  */.SQLITE_API co
26ec0 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
26ed0 33 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f 73 74  3_sql(sqlite3_st
26ee0 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
26ef0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74  ** CAPI3REF: Det
26f00 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c  ermine If An SQL
26f10 20 53 74 61 74 65 6d 65 6e 74 20 57 72 69 74 65   Statement Write
26f20 73 20 54 68 65 20 44 61 74 61 62 61 73 65 0a 2a  s The Database.*
26f30 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
26f40 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28  3_stmt_readonly(
26f50 58 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  X) interface ret
26f60 75 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a  urns true (non-z
26f70 65 72 6f 29 20 69 66 0a 2a 2a 20 61 6e 64 20 6f  ero) if.** and o
26f80 6e 6c 79 20 69 66 20 74 68 65 20 5b 70 72 65 70  nly if the [prep
26f90 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
26fa0 58 20 6d 61 6b 65 73 20 6e 6f 20 64 69 72 65 63  X makes no direc
26fb0 74 20 63 68 61 6e 67 65 73 20 74 6f 0a 2a 2a 20  t changes to.** 
26fc0 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74  the content of t
26fd0 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
26fe0 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ..**.** Note tha
26ff0 74 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  t [application-d
27000 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
27010 69 6f 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76 69 72  ions] or.** [vir
27020 74 75 61 6c 20 74 61 62 6c 65 73 5d 20 6d 69 67  tual tables] mig
27030 68 74 20 63 68 61 6e 67 65 20 74 68 65 20 64 61  ht change the da
27040 74 61 62 61 73 65 20 69 6e 64 69 72 65 63 74 6c  tabase indirectl
27050 79 20 61 73 20 61 20 73 69 64 65 20 65 66 66 65  y as a side effe
27060 63 74 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72 20 65  ct.  .** ^(For e
27070 78 61 6d 70 6c 65 2c 20 69 66 20 61 6e 20 61 70  xample, if an ap
27080 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65  plication define
27090 73 20 61 20 66 75 6e 63 74 69 6f 6e 20 22 65 76  s a function "ev
270a0 61 6c 28 29 22 20 74 68 61 74 20 0a 2a 2a 20 63  al()" that .** c
270b0 61 6c 6c 73 20 5b 73 71 6c 69 74 65 33 5f 65 78  alls [sqlite3_ex
270c0 65 63 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20  ec()], then the 
270d0 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 20 73 74  following SQL st
270e0 61 74 65 6d 65 6e 74 20 77 6f 75 6c 64 0a 2a 2a  atement would.**
270f0 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61   change the data
27100 62 61 73 65 20 66 69 6c 65 20 74 68 72 6f 75 67  base file throug
27110 68 20 73 69 64 65 2d 65 66 66 65 63 74 73 3a 0a  h side-effects:.
27120 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
27130 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 53 45  e><pre>.**    SE
27140 4c 45 43 54 20 65 76 61 6c 28 27 44 45 4c 45 54  LECT eval('DELET
27150 45 20 46 52 4f 4d 20 74 31 27 29 20 46 52 4f 4d  E FROM t1') FROM
27160 20 74 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f   t2;.** </pre></
27170 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
27180 2a 20 42 75 74 20 62 65 63 61 75 73 65 20 74 68  * But because th
27190 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  e [SELECT] state
271a0 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 68  ment does not ch
271b0 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 73  ange the databas
271c0 65 20 66 69 6c 65 0a 2a 2a 20 64 69 72 65 63 74  e file.** direct
271d0 6c 79 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  ly, sqlite3_stmt
271e0 5f 72 65 61 64 6f 6e 6c 79 28 29 20 77 6f 75 6c  _readonly() woul
271f0 64 20 73 74 69 6c 6c 20 72 65 74 75 72 6e 20 74  d still return t
27200 72 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72  rue.)^.**.** ^Tr
27210 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f  ansaction contro
27220 6c 20 73 74 61 74 65 6d 65 6e 74 73 20 73 75 63  l statements suc
27230 68 20 61 73 20 5b 42 45 47 49 4e 5d 2c 20 5b 43  h as [BEGIN], [C
27240 4f 4d 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42 41 43  OMMIT], [ROLLBAC
27250 4b 5d 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f 49 4e  K],.** [SAVEPOIN
27260 54 5d 2c 20 61 6e 64 20 5b 52 45 4c 45 41 53 45  T], and [RELEASE
27270 5d 20 63 61 75 73 65 20 73 71 6c 69 74 65 33 5f  ] cause sqlite3_
27280 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20  stmt_readonly() 
27290 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65 2c 0a  to return true,.
272a0 2a 2a 20 73 69 6e 63 65 20 74 68 65 20 73 74 61  ** since the sta
272b0 74 65 6d 65 6e 74 73 20 74 68 65 6d 73 65 6c 76  tements themselv
272c0 65 73 20 64 6f 20 6e 6f 74 20 61 63 74 75 61 6c  es do not actual
272d0 6c 79 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61  ly modify the da
272e0 74 61 62 61 73 65 20 62 75 74 0a 2a 2a 20 72 61  tabase but.** ra
272f0 74 68 65 72 20 74 68 65 79 20 63 6f 6e 74 72 6f  ther they contro
27300 6c 20 74 68 65 20 74 69 6d 69 6e 67 20 6f 66 20  l the timing of 
27310 77 68 65 6e 20 6f 74 68 65 72 20 73 74 61 74 65  when other state
27320 6d 65 6e 74 73 20 6d 6f 64 69 66 79 20 74 68 65  ments modify the
27330 20 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20   .** database.  
27340 5e 54 68 65 20 5b 41 54 54 41 43 48 5d 20 61 6e  ^The [ATTACH] an
27350 64 20 5b 44 45 54 41 43 48 5d 20 73 74 61 74 65  d [DETACH] state
27360 6d 65 6e 74 73 20 61 6c 73 6f 20 63 61 75 73 65  ments also cause
27370 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  .** sqlite3_stmt
27380 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72  _readonly() to r
27390 65 74 75 72 6e 20 74 72 75 65 20 73 69 6e 63 65  eturn true since
273a0 2c 20 77 68 69 6c 65 20 74 68 6f 73 65 20 73 74  , while those st
273b0 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 63 68 61 6e  atements.** chan
273c0 67 65 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61  ge the configura
273d0 74 69 6f 6e 20 6f 66 20 61 20 64 61 74 61 62 61  tion of a databa
273e0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 74  se connection, t
273f0 68 65 79 20 64 6f 20 6e 6f 74 20 6d 61 6b 65 20  hey do not make 
27400 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 74  .** changes to t
27410 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  he content of th
27420 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 73  e database files
27430 20 6f 6e 20 64 69 73 6b 2e 0a 2a 2f 0a 53 51 4c   on disk..*/.SQL
27440 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
27450 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c  te3_stmt_readonl
27460 79 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  y(sqlite3_stmt *
27470 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
27480 41 50 49 33 52 45 46 3a 20 44 79 6e 61 6d 69 63  API3REF: Dynamic
27490 61 6c 6c 79 20 54 79 70 65 64 20 56 61 6c 75 65  ally Typed Value
274a0 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f   Object.** KEYWO
274b0 52 44 53 3a 20 7b 70 72 6f 74 65 63 74 65 64 20  RDS: {protected 
274c0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 20 7b  sqlite3_value} {
274d0 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
274e0 74 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a  te3_value}.**.**
274f0 20 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65   SQLite uses the
27500 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
27510 62 6a 65 63 74 20 74 6f 20 72 65 70 72 65 73 65  bject to represe
27520 6e 74 20 61 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a  nt all values.**
27530 20 74 68 61 74 20 63 61 6e 20 62 65 20 73 74 6f   that can be sto
27540 72 65 64 20 69 6e 20 61 20 64 61 74 61 62 61 73  red in a databas
27550 65 20 74 61 62 6c 65 2e 20 53 51 4c 69 74 65 20  e table. SQLite 
27560 75 73 65 73 20 64 79 6e 61 6d 69 63 20 74 79 70  uses dynamic typ
27570 69 6e 67 0a 2a 2a 20 66 6f 72 20 74 68 65 20 76  ing.** for the v
27580 61 6c 75 65 73 20 69 74 20 73 74 6f 72 65 73 2e  alues it stores.
27590 20 20 5e 56 61 6c 75 65 73 20 73 74 6f 72 65 64    ^Values stored
275a0 20 69 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75   in sqlite3_valu
275b0 65 20 6f 62 6a 65 63 74 73 0a 2a 2a 20 63 61 6e  e objects.** can
275c0 20 62 65 20 69 6e 74 65 67 65 72 73 2c 20 66 6c   be integers, fl
275d0 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c  oating point val
275e0 75 65 73 2c 20 73 74 72 69 6e 67 73 2c 20 42 4c  ues, strings, BL
275f0 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a  OBs, or NULL..**
27600 0a 2a 2a 20 41 6e 20 73 71 6c 69 74 65 33 5f 76  .** An sqlite3_v
27610 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61 79 20  alue object may 
27620 62 65 20 65 69 74 68 65 72 20 22 70 72 6f 74 65  be either "prote
27630 63 74 65 64 22 20 6f 72 20 22 75 6e 70 72 6f 74  cted" or "unprot
27640 65 63 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20  ected"..** Some 
27650 69 6e 74 65 72 66 61 63 65 73 20 72 65 71 75 69  interfaces requi
27660 72 65 20 61 20 70 72 6f 74 65 63 74 65 64 20 73  re a protected s
27670 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20 20 4f  qlite3_value.  O
27680 74 68 65 72 20 69 6e 74 65 72 66 61 63 65 73 0a  ther interfaces.
27690 2a 2a 20 77 69 6c 6c 20 61 63 63 65 70 74 20 65  ** will accept e
276a0 69 74 68 65 72 20 61 20 70 72 6f 74 65 63 74 65  ither a protecte
276b0 64 20 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63  d or an unprotec
276c0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
276d0 65 2e 0a 2a 2a 20 45 76 65 72 79 20 69 6e 74 65  e..** Every inte
276e0 72 66 61 63 65 20 74 68 61 74 20 61 63 63 65 70  rface that accep
276f0 74 73 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ts sqlite3_value
27700 20 61 72 67 75 6d 65 6e 74 73 20 73 70 65 63 69   arguments speci
27710 66 69 65 73 0a 2a 2a 20 77 68 65 74 68 65 72 20  fies.** whether 
27720 6f 72 20 6e 6f 74 20 69 74 20 72 65 71 75 69 72  or not it requir
27730 65 73 20 61 20 70 72 6f 74 65 63 74 65 64 20 73  es a protected s
27740 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a  qlite3_value..**
27750 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73 20 22 70  .** The terms "p
27760 72 6f 74 65 63 74 65 64 22 20 61 6e 64 20 22 75  rotected" and "u
27770 6e 70 72 6f 74 65 63 74 65 64 22 20 72 65 66 65  nprotected" refe
27780 72 20 74 6f 20 77 68 65 74 68 65 72 20 6f 72 20  r to whether or 
27790 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78 20 69  not.** a mutex i
277a0 73 20 68 65 6c 64 2e 20 20 41 6e 20 69 6e 74 65  s held.  An inte
277b0 72 6e 61 6c 20 6d 75 74 65 78 20 69 73 20 68 65  rnal mutex is he
277c0 6c 64 20 66 6f 72 20 61 20 70 72 6f 74 65 63 74  ld for a protect
277d0 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  ed.** sqlite3_va
277e0 6c 75 65 20 6f 62 6a 65 63 74 20 62 75 74 20 6e  lue object but n
277f0 6f 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20  o mutex is held 
27800 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74  for an unprotect
27810 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  ed.** sqlite3_va
27820 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20 49 66 20  lue object.  If 
27830 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
27840 65 64 20 74 6f 20 62 65 20 73 69 6e 67 6c 65 2d  ed to be single-
27850 74 68 72 65 61 64 65 64 0a 2a 2a 20 28 77 69 74  threaded.** (wit
27860 68 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  h [SQLITE_THREAD
27870 53 41 46 45 3d 30 5d 20 61 6e 64 20 77 69 74 68  SAFE=0] and with
27880 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64   [sqlite3_thread
27890 73 61 66 65 28 29 5d 20 72 65 74 75 72 6e 69 6e  safe()] returnin
278a0 67 20 30 29 0a 2a 2a 20 6f 72 20 69 66 20 53 51  g 0).** or if SQ
278b0 4c 69 74 65 20 69 73 20 72 75 6e 20 69 6e 20 6f  Lite is run in o
278c0 6e 65 20 6f 66 20 72 65 64 75 63 65 64 20 6d 75  ne of reduced mu
278d0 74 65 78 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53  tex modes .** [S
278e0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
278f0 47 4c 45 54 48 52 45 41 44 5d 20 6f 72 20 5b 53  GLETHREAD] or [S
27900 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
27910 54 49 54 48 52 45 41 44 5d 0a 2a 2a 20 74 68 65  TITHREAD].** the
27920 6e 20 74 68 65 72 65 20 69 73 20 6e 6f 20 64 69  n there is no di
27930 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65  stinction betwee
27940 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20  n protected and 
27950 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  unprotected.** s
27960 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
27970 65 63 74 73 20 61 6e 64 20 74 68 65 79 20 63 61  ects and they ca
27980 6e 20 62 65 20 75 73 65 64 20 69 6e 74 65 72 63  n be used interc
27990 68 61 6e 67 65 61 62 6c 79 2e 20 20 48 6f 77 65  hangeably.  Howe
279a0 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78 69  ver,.** for maxi
279b0 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74 61 62 69  mum code portabi
279c0 6c 69 74 79 20 69 74 20 69 73 20 72 65 63 6f 6d  lity it is recom
279d0 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c  mended that appl
279e0 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c  ications.** stil
279f0 6c 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69  l make the disti
27a00 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70  nction between p
27a10 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70  rotected and unp
27a20 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69  rotected.** sqli
27a30 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
27a40 73 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74 20  s even when not 
27a50 73 74 72 69 63 74 6c 79 20 72 65 71 75 69 72 65  strictly require
27a60 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  d..**.** ^The sq
27a70 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
27a80 63 74 73 20 74 68 61 74 20 61 72 65 20 70 61 73  cts that are pas
27a90 73 65 64 20 61 73 20 70 61 72 61 6d 65 74 65 72  sed as parameter
27aa0 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d  s into the.** im
27ab0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
27ac0 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  [application-def
27ad0 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
27ae0 6e 73 5d 20 61 72 65 20 70 72 6f 74 65 63 74 65  ns] are protecte
27af0 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  d..** ^The sqlit
27b00 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20  e3_value object 
27b10 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b  returned by.** [
27b20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76  sqlite3_column_v
27b30 61 6c 75 65 28 29 5d 20 69 73 20 75 6e 70 72 6f  alue()] is unpro
27b40 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f  tected..** Unpro
27b50 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
27b60 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d 61 79  alue objects may
27b70 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69   only be used wi
27b80 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  th.** [sqlite3_r
27b90 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20 61  esult_value()] a
27ba0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  nd [sqlite3_bind
27bb0 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54 68  _value()]..** Th
27bc0 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
27bd0 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f  _blob | sqlite3_
27be0 76 61 6c 75 65 5f 74 79 70 65 28 29 5d 20 66 61  value_type()] fa
27bf0 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72  mily of.** inter
27c00 66 61 63 65 73 20 72 65 71 75 69 72 65 20 70 72  faces require pr
27c10 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
27c20 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a  value objects..*
27c30 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
27c40 20 4d 65 6d 20 73 71 6c 69 74 65 33 5f 76 61 6c   Mem sqlite3_val
27c50 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  ue;../*.** CAPI3
27c60 52 45 46 3a 20 53 51 4c 20 46 75 6e 63 74 69 6f  REF: SQL Functio
27c70 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74  n Context Object
27c80 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65  .**.** The conte
27c90 78 74 20 69 6e 20 77 68 69 63 68 20 61 6e 20 53  xt in which an S
27ca0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78 65 63  QL function exec
27cb0 75 74 65 73 20 69 73 20 73 74 6f 72 65 64 20 69  utes is stored i
27cc0 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  n an.** sqlite3_
27cd0 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e 20  context object. 
27ce0 20 5e 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61   ^A pointer to a
27cf0 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  n sqlite3_contex
27d00 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 73 20 61  t object.** is a
27d10 6c 77 61 79 73 20 66 69 72 73 74 20 70 61 72 61  lways first para
27d20 6d 65 74 65 72 20 74 6f 20 5b 61 70 70 6c 69 63  meter to [applic
27d30 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
27d40 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a  L functions]..**
27d50 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
27d60 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
27d70 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  ction implementa
27d80 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73 73 20 74  tion will pass t
27d90 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74  his.** pointer t
27da0 68 72 6f 75 67 68 20 69 6e 74 6f 20 63 61 6c 6c  hrough into call
27db0 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  s to [sqlite3_re
27dc0 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71 6c 69 74  sult_int | sqlit
27dd0 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a  e3_result()],.**
27de0 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67   [sqlite3_aggreg
27df0 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 5d 2c 20  ate_context()], 
27e00 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61  [sqlite3_user_da
27e10 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  ta()],.** [sqlit
27e20 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61  e3_context_db_ha
27e30 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65  ndle()], [sqlite
27e40 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 5d  3_get_auxdata()]
27e50 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73 71 6c  ,.** and/or [sql
27e60 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
27e70 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ()]..*/.typedef 
27e80 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 63  struct sqlite3_c
27e90 6f 6e 74 65 78 74 20 73 71 6c 69 74 65 33 5f 63  ontext sqlite3_c
27ea0 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ontext;../*.** C
27eb0 41 50 49 33 52 45 46 3a 20 42 69 6e 64 69 6e 67  API3REF: Binding
27ec0 20 56 61 6c 75 65 73 20 54 6f 20 50 72 65 70 61   Values To Prepa
27ed0 72 65 64 20 53 74 61 74 65 6d 65 6e 74 73 0a 2a  red Statements.*
27ee0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 68 6f 73  * KEYWORDS: {hos
27ef0 74 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 68 6f  t parameter} {ho
27f00 73 74 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b  st parameters} {
27f10 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e  host parameter n
27f20 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ame}.** KEYWORDS
27f30 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72  : {SQL parameter
27f40 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72  } {SQL parameter
27f50 73 7d 20 7b 70 61 72 61 6d 65 74 65 72 20 62 69  s} {parameter bi
27f60 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a 20 5e 28 49  nding}.**.** ^(I
27f70 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  n the SQL statem
27f80 65 6e 74 20 74 65 78 74 20 69 6e 70 75 74 20 74  ent text input t
27f90 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  o [sqlite3_prepa
27fa0 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 69 74 73  re_v2()] and its
27fb0 20 76 61 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69   variants,.** li
27fc0 74 65 72 61 6c 73 20 6d 61 79 20 62 65 20 72 65  terals may be re
27fd0 70 6c 61 63 65 64 20 62 79 20 61 20 5b 70 61 72  placed by a [par
27fe0 61 6d 65 74 65 72 5d 20 74 68 61 74 20 6d 61 74  ameter] that mat
27ff0 63 68 65 73 20 6f 6e 65 20 6f 66 20 66 6f 6c 6c  ches one of foll
28000 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d 70 6c 61 74  owing.** templat
28010 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  es:.**.** <ul>.*
28020 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69  * <li>  ?.** <li
28030 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20  >  ?NNN.** <li> 
28040 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40   :VVV.** <li>  @
28050 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56 56  VVV.** <li>  $VV
28060 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  V.** </ul>.**.**
28070 20 49 6e 20 74 68 65 20 74 65 6d 70 6c 61 74 65   In the template
28080 73 20 61 62 6f 76 65 2c 20 4e 4e 4e 20 72 65 70  s above, NNN rep
28090 72 65 73 65 6e 74 73 20 61 6e 20 69 6e 74 65 67  resents an integ
280a0 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20 61  er literal,.** a
280b0 6e 64 20 56 56 56 20 72 65 70 72 65 73 65 6e 74  nd VVV represent
280c0 73 20 61 6e 20 61 6c 70 68 61 6e 75 6d 65 72 69  s an alphanumeri
280d0 63 20 69 64 65 6e 74 69 66 69 65 72 2e 29 5e 20  c identifier.)^ 
280e0 20 5e 54 68 65 20 76 61 6c 75 65 73 20 6f 66 20   ^The values of 
280f0 74 68 65 73 65 0a 2a 2a 20 70 61 72 61 6d 65 74  these.** paramet
28100 65 72 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65 64  ers (also called
28110 20 22 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72   "host parameter
28120 20 6e 61 6d 65 73 22 20 6f 72 20 22 53 51 4c 20   names" or "SQL 
28130 70 61 72 61 6d 65 74 65 72 73 22 29 0a 2a 2a 20  parameters").** 
28140 63 61 6e 20 62 65 20 73 65 74 20 75 73 69 6e 67  can be set using
28150 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   the sqlite3_bin
28160 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 64  d_*() routines d
28170 65 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a  efined here..**.
28180 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  ** ^The first ar
28190 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71  gument to the sq
281a0 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72  lite3_bind_*() r
281b0 6f 75 74 69 6e 65 73 20 69 73 20 61 6c 77 61 79  outines is alway
281c0 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74  s.** a pointer t
281d0 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  o the [sqlite3_s
281e0 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65 74 75  tmt] object retu
281f0 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71  rned from.** [sq
28200 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
28210 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61  ()] or its varia
28220 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  nts..**.** ^The 
28230 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
28240 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20  is the index of 
28250 74 68 65 20 53 51 4c 20 70 61 72 61 6d 65 74 65  the SQL paramete
28260 72 20 74 6f 20 62 65 20 73 65 74 2e 0a 2a 2a 20  r to be set..** 
28270 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 53 51  ^The leftmost SQ
28280 4c 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20  L parameter has 
28290 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2e 20 20  an index of 1.  
282a0 5e 57 68 65 6e 20 74 68 65 20 73 61 6d 65 20 6e  ^When the same n
282b0 61 6d 65 64 0a 2a 2a 20 53 51 4c 20 70 61 72 61  amed.** SQL para
282c0 6d 65 74 65 72 20 69 73 20 75 73 65 64 20 6d 6f  meter is used mo
282d0 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 73 65  re than once, se
282e0 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75  cond and subsequ
282f0 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65 6e 63  ent.** occurrenc
28300 65 73 20 68 61 76 65 20 74 68 65 20 73 61 6d 65  es have the same
28310 20 69 6e 64 65 78 20 61 73 20 74 68 65 20 66 69   index as the fi
28320 72 73 74 20 6f 63 63 75 72 72 65 6e 63 65 2e 0a  rst occurrence..
28330 2a 2a 20 5e 54 68 65 20 69 6e 64 65 78 20 66 6f  ** ^The index fo
28340 72 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65  r named paramete
28350 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f 6b 65 64  rs can be looked
28360 20 75 70 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a   up using the.**
28370 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
28380 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29  arameter_index()
28390 5d 20 41 50 49 20 69 66 20 64 65 73 69 72 65 64  ] API if desired
283a0 2e 20 20 5e 54 68 65 20 69 6e 64 65 78 0a 2a 2a  .  ^The index.**
283b0 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61 72 61   for "?NNN" para
283c0 6d 65 74 65 72 73 20 69 73 20 74 68 65 20 76 61  meters is the va
283d0 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e  lue of NNN..** ^
283e0 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d 75  The NNN value mu
283f0 73 74 20 62 65 20 62 65 74 77 65 65 6e 20 31 20  st be between 1 
28400 61 6e 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33  and the [sqlite3
28410 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 70 61 72  _limit()].** par
28420 61 6d 65 74 65 72 20 5b 53 51 4c 49 54 45 5f 4c  ameter [SQLITE_L
28430 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55  IMIT_VARIABLE_NU
28440 4d 42 45 52 5d 20 28 64 65 66 61 75 6c 74 20 76  MBER] (default v
28450 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a  alue: 999)..**.*
28460 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61 72 67  * ^The third arg
28470 75 6d 65 6e 74 20 69 73 20 74 68 65 20 76 61 6c  ument is the val
28480 75 65 20 74 6f 20 62 69 6e 64 20 74 6f 20 74 68  ue to bind to th
28490 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  e parameter..**.
284a0 2a 2a 20 5e 28 49 6e 20 74 68 6f 73 65 20 72 6f  ** ^(In those ro
284b0 75 74 69 6e 65 73 20 74 68 61 74 20 68 61 76 65  utines that have
284c0 20 61 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65   a fourth argume
284d0 6e 74 2c 20 69 74 73 20 76 61 6c 75 65 20 69 73  nt, its value is
284e0 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f   the.** number o
284f0 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 70  f bytes in the p
28500 61 72 61 6d 65 74 65 72 2e 20 20 54 6f 20 62 65  arameter.  To be
28510 20 63 6c 65 61 72 3a 20 74 68 65 20 76 61 6c 75   clear: the valu
28520 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62  e is the.** numb
28530 65 72 20 6f 66 20 3c 75 3e 62 79 74 65 73 3c 2f  er of <u>bytes</
28540 75 3e 20 69 6e 20 74 68 65 20 76 61 6c 75 65 2c  u> in the value,
28550 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20   not the number 
28560 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 29 5e  of characters.)^
28570 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 6f 75 72  .** ^If the four
28580 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
28590 6e 65 67 61 74 69 76 65 2c 20 74 68 65 20 6c 65  negative, the le
285a0 6e 67 74 68 20 6f 66 20 74 68 65 20 73 74 72 69  ngth of the stri
285b0 6e 67 20 69 73 0a 2a 2a 20 74 68 65 20 6e 75 6d  ng is.** the num
285c0 62 65 72 20 6f 66 20 62 79 74 65 73 20 75 70 20  ber of bytes up 
285d0 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 72  to the first zer
285e0 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a  o terminator..**
285f0 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74 68 20 61  .** ^The fifth a
28600 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
28610 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 20  e3_bind_blob(), 
28620 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
28630 74 28 29 2c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69  t(), and.** sqli
28640 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28  te3_bind_text16(
28650 29 20 69 73 20 61 20 64 65 73 74 72 75 63 74 6f  ) is a destructo
28660 72 20 75 73 65 64 20 74 6f 20 64 69 73 70 6f 73  r used to dispos
28670 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72  e of the BLOB or
28680 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66 74 65 72  .** string after
28690 20 53 51 4c 69 74 65 20 68 61 73 20 66 69 6e 69   SQLite has fini
286a0 73 68 65 64 20 77 69 74 68 20 69 74 2e 20 20 5e  shed with it.  ^
286b0 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69  The destructor i
286c0 73 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 6f 20 64  s called.** to d
286d0 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c  ispose of the BL
286e0 4f 42 20 6f 72 20 73 74 72 69 6e 67 20 65 76 65  OB or string eve
286f0 6e 20 69 66 20 74 68 65 20 63 61 6c 6c 20 74 6f  n if the call to
28700 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c   sqlite3_bind_bl
28710 6f 62 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33  ob(),.** sqlite3
28720 5f 62 69 6e 64 5f 74 65 78 74 28 29 2c 20 6f 72  _bind_text(), or
28730 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
28740 78 74 31 36 28 29 20 66 61 69 6c 73 2e 20 20 0a  xt16() fails.  .
28750 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74 68  ** ^If the fifth
28760 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20   argument is.** 
28770 74 68 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75  the special valu
28780 65 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43  e [SQLITE_STATIC
28790 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 61  ], then SQLite a
287a0 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a  ssumes that the.
287b0 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  ** information i
287c0 73 20 69 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d  s in static, unm
287d0 61 6e 61 67 65 64 20 73 70 61 63 65 20 61 6e 64  anaged space and
287e0 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74   does not need t
287f0 6f 20 62 65 20 66 72 65 65 64 2e 0a 2a 2a 20 5e  o be freed..** ^
28800 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72 67  If the fifth arg
28810 75 6d 65 6e 74 20 68 61 73 20 74 68 65 20 76 61  ument has the va
28820 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e  lue [SQLITE_TRAN
28830 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20  SIENT], then.** 
28840 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 69 74 73  SQLite makes its
28850 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70   own private cop
28860 79 20 6f 66 20 74 68 65 20 64 61 74 61 20 69 6d  y of the data im
28870 6d 65 64 69 61 74 65 6c 79 2c 20 62 65 66 6f 72  mediately, befor
28880 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33  e.** the sqlite3
28890 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e  _bind_*() routin
288a0 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a  e returns..**.**
288b0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69   ^The sqlite3_bi
288c0 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f  nd_zeroblob() ro
288d0 75 74 69 6e 65 20 62 69 6e 64 73 20 61 20 42 4c  utine binds a BL
288e0 4f 42 20 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74  OB of length N t
288f0 68 61 74 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64  hat.** is filled
28900 20 77 69 74 68 20 7a 65 72 6f 65 73 2e 20 20 5e   with zeroes.  ^
28910 41 20 7a 65 72 6f 62 6c 6f 62 20 75 73 65 73 20  A zeroblob uses 
28920 61 20 66 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f  a fixed amount o
28930 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73  f memory.** (jus
28940 74 20 61 6e 20 69 6e 74 65 67 65 72 20 74 6f 20  t an integer to 
28950 68 6f 6c 64 20 69 74 73 20 73 69 7a 65 29 20 77  hold its size) w
28960 68 69 6c 65 20 69 74 20 69 73 20 62 65 69 6e 67  hile it is being
28970 20 70 72 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a   processed..** Z
28980 65 72 6f 62 6c 6f 62 73 20 61 72 65 20 69 6e 74  eroblobs are int
28990 65 6e 64 65 64 20 74 6f 20 73 65 72 76 65 20 61  ended to serve a
289a0 73 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66  s placeholders f
289b0 6f 72 20 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a  or BLOBs whose.*
289c0 2a 20 63 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74  * content is lat
289d0 65 72 20 77 72 69 74 74 65 6e 20 75 73 69 6e 67  er written using
289e0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  .** [sqlite3_blo
289f0 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65  b_open | increme
28a00 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 72  ntal BLOB I/O] r
28a10 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 5e 41 20 6e  outines..** ^A n
28a20 65 67 61 74 69 76 65 20 76 61 6c 75 65 20 66 6f  egative value fo
28a30 72 20 74 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72  r the zeroblob r
28a40 65 73 75 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f  esults in a zero
28a50 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a  -length BLOB..**
28a60 0a 2a 2a 20 5e 49 66 20 61 6e 79 20 6f 66 20 74  .** ^If any of t
28a70 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
28a80 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 61 72 65  *() routines are
28a90 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e   called with a N
28aa0 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 66  ULL pointer.** f
28ab0 6f 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  or the [prepared
28ac0 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 72 20 77   statement] or w
28ad0 69 74 68 20 61 20 70 72 65 70 61 72 65 64 20 73  ith a prepared s
28ae0 74 61 74 65 6d 65 6e 74 20 66 6f 72 20 77 68 69  tatement for whi
28af0 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  ch.** [sqlite3_s
28b00 74 65 70 28 29 5d 20 68 61 73 20 62 65 65 6e 20  tep()] has been 
28b10 63 61 6c 6c 65 64 20 6d 6f 72 65 20 72 65 63 65  called more rece
28b20 6e 74 6c 79 20 74 68 61 6e 20 5b 73 71 6c 69 74  ntly than [sqlit
28b30 65 33 5f 72 65 73 65 74 28 29 5d 2c 0a 2a 2a 20  e3_reset()],.** 
28b40 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 20 77 69  then the call wi
28b50 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ll return [SQLIT
28b60 45 5f 4d 49 53 55 53 45 5d 2e 20 20 49 66 20 61  E_MISUSE].  If a
28b70 6e 79 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  ny sqlite3_bind_
28b80 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 69 73  ().** routine is
28b90 20 70 61 73 73 65 64 20 61 20 5b 70 72 65 70 61   passed a [prepa
28ba0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74  red statement] t
28bb0 68 61 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e  hat has been fin
28bc0 61 6c 69 7a 65 64 2c 20 74 68 65 0a 2a 2a 20 72  alized, the.** r
28bd0 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e  esult is undefin
28be0 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20  ed and probably 
28bf0 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e  harmful..**.** ^
28c00 42 69 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f 74  Bindings are not
28c10 20 63 6c 65 61 72 65 64 20 62 79 20 74 68 65 20   cleared by the 
28c20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
28c30 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 5e 55  ] routine..** ^U
28c40 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72  nbound parameter
28c50 73 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65  s are interprete
28c60 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  d as NULL..**.**
28c70 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69   ^The sqlite3_bi
28c80 6e 64 5f 2a 20 72 6f 75 74 69 6e 65 73 20 72 65  nd_* routines re
28c90 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
28ca0 20 6f 6e 20 73 75 63 63 65 73 73 20 6f 72 20 61   on success or a
28cb0 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65  n.** [error code
28cc0 5d 20 69 66 20 61 6e 79 74 68 69 6e 67 20 67 6f  ] if anything go
28cd0 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53  es wrong..** ^[S
28ce0 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20 69 73 20  QLITE_RANGE] is 
28cf0 72 65 74 75 72 6e 65 64 20 69 66 20 74 68 65 20  returned if the 
28d00 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64  parameter.** ind
28d10 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e  ex is out of ran
28d20 67 65 2e 20 20 5e 5b 53 51 4c 49 54 45 5f 4e 4f  ge.  ^[SQLITE_NO
28d30 4d 45 4d 5d 20 69 73 20 72 65 74 75 72 6e 65 64  MEM] is returned
28d40 20 69 66 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69   if malloc() fai
28d50 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ls..**.** See al
28d60 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  so: [sqlite3_bin
28d70 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e  d_parameter_coun
28d80 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  t()],.** [sqlite
28d90 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
28da0 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 20 5b 73  _name()], and [s
28db0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
28dc0 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a  meter_index()]..
28dd0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
28de0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62  t sqlite3_bind_b
28df0 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lob(sqlite3_stmt
28e00 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f  *, int, const vo
28e10 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64  id*, int n, void
28e20 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c  (*)(void*));.SQL
28e30 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
28e40 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c 65 28  te3_bind_double(
28e50 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
28e60 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 53 51 4c  nt, double);.SQL
28e70 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
28e80 74 65 33 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c  te3_bind_int(sql
28e90 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
28ea0 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50   int);.SQLITE_AP
28eb0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  I int sqlite3_bi
28ec0 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33  nd_int64(sqlite3
28ed0 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c  _stmt*, int, sql
28ee0 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 53 51 4c  ite3_int64);.SQL
28ef0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
28f00 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 71  te3_bind_null(sq
28f10 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
28f20 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
28f30 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  t sqlite3_bind_t
28f40 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ext(sqlite3_stmt
28f50 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63 68  *, int, const ch
28f60 61 72 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64  ar*, int n, void
28f70 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c  (*)(void*));.SQL
28f80 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
28f90 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28  te3_bind_text16(
28fa0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
28fb0 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  nt, const void*,
28fc0 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f   int, void(*)(vo
28fd0 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50  id*));.SQLITE_AP
28fe0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  I int sqlite3_bi
28ff0 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33  nd_value(sqlite3
29000 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e  _stmt*, int, con
29010 73 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  st sqlite3_value
29020 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  *);.SQLITE_API i
29030 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
29040 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33  zeroblob(sqlite3
29050 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74  _stmt*, int, int
29060 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49   n);../*.** CAPI
29070 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20  3REF: Number Of 
29080 53 51 4c 20 50 61 72 61 6d 65 74 65 72 73 0a 2a  SQL Parameters.*
29090 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69  *.** ^This routi
290a0 6e 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  ne can be used t
290b0 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65  o find the numbe
290c0 72 20 6f 66 20 5b 53 51 4c 20 70 61 72 61 6d 65  r of [SQL parame
290d0 74 65 72 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70  ters].** in a [p
290e0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
290f0 74 5d 2e 20 20 53 51 4c 20 70 61 72 61 6d 65 74  t].  SQL paramet
29100 65 72 73 20 61 72 65 20 74 6f 6b 65 6e 73 20 6f  ers are tokens o
29110 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f  f the.** form "?
29120 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41  ", "?NNN", ":AAA
29130 22 2c 20 22 24 41 41 41 22 2c 20 6f 72 20 22 40  ", "$AAA", or "@
29140 41 41 41 22 20 74 68 61 74 20 73 65 72 76 65 20  AAA" that serve 
29150 61 73 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 65  as.** placeholde
29160 72 73 20 66 6f 72 20 76 61 6c 75 65 73 20 74 68  rs for values th
29170 61 74 20 61 72 65 20 5b 73 71 6c 69 74 65 33 5f  at are [sqlite3_
29180 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e  bind_blob | boun
29190 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 70 61 72  d].** to the par
291a0 61 6d 65 74 65 72 73 20 61 74 20 61 20 6c 61 74  ameters at a lat
291b0 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e  er time..**.** ^
291c0 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20 61 63  (This routine ac
291d0 74 75 61 6c 6c 79 20 72 65 74 75 72 6e 73 20 74  tually returns t
291e0 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20  he index of the 
291f0 6c 61 72 67 65 73 74 20 28 72 69 67 68 74 6d 6f  largest (rightmo
29200 73 74 29 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  st).** parameter
29210 2e 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d 73 20  . For all forms 
29220 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74 68 69  except ?NNN, thi
29230 73 20 77 69 6c 6c 20 63 6f 72 72 65 73 70 6f 6e  s will correspon
29240 64 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d 62  d to the.** numb
29250 65 72 20 6f 66 20 75 6e 69 71 75 65 20 70 61 72  er of unique par
29260 61 6d 65 74 65 72 73 2e 20 20 49 66 20 70 61 72  ameters.  If par
29270 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 3f  ameters of the ?
29280 4e 4e 4e 20 66 6f 72 6d 20 61 72 65 20 75 73 65  NNN form are use
29290 64 2c 0a 2a 2a 20 74 68 65 72 65 20 6d 61 79 20  d,.** there may 
292a0 62 65 20 67 61 70 73 20 69 6e 20 74 68 65 20 6c  be gaps in the l
292b0 69 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65  ist.)^.**.** See
292c0 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
292d0 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65  bind_blob|sqlite
292e0 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73  3_bind()],.** [s
292f0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
29300 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61  meter_name()], a
29310 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  nd.** [sqlite3_b
29320 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
29330 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54  dex()]..*/.SQLIT
29340 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
29350 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
29360 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73  _count(sqlite3_s
29370 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tmt*);../*.** CA
29380 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20  PI3REF: Name Of 
29390 41 20 48 6f 73 74 20 50 61 72 61 6d 65 74 65 72  A Host Parameter
293a0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
293b0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
293c0 65 72 5f 6e 61 6d 65 28 50 2c 4e 29 20 69 6e 74  er_name(P,N) int
293d0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a  erface returns.*
293e0 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  * the name of th
293f0 65 20 4e 2d 74 68 20 5b 53 51 4c 20 70 61 72 61  e N-th [SQL para
29400 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20 5b 70  meter] in the [p
29410 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
29420 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53 51 4c 20 70  t] P..** ^(SQL p
29430 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65  arameters of the
29440 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20   form "?NNN" or 
29450 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22  ":AAA" or "@AAA"
29460 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 68 61   or "$AAA".** ha
29470 76 65 20 61 20 6e 61 6d 65 20 77 68 69 63 68 20  ve a name which 
29480 69 73 20 74 68 65 20 73 74 72 69 6e 67 20 22 3f  is the string "?
29490 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f  NNN" or ":AAA" o
294a0 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41  r "@AAA" or "$AA
294b0 41 22 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65  A".** respective
294c0 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20  ly..** In other 
294d0 77 6f 72 64 73 2c 20 74 68 65 20 69 6e 69 74 69  words, the initi
294e0 61 6c 20 22 3a 22 20 6f 72 20 22 24 22 20 6f 72  al ":" or "$" or
294f0 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a 2a 20 69   "@" or "?".** i
29500 73 20 69 6e 63 6c 75 64 65 64 20 61 73 20 70 61  s included as pa
29510 72 74 20 6f 66 20 74 68 65 20 6e 61 6d 65 2e 29  rt of the name.)
29520 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65 74 65 72 73  ^.** ^Parameters
29530 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 22   of the form "?"
29540 20 77 69 74 68 6f 75 74 20 61 20 66 6f 6c 6c 6f   without a follo
29550 77 69 6e 67 20 69 6e 74 65 67 65 72 20 68 61 76  wing integer hav
29560 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64  e no name.** and
29570 20 61 72 65 20 72 65 66 65 72 72 65 64 20 74 6f   are referred to
29580 20 61 73 20 22 6e 61 6d 65 6c 65 73 73 22 20 6f   as "nameless" o
29590 72 20 22 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72  r "anonymous par
295a0 61 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20  ameters"..**.** 
295b0 5e 54 68 65 20 66 69 72 73 74 20 68 6f 73 74 20  ^The first host 
295c0 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e  parameter has an
295d0 20 69 6e 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74   index of 1, not
295e0 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68   0..**.** ^If th
295f0 65 20 76 61 6c 75 65 20 4e 20 69 73 20 6f 75 74  e value N is out
29600 20 6f 66 20 72 61 6e 67 65 20 6f 72 20 69 66 20   of range or if 
29610 74 68 65 20 4e 2d 74 68 20 70 61 72 61 6d 65 74  the N-th paramet
29620 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73  er is.** nameles
29630 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20  s, then NULL is 
29640 72 65 74 75 72 6e 65 64 2e 20 20 5e 54 68 65 20  returned.  ^The 
29650 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20  returned string 
29660 69 73 0a 2a 2a 20 61 6c 77 61 79 73 20 69 6e 20  is.** always in 
29670 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65  UTF-8 encoding e
29680 76 65 6e 20 69 66 20 74 68 65 20 6e 61 6d 65 64  ven if the named
29690 20 70 61 72 61 6d 65 74 65 72 20 77 61 73 0a 2a   parameter was.*
296a0 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 20 73 70 65  * originally spe
296b0 63 69 66 69 65 64 20 61 73 20 55 54 46 2d 31 36  cified as UTF-16
296c0 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   in [sqlite3_pre
296d0 70 61 72 65 31 36 28 29 5d 20 6f 72 0a 2a 2a 20  pare16()] or.** 
296e0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
296f0 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  16_v2()]..**.** 
29700 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
29710 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c  e3_bind_blob|sql
29720 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a  ite3_bind()],.**
29730 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
29740 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29  arameter_count()
29750 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  ], and.** [sqlit
29760 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
29770 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53  r_index()]..*/.S
29780 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
29790 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 62 69  char *sqlite3_bi
297a0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d  nd_parameter_nam
297b0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
297c0 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   int);../*.** CA
297d0 50 49 33 52 45 46 3a 20 49 6e 64 65 78 20 4f 66  PI3REF: Index Of
297e0 20 41 20 50 61 72 61 6d 65 74 65 72 20 57 69 74   A Parameter Wit
297f0 68 20 41 20 47 69 76 65 6e 20 4e 61 6d 65 0a 2a  h A Given Name.*
29800 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65  *.** ^Return the
29810 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 53 51 4c   index of an SQL
29820 20 70 61 72 61 6d 65 74 65 72 20 67 69 76 65 6e   parameter given
29830 20 69 74 73 20 6e 61 6d 65 2e 20 20 5e 54 68 65   its name.  ^The
29840 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75 65 20  .** index value 
29850 72 65 74 75 72 6e 65 64 20 69 73 20 73 75 69 74  returned is suit
29860 61 62 6c 65 20 66 6f 72 20 75 73 65 20 61 73 20  able for use as 
29870 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61  the second.** pa
29880 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
29890 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71  te3_bind_blob|sq
298a0 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20  lite3_bind()].  
298b0 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65  ^A zero.** is re
298c0 74 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74  turned if no mat
298d0 63 68 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20  ching parameter 
298e0 69 73 20 66 6f 75 6e 64 2e 20 20 5e 54 68 65 20  is found.  ^The 
298f0 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d  parameter.** nam
29900 65 20 6d 75 73 74 20 62 65 20 67 69 76 65 6e 20  e must be given 
29910 69 6e 20 55 54 46 2d 38 20 65 76 65 6e 20 69 66  in UTF-8 even if
29920 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74   the original st
29930 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 70  atement.** was p
29940 72 65 70 61 72 65 64 20 66 72 6f 6d 20 55 54 46  repared from UTF
29950 2d 31 36 20 74 65 78 74 20 75 73 69 6e 67 20 5b  -16 text using [
29960 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
29970 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53  6_v2()]..**.** S
29980 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
29990 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69  3_bind_blob|sqli
299a0 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20  te3_bind()],.** 
299b0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
299c0 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d  rameter_count()]
299d0 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  , and.** [sqlite
299e0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
299f0 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51  _index()]..*/.SQ
29a00 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
29a10 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
29a20 74 65 72 5f 69 6e 64 65 78 28 73 71 6c 69 74 65  ter_index(sqlite
29a30 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63  3_stmt*, const c
29a40 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a  har *zName);../*
29a50 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
29a60 73 65 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73  set All Bindings
29a70 20 4f 6e 20 41 20 50 72 65 70 61 72 65 64 20 53   On A Prepared S
29a80 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e  tatement.**.** ^
29a90 43 6f 6e 74 72 61 72 79 20 74 6f 20 74 68 65 20  Contrary to the 
29aa0 69 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d 61 6e  intuition of man
29ab0 79 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  y, [sqlite3_rese
29ac0 74 28 29 5d 20 64 6f 65 73 20 6e 6f 74 20 72 65  t()] does not re
29ad0 73 65 74 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69  set.** the [sqli
29ae0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20  te3_bind_blob | 
29af0 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 20 5b  bindings] on a [
29b00 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
29b10 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 65 20 74 68 69  nt]..** ^Use thi
29b20 73 20 72 6f 75 74 69 6e 65 20 74 6f 20 72 65 73  s routine to res
29b30 65 74 20 61 6c 6c 20 68 6f 73 74 20 70 61 72 61  et all host para
29b40 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a  meters to NULL..
29b50 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
29b60 74 20 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f  t sqlite3_clear_
29b70 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33  bindings(sqlite3
29b80 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  _stmt*);../*.** 
29b90 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72  CAPI3REF: Number
29ba0 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41   Of Columns In A
29bb0 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a   Result Set.**.*
29bc0 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20 6e 75  * ^Return the nu
29bd0 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
29be0 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  in the result se
29bf0 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  t returned by th
29c00 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
29c10 74 61 74 65 6d 65 6e 74 5d 2e 20 5e 54 68 69 73  tatement]. ^This
29c20 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
29c30 20 30 20 69 66 20 70 53 74 6d 74 20 69 73 20 61   0 if pStmt is a
29c40 6e 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65  n SQL.** stateme
29c50 6e 74 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74  nt that does not
29c60 20 72 65 74 75 72 6e 20 64 61 74 61 20 28 66 6f   return data (fo
29c70 72 20 65 78 61 6d 70 6c 65 20 61 6e 20 5b 55 50  r example an [UP
29c80 44 41 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65  DATE])..**.** Se
29c90 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
29ca0 5f 64 61 74 61 5f 63 6f 75 6e 74 28 29 5d 0a 2a  _data_count()].*
29cb0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
29cc0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
29cd0 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  count(sqlite3_st
29ce0 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
29cf0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c  ** CAPI3REF: Col
29d00 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41 20 52  umn Names In A R
29d10 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20  esult Set.**.** 
29d20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
29d30 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20  return the name 
29d40 61 73 73 69 67 6e 65 64 20 74 6f 20 61 20 70 61  assigned to a pa
29d50 72 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a  rticular column.
29d60 2a 2a 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74  ** in the result
29d70 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43   set of a [SELEC
29d80 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e  T] statement.  ^
29d90 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  The sqlite3_colu
29da0 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74  mn_name().** int
29db0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
29dc0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65   pointer to a ze
29dd0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
29de0 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61 6e  F-8 string.** an
29df0 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
29e00 5f 6e 61 6d 65 31 36 28 29 20 72 65 74 75 72 6e  _name16() return
29e10 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
29e20 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
29e30 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e  .** UTF-16 strin
29e40 67 2e 20 20 5e 54 68 65 20 66 69 72 73 74 20 70  g.  ^The first p
29e50 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
29e60 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
29e70 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d 70  ent].** that imp
29e80 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b 53 45 4c  lements the [SEL
29e90 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20  ECT] statement. 
29ea0 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61  ^The second para
29eb0 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20  meter is the.** 
29ec0 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 20  column number.  
29ed0 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f  ^The leftmost co
29ee0 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20 30  lumn is number 0
29ef0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 74  ..**.** ^The ret
29f00 75 72 6e 65 64 20 73 74 72 69 6e 67 20 70 6f 69  urned string poi
29f10 6e 74 65 72 20 69 73 20 76 61 6c 69 64 20 75 6e  nter is valid un
29f20 74 69 6c 20 65 69 74 68 65 72 20 74 68 65 20 5b  til either the [
29f30 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
29f40 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74 72 6f  nt].** is destro
29f50 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  yed by [sqlite3_
29f60 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75  finalize()] or u
29f70 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65  ntil the stateme
29f80 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61  nt is automatica
29f90 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65  lly.** reprepare
29fa0 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20 63  d by the first c
29fb0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
29fc0 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61  step()] for a pa
29fd0 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20  rticular run.** 
29fe0 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78  or until the nex
29ff0 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c  t call to.** sql
2a000 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
2a010 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f  () or sqlite3_co
2a020 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f 6e  lumn_name16() on
2a030 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e   the same column
2a040 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c 69  ..**.** ^If sqli
2a050 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69  te3_malloc() fai
2a060 6c 73 20 64 75 72 69 6e 67 20 74 68 65 20 70 72  ls during the pr
2a070 6f 63 65 73 73 69 6e 67 20 6f 66 20 65 69 74 68  ocessing of eith
2a080 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66  er routine.** (f
2a090 6f 72 20 65 78 61 6d 70 6c 65 20 64 75 72 69 6e  or example durin
2a0a0 67 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66  g a conversion f
2a0b0 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55 54 46  rom UTF-8 to UTF
2a0c0 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e  -16) then a.** N
2a0d0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72  ULL pointer is r
2a0e0 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  eturned..**.** ^
2a0f0 54 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 72 65  The name of a re
2a100 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74  sult column is t
2a110 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  he value of the 
2a120 22 41 53 22 20 63 6c 61 75 73 65 20 66 6f 72 0a  "AS" clause for.
2a130 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20  ** that column, 
2a140 69 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 41  if there is an A
2a150 53 20 63 6c 61 75 73 65 2e 20 20 49 66 20 74 68  S clause.  If th
2a160 65 72 65 20 69 73 20 6e 6f 20 41 53 20 63 6c 61  ere is no AS cla
2a170 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  use.** then the 
2a180 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 75  name of the colu
2a190 6d 6e 20 69 73 20 75 6e 73 70 65 63 69 66 69 65  mn is unspecifie
2a1a0 64 20 61 6e 64 20 6d 61 79 20 63 68 61 6e 67 65  d and may change
2a1b0 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c   from.** one rel
2a1c0 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20 74  ease of SQLite t
2a1d0 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a 53  o the next..*/.S
2a1e0 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
2a1f0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
2a200 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65  lumn_name(sqlite
2a210 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b  3_stmt*, int N);
2a220 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
2a230 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
2a240 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71  column_name16(sq
2a250 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2a260 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49   N);../*.** CAPI
2a270 33 52 45 46 3a 20 53 6f 75 72 63 65 20 4f 66 20  3REF: Source Of 
2a280 44 61 74 61 20 49 6e 20 41 20 51 75 65 72 79 20  Data In A Query 
2a290 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  Result.**.** ^Th
2a2a0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 70 72 6f  ese routines pro
2a2b0 76 69 64 65 20 61 20 6d 65 61 6e 73 20 74 6f 20  vide a means to 
2a2c0 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 64 61  determine the da
2a2d0 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61  tabase, table, a
2a2e0 6e 64 0a 2a 2a 20 74 61 62 6c 65 20 63 6f 6c 75  nd.** table colu
2a2f0 6d 6e 20 74 68 61 74 20 69 73 20 74 68 65 20 6f  mn that is the o
2a300 72 69 67 69 6e 20 6f 66 20 61 20 70 61 72 74 69  rigin of a parti
2a310 63 75 6c 61 72 20 72 65 73 75 6c 74 20 63 6f 6c  cular result col
2a320 75 6d 6e 20 69 6e 0a 2a 2a 20 5b 53 45 4c 45 43  umn in.** [SELEC
2a330 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a  T] statement..**
2a340 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68   ^The name of th
2a350 65 20 64 61 74 61 62 61 73 65 20 6f 72 20 74 61  e database or ta
2a360 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61  ble or column ca
2a370 6e 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 73  n be returned as
2a380 0a 2a 2a 20 65 69 74 68 65 72 20 61 20 55 54 46  .** either a UTF
2a390 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72  -8 or UTF-16 str
2a3a0 69 6e 67 2e 20 20 5e 54 68 65 20 5f 64 61 74 61  ing.  ^The _data
2a3b0 62 61 73 65 5f 20 72 6f 75 74 69 6e 65 73 20 72  base_ routines r
2a3c0 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74  eturn.** the dat
2a3d0 61 62 61 73 65 20 6e 61 6d 65 2c 20 74 68 65 20  abase name, the 
2a3e0 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73  _table_ routines
2a3f0 20 72 65 74 75 72 6e 20 74 68 65 20 74 61 62 6c   return the tabl
2a400 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74  e name, and.** t
2a410 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69  he origin_ routi
2a420 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 63  nes return the c
2a430 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 5e  olumn name..** ^
2a440 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72  The returned str
2a450 69 6e 67 20 69 73 20 76 61 6c 69 64 20 75 6e 74  ing is valid unt
2a460 69 6c 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  il the [prepared
2a470 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 73 20 64   statement] is d
2a480 65 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73 69 6e  estroyed.** usin
2a490 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  g [sqlite3_final
2a4a0 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20  ize()] or until 
2a4b0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
2a4c0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a   automatically.*
2a4d0 2a 20 72 65 70 72 65 70 61 72 65 64 20 62 79 20  * reprepared by 
2a4e0 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20 74  the first call t
2a4f0 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  o [sqlite3_step(
2a500 29 5d 20 66 6f 72 20 61 20 70 61 72 74 69 63 75  )] for a particu
2a510 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e  lar run.** or un
2a520 74 69 6c 20 74 68 65 20 73 61 6d 65 20 69 6e 66  til the same inf
2a530 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72 65 71 75  ormation is requ
2a540 65 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69  ested.** again i
2a550 6e 20 61 20 64 69 66 66 65 72 65 6e 74 20 65 6e  n a different en
2a560 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54  coding..**.** ^T
2a570 68 65 20 6e 61 6d 65 73 20 72 65 74 75 72 6e 65  he names returne
2a580 64 20 61 72 65 20 74 68 65 20 6f 72 69 67 69 6e  d are the origin
2a590 61 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e 61  al un-aliased na
2a5a0 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64 61  mes of the.** da
2a5b0 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61  tabase, table, a
2a5c0 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a  nd column..**.**
2a5d0 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75   ^The first argu
2a5e0 6d 65 6e 74 20 74 6f 20 74 68 65 73 65 20 69 6e  ment to these in
2a5f0 74 65 72 66 61 63 65 73 20 69 73 20 61 20 5b 70  terfaces is a [p
2a600 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2a610 74 5d 2e 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75  t]..** ^These fu
2a620 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 69  nctions return i
2a630 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74  nformation about
2a640 20 74 68 65 20 4e 74 68 20 72 65 73 75 6c 74 20   the Nth result 
2a650 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20  column returned 
2a660 62 79 0a 2a 2a 20 74 68 65 20 73 74 61 74 65 6d  by.** the statem
2a670 65 6e 74 2c 20 77 68 65 72 65 20 4e 20 69 73 20  ent, where N is 
2a680 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e 63 74  the second funct
2a690 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  ion argument..**
2a6a0 20 5e 54 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20   ^The left-most 
2a6b0 63 6f 6c 75 6d 6e 20 69 73 20 63 6f 6c 75 6d 6e  column is column
2a6c0 20 30 20 66 6f 72 20 74 68 65 73 65 20 72 6f 75   0 for these rou
2a6d0 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  tines..**.** ^If
2a6e0 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
2a6f0 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 20  returned by the 
2a700 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 6e 20  statement is an 
2a710 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a  expression or.**
2a720 20 73 75 62 71 75 65 72 79 20 61 6e 64 20 69 73   subquery and is
2a730 20 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20 76 61   not a column va
2a740 6c 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20 6f 66  lue, then all of
2a750 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   these functions
2a760 20 72 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e   return.** NULL.
2a770 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65    ^These routine
2a780 20 6d 69 67 68 74 20 61 6c 73 6f 20 72 65 74 75   might also retu
2a790 72 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d 65 6d  rn NULL if a mem
2a7a0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65  ory allocation e
2a7b0 72 72 6f 72 0a 2a 2a 20 6f 63 63 75 72 73 2e 20  rror.** occurs. 
2a7c0 20 5e 4f 74 68 65 72 77 69 73 65 2c 20 74 68 65   ^Otherwise, the
2a7d0 79 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d  y return the nam
2a7e0 65 20 6f 66 20 74 68 65 20 61 74 74 61 63 68 65  e of the attache
2a7f0 64 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c  d database, tabl
2a800 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6c 75 6d 6e 20  e,.** or column 
2a810 74 68 61 74 20 71 75 65 72 79 20 72 65 73 75 6c  that query resul
2a820 74 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65 78 74  t column was ext
2a830 72 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a  racted from..**.
2a840 2a 2a 20 5e 41 73 20 77 69 74 68 20 61 6c 6c 20  ** ^As with all 
2a850 6f 74 68 65 72 20 53 51 4c 69 74 65 20 41 50 49  other SQLite API
2a860 73 2c 20 74 68 6f 73 65 20 77 68 6f 73 65 20 6e  s, those whose n
2a870 61 6d 65 73 20 65 6e 64 20 77 69 74 68 20 22 31  ames end with "1
2a880 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55 54 46  6" return.** UTF
2a890 2d 31 36 20 65 6e 63 6f 64 65 64 20 73 74 72 69  -16 encoded stri
2a8a0 6e 67 73 20 61 6e 64 20 74 68 65 20 6f 74 68 65  ngs and the othe
2a8b0 72 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75  r functions retu
2a8c0 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20  rn UTF-8..**.** 
2a8d0 5e 54 68 65 73 65 20 41 50 49 73 20 61 72 65 20  ^These APIs are 
2a8e0 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69  only available i
2a8f0 66 20 74 68 65 20 6c 69 62 72 61 72 79 20 77 61  f the library wa
2a900 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
2a910 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45  the.** [SQLITE_E
2a920 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54  NABLE_COLUMN_MET
2a930 41 44 41 54 41 5d 20 43 2d 70 72 65 70 72 6f 63  ADATA] C-preproc
2a940 65 73 73 6f 72 20 73 79 6d 62 6f 6c 2e 0a 2a 2a  essor symbol..**
2a950 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f  .** If two or mo
2a960 72 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20  re threads call 
2a970 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74  one or more of t
2a980 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 67  hese routines ag
2a990 61 69 6e 73 74 20 74 68 65 20 73 61 6d 65 0a 2a  ainst the same.*
2a9a0 2a 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  * prepared state
2a9b0 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 20  ment and column 
2a9c0 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
2a9d0 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74   then the result
2a9e0 73 20 61 72 65 0a 2a 2a 20 75 6e 64 65 66 69 6e  s are.** undefin
2a9f0 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f  ed..**.** If two
2aa00 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73   or more threads
2aa10 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72   call one or mor
2aa20 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  e.** [sqlite3_co
2aa30 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61  lumn_database_na
2aa40 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61  me | column meta
2aa50 64 61 74 61 20 69 6e 74 65 72 66 61 63 65 73 5d  data interfaces]
2aa60 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65  .** for the same
2aa70 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2aa80 6d 65 6e 74 5d 20 61 6e 64 20 72 65 73 75 6c 74  ment] and result
2aa90 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20 74 68   column.** at th
2aaa0 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e  e same time then
2aab0 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
2aac0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 53   undefined..*/.S
2aad0 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
2aae0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
2aaf0 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61  lumn_database_na
2ab00 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
2ab10 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50  ,int);.SQLITE_AP
2ab20 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  I const void *sq
2ab30 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74  lite3_column_dat
2ab40 61 62 61 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c  abase_name16(sql
2ab50 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
2ab60 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
2ab70 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
2ab80 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d  column_table_nam
2ab90 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
2aba0 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  int);.SQLITE_API
2abb0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c   const void *sql
2abc0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c  ite3_column_tabl
2abd0 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33  e_name16(sqlite3
2abe0 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c  _stmt*,int);.SQL
2abf0 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68  ITE_API const ch
2ac00 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
2ac10 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73  mn_origin_name(s
2ac20 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
2ac30 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  );.SQLITE_API co
2ac40 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
2ac50 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f  3_column_origin_
2ac60 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73  name16(sqlite3_s
2ac70 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  tmt*,int);../*.*
2ac80 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c  * CAPI3REF: Decl
2ac90 61 72 65 64 20 44 61 74 61 74 79 70 65 20 4f 66  ared Datatype Of
2aca0 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a   A Query Result.
2acb0 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 72 73  **.** ^(The firs
2acc0 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  t parameter is a
2acd0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2ace0 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 69  ment]..** If thi
2acf0 73 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  s statement is a
2ad00 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
2ad10 65 6e 74 20 61 6e 64 20 74 68 65 20 4e 74 68 20  ent and the Nth 
2ad20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a  column of the.**
2ad30 20 72 65 74 75 72 6e 65 64 20 72 65 73 75 6c 74   returned result
2ad40 20 73 65 74 20 6f 66 20 74 68 61 74 20 5b 53 45   set of that [SE
2ad50 4c 45 43 54 5d 20 69 73 20 61 20 74 61 62 6c 65  LECT] is a table
2ad60 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a   column (not an.
2ad70 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72  ** expression or
2ad80 20 73 75 62 71 75 65 72 79 29 20 74 68 65 6e 20   subquery) then 
2ad90 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70  the declared typ
2ada0 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 0a 2a  e of the table.*
2adb0 2a 20 63 6f 6c 75 6d 6e 20 69 73 20 72 65 74 75  * column is retu
2adc0 72 6e 65 64 2e 29 5e 20 20 5e 49 66 20 74 68 65  rned.)^  ^If the
2add0 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74   Nth column of t
2ade0 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 69 73  he result set is
2adf0 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f   an.** expressio
2ae00 6e 20 6f 72 20 73 75 62 71 75 65 72 79 2c 20 74  n or subquery, t
2ae10 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  hen a NULL point
2ae20 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  er is returned..
2ae30 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64  ** ^The returned
2ae40 20 73 74 72 69 6e 67 20 69 73 20 61 6c 77 61 79   string is alway
2ae50 73 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2e  s UTF-8 encoded.
2ae60 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61  .**.** ^(For exa
2ae70 6d 70 6c 65 2c 20 67 69 76 65 6e 20 74 68 65 20  mple, given the 
2ae80 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 3a  database schema:
2ae90 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20 54 41  .**.** CREATE TA
2aea0 42 4c 45 20 74 31 28 63 31 20 56 41 52 49 41 4e  BLE t1(c1 VARIAN
2aeb0 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68  T);.**.** and th
2aec0 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 74  e following stat
2aed0 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70  ement to be comp
2aee0 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45  iled:.**.** SELE
2aef0 43 54 20 63 31 20 2b 20 31 2c 20 63 31 20 46 52  CT c1 + 1, c1 FR
2af00 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69  OM t1;.**.** thi
2af10 73 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c 64 20  s routine would 
2af20 72 65 74 75 72 6e 20 74 68 65 20 73 74 72 69 6e  return the strin
2af30 67 20 22 56 41 52 49 41 4e 54 22 20 66 6f 72 20  g "VARIANT" for 
2af40 74 68 65 20 73 65 63 6f 6e 64 20 72 65 73 75 6c  the second resul
2af50 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d  t.** column (i==
2af60 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c 20 70  1), and a NULL p
2af70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65 20 66  ointer for the f
2af80 69 72 73 74 20 72 65 73 75 6c 74 20 63 6f 6c 75  irst result colu
2af90 6d 6e 20 28 69 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a  mn (i==0).)^.**.
2afa0 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20  ** ^SQLite uses 
2afb0 64 79 6e 61 6d 69 63 20 72 75 6e 2d 74 69 6d 65  dynamic run-time
2afc0 20 74 79 70 69 6e 67 2e 20 20 5e 53 6f 20 6a 75   typing.  ^So ju
2afd0 73 74 20 62 65 63 61 75 73 65 20 61 20 63 6f 6c  st because a col
2afe0 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63 6c 61 72  umn.** is declar
2aff0 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20 61 20  ed to contain a 
2b000 70 61 72 74 69 63 75 6c 61 72 20 74 79 70 65 20  particular type 
2b010 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e 20 74 68  does not mean th
2b020 61 74 20 74 68 65 0a 2a 2a 20 64 61 74 61 20 73  at the.** data s
2b030 74 6f 72 65 64 20 69 6e 20 74 68 61 74 20 63 6f  tored in that co
2b040 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68 65 20 64  lumn is of the d
2b050 65 63 6c 61 72 65 64 20 74 79 70 65 2e 20 20 53  eclared type.  S
2b060 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73 74 72 6f  QLite is.** stro
2b070 6e 67 6c 79 20 74 79 70 65 64 2c 20 62 75 74 20  ngly typed, but 
2b080 74 68 65 20 74 79 70 69 6e 67 20 69 73 20 64 79  the typing is dy
2b090 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61 74 69 63  namic not static
2b0a0 2e 20 20 5e 54 79 70 65 0a 2a 2a 20 69 73 20 61  .  ^Type.** is a
2b0b0 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 69  ssociated with i
2b0c0 6e 64 69 76 69 64 75 61 6c 20 76 61 6c 75 65 73  ndividual values
2b0d0 2c 20 6e 6f 74 20 77 69 74 68 20 74 68 65 20 63  , not with the c
2b0e0 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 75 73 65  ontainers.** use
2b0f0 64 20 74 6f 20 68 6f 6c 64 20 74 68 6f 73 65 20  d to hold those 
2b100 76 61 6c 75 65 73 2e 0a 2a 2f 0a 53 51 4c 49 54  values..*/.SQLIT
2b110 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72  E_API const char
2b120 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
2b130 5f 64 65 63 6c 74 79 70 65 28 73 71 6c 69 74 65  _decltype(sqlite
2b140 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51  3_stmt*,int);.SQ
2b150 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76  LITE_API const v
2b160 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
2b170 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36 28 73  umn_decltype16(s
2b180 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
2b190 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2b1a0 45 46 3a 20 45 76 61 6c 75 61 74 65 20 41 6e 20  EF: Evaluate An 
2b1b0 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a  SQL Statement.**
2b1c0 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b 70 72 65  .** After a [pre
2b1d0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2b1e0 20 68 61 73 20 62 65 65 6e 20 70 72 65 70 61 72   has been prepar
2b1f0 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 0a  ed using either.
2b200 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
2b210 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71  are_v2()] or [sq
2b220 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
2b230 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20  v2()] or one of 
2b240 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e  the legacy.** in
2b250 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65  terfaces [sqlite
2b260 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20  3_prepare()] or 
2b270 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2b280 31 36 28 29 5d 2c 20 74 68 69 73 20 66 75 6e 63  16()], this func
2b290 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62 65 20  tion.** must be 
2b2a0 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f  called one or mo
2b2b0 72 65 20 74 69 6d 65 73 20 74 6f 20 65 76 61 6c  re times to eval
2b2c0 75 61 74 65 20 74 68 65 20 73 74 61 74 65 6d 65  uate the stateme
2b2d0 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65  nt..**.** The de
2b2e0 74 61 69 6c 73 20 6f 66 20 74 68 65 20 62 65 68  tails of the beh
2b2f0 61 76 69 6f 72 20 6f 66 20 74 68 65 20 73 71 6c  avior of the sql
2b300 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 74 65  ite3_step() inte
2b310 72 66 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20  rface depend.** 
2b320 6f 6e 20 77 68 65 74 68 65 72 20 74 68 65 20 73  on whether the s
2b330 74 61 74 65 6d 65 6e 74 20 77 61 73 20 70 72 65  tatement was pre
2b340 70 61 72 65 64 20 75 73 69 6e 67 20 74 68 65 20  pared using the 
2b350 6e 65 77 65 72 20 22 76 32 22 20 69 6e 74 65 72  newer "v2" inter
2b360 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  face.** [sqlite3
2b370 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61  _prepare_v2()] a
2b380 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  nd [sqlite3_prep
2b390 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 74  are16_v2()] or t
2b3a0 68 65 20 6f 6c 64 65 72 20 6c 65 67 61 63 79 0a  he older legacy.
2b3b0 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 5b 73 71  ** interface [sq
2b3c0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
2b3d0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72   and [sqlite3_pr
2b3e0 65 70 61 72 65 31 36 28 29 5d 2e 20 20 54 68 65  epare16()].  The
2b3f0 20 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20 6e   use of the.** n
2b400 65 77 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  ew "v2" interfac
2b410 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  e is recommended
2b420 20 66 6f 72 20 6e 65 77 20 61 70 70 6c 69 63 61   for new applica
2b430 74 69 6f 6e 73 20 62 75 74 20 74 68 65 20 6c 65  tions but the le
2b440 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63  gacy.** interfac
2b450 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 20  e will continue 
2b460 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e  to be supported.
2b470 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 6c  .**.** ^In the l
2b480 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c  egacy interface,
2b490 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
2b4a0 65 20 77 69 6c 6c 20 62 65 20 65 69 74 68 65 72  e will be either
2b4b0 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 0a   [SQLITE_BUSY],.
2b4c0 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  ** [SQLITE_DONE]
2b4d0 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20  , [SQLITE_ROW], 
2b4e0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20  [SQLITE_ERROR], 
2b4f0 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  or [SQLITE_MISUS
2b500 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65  E]..** ^With the
2b510 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c   "v2" interface,
2b520 20 61 6e 79 20 6f 66 20 74 68 65 20 6f 74 68 65   any of the othe
2b530 72 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 5d  r [result codes]
2b540 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64   or.** [extended
2b550 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6d   result codes] m
2b560 69 67 68 74 20 62 65 20 72 65 74 75 72 6e 65 64  ight be returned
2b570 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20   as well..**.** 
2b580 5e 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6d  ^[SQLITE_BUSY] m
2b590 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 64 61  eans that the da
2b5a0 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20 77 61  tabase engine wa
2b5b0 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 63 71 75  s unable to acqu
2b5c0 69 72 65 20 74 68 65 0a 2a 2a 20 64 61 74 61 62  ire the.** datab
2b5d0 61 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65 65  ase locks it nee
2b5e0 64 73 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f 62  ds to do its job
2b5f0 2e 20 20 5e 49 66 20 74 68 65 20 73 74 61 74 65  .  ^If the state
2b600 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f 4d 4d 49  ment is a [COMMI
2b610 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73 20  T].** or occurs 
2b620 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 20 65 78  outside of an ex
2b630 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69  plicit transacti
2b640 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63 61 6e  on, then you can
2b650 20 72 65 74 72 79 20 74 68 65 0a 2a 2a 20 73 74   retry the.** st
2b660 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 74 68 65  atement.  If the
2b670 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f   statement is no
2b680 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64  t a [COMMIT] and
2b690 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61   occurs within a
2b6a0 6e 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20 74 72  n.** explicit tr
2b6b0 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e 20 79  ansaction then y
2b6c0 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 61  ou should rollba
2b6d0 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74 69  ck the transacti
2b6e0 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e  on before.** con
2b6f0 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e  tinuing..**.** ^
2b700 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65  [SQLITE_DONE] me
2b710 61 6e 73 20 74 68 61 74 20 74 68 65 20 73 74 61  ans that the sta
2b720 74 65 6d 65 6e 74 20 68 61 73 20 66 69 6e 69 73  tement has finis
2b730 68 65 64 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a  hed executing.**
2b740 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20   successfully.  
2b750 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73  sqlite3_step() s
2b760 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c  hould not be cal
2b770 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 69  led again on thi
2b780 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63  s virtual.** mac
2b790 68 69 6e 65 20 77 69 74 68 6f 75 74 20 66 69 72  hine without fir
2b7a0 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  st calling [sqli
2b7b0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 6f 20  te3_reset()] to 
2b7c0 72 65 73 65 74 20 74 68 65 20 76 69 72 74 75 61  reset the virtua
2b7d0 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61 63  l.** machine bac
2b7e0 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c  k to its initial
2b7f0 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49   state..**.** ^I
2b800 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  f the SQL statem
2b810 65 6e 74 20 62 65 69 6e 67 20 65 78 65 63 75 74  ent being execut
2b820 65 64 20 72 65 74 75 72 6e 73 20 61 6e 79 20 64  ed returns any d
2b830 61 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54  ata, then [SQLIT
2b840 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 74  E_ROW].** is ret
2b850 75 72 6e 65 64 20 65 61 63 68 20 74 69 6d 65 20  urned each time 
2b860 61 20 6e 65 77 20 72 6f 77 20 6f 66 20 64 61 74  a new row of dat
2b870 61 20 69 73 20 72 65 61 64 79 20 66 6f 72 20 70  a is ready for p
2b880 72 6f 63 65 73 73 69 6e 67 20 62 79 20 74 68 65  rocessing by the
2b890 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68 65 20  .** caller. The 
2b8a0 76 61 6c 75 65 73 20 6d 61 79 20 62 65 20 61 63  values may be ac
2b8b0 63 65 73 73 65 64 20 75 73 69 6e 67 20 74 68 65  cessed using the
2b8c0 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20   [column access 
2b8d0 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73  functions]..** s
2b8e0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 73  qlite3_step() is
2b8f0 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f   called again to
2b900 20 72 65 74 72 69 65 76 65 20 74 68 65 20 6e 65   retrieve the ne
2b910 78 74 20 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a  xt row of data..
2b920 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 45  **.** ^[SQLITE_E
2b930 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61 74  RROR] means that
2b940 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f   a run-time erro
2b950 72 20 28 73 75 63 68 20 61 73 20 61 20 63 6f 6e  r (such as a con
2b960 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61  straint.** viola
2b970 74 69 6f 6e 29 20 68 61 73 20 6f 63 63 75 72 72  tion) has occurr
2b980 65 64 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65  ed.  sqlite3_ste
2b990 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62  p() should not b
2b9a0 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f  e called again o
2b9b0 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72  n.** the VM. Mor
2b9c0 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61  e information ma
2b9d0 79 20 62 65 20 66 6f 75 6e 64 20 62 79 20 63 61  y be found by ca
2b9e0 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65  lling [sqlite3_e
2b9f0 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e 57 69  rrmsg()]..** ^Wi
2ba00 74 68 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e  th the legacy in
2ba10 74 65 72 66 61 63 65 2c 20 61 20 6d 6f 72 65 20  terface, a more 
2ba20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63  specific error c
2ba30 6f 64 65 20 28 66 6f 72 20 65 78 61 6d 70 6c 65  ode (for example
2ba40 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54  ,.** [SQLITE_INT
2ba50 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45  ERRUPT], [SQLITE
2ba60 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54  _SCHEMA], [SQLIT
2ba70 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20  E_CORRUPT], and 
2ba80 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e  so forth).** can
2ba90 20 62 65 20 6f 62 74 61 69 6e 65 64 20 62 79 20   be obtained by 
2baa0 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
2bab0 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20 74 68 65  _reset()] on the
2bac0 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
2bad0 61 74 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e 20 74  atement].  ^In t
2bae0 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
2baf0 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73  e,.** the more s
2bb00 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f  pecific error co
2bb10 64 65 20 69 73 20 72 65 74 75 72 6e 65 64 20 64  de is returned d
2bb20 69 72 65 63 74 6c 79 20 62 79 20 73 71 6c 69 74  irectly by sqlit
2bb30 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a  e3_step()..**.**
2bb40 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
2bb50 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
2bb60 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 61 73  this routine was
2bb70 20 63 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70   called inapprop
2bb80 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68  riately..** Perh
2bb90 61 70 73 20 69 74 20 77 61 73 20 63 61 6c 6c 65  aps it was calle
2bba0 64 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64  d on a [prepared
2bbb0 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
2bbc0 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20   has.** already 
2bbd0 62 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69  been [sqlite3_fi
2bbe0 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a  nalize | finaliz
2bbf0 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68  ed] or on one th
2bc00 61 74 20 68 61 64 0a 2a 2a 20 70 72 65 76 69 6f  at had.** previo
2bc10 75 73 6c 79 20 72 65 74 75 72 6e 65 64 20 5b 53  usly returned [S
2bc20 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20  QLITE_ERROR] or 
2bc30 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20  [SQLITE_DONE].  
2bc40 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62  Or it could.** b
2bc50 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74 20  e the case that 
2bc60 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
2bc70 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
2bc80 62 65 69 6e 67 20 75 73 65 64 20 62 79 20 74 77  being used by tw
2bc90 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72  o or.** more thr
2bca0 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65  eads at the same
2bcb0 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e   moment in time.
2bcc0 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20 76  .**.** For all v
2bcd0 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
2bce0 65 20 75 70 20 74 6f 20 61 6e 64 20 69 6e 63 6c  e up to and incl
2bcf0 75 64 69 6e 67 20 33 2e 36 2e 32 33 2e 31 2c 20  uding 3.6.23.1, 
2bd00 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71  a call to.** [sq
2bd10 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77  lite3_reset()] w
2bd20 61 73 20 72 65 71 75 69 72 65 64 20 61 66 74 65  as required afte
2bd30 72 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  r sqlite3_step()
2bd40 20 72 65 74 75 72 6e 65 64 20 61 6e 79 74 68 69   returned anythi
2bd50 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 74 68 61 6e  ng.** other than
2bd60 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 62 65   [SQLITE_ROW] be
2bd70 66 6f 72 65 20 61 6e 79 20 73 75 62 73 65 71 75  fore any subsequ
2bd80 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f  ent invocation o
2bd90 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65  f.** sqlite3_ste
2bda0 70 28 29 2e 20 20 46 61 69 6c 75 72 65 20 74 6f  p().  Failure to
2bdb0 20 72 65 73 65 74 20 74 68 65 20 70 72 65 70 61   reset the prepa
2bdc0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 75 73  red statement us
2bdd0 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ing .** [sqlite3
2bde0 5f 72 65 73 65 74 28 29 5d 20 77 6f 75 6c 64 20  _reset()] would 
2bdf0 72 65 73 75 6c 74 20 69 6e 20 61 6e 20 5b 53 51  result in an [SQ
2be00 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 72 65 74  LITE_MISUSE] ret
2be10 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69  urn from.** sqli
2be20 74 65 33 5f 73 74 65 70 28 29 2e 20 20 42 75 74  te3_step().  But
2be30 20 61 66 74 65 72 20 76 65 72 73 69 6f 6e 20 33   after version 3
2be40 2e 36 2e 32 33 2e 31 2c 20 73 71 6c 69 74 65 33  .6.23.1, sqlite3
2be50 5f 73 74 65 70 28 29 20 62 65 67 61 6e 0a 2a 2a  _step() began.**
2be60 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
2be70 33 5f 72 65 73 65 74 28 29 5d 20 61 75 74 6f 6d  3_reset()] autom
2be80 61 74 69 63 61 6c 6c 79 20 69 6e 20 74 68 69 73  atically in this
2be90 20 63 69 72 63 75 6d 73 74 61 6e 63 65 20 72 61   circumstance ra
2bea0 74 68 65 72 0a 2a 2a 20 74 68 61 6e 20 72 65 74  ther.** than ret
2beb0 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 4d  urning [SQLITE_M
2bec0 49 53 55 53 45 5d 2e 20 20 54 68 69 73 20 69 73  ISUSE].  This is
2bed0 20 6e 6f 74 20 63 6f 6e 73 69 64 65 72 65 64 20   not considered 
2bee0 61 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 0a  a compatibility.
2bef0 2a 2a 20 62 72 65 61 6b 20 62 65 63 61 75 73 65  ** break because
2bf00 20 61 6e 79 20 61 70 70 6c 69 63 61 74 69 6f 6e   any application
2bf10 20 74 68 61 74 20 65 76 65 72 20 72 65 63 65 69   that ever recei
2bf20 76 65 73 20 61 6e 20 53 51 4c 49 54 45 5f 4d 49  ves an SQLITE_MI
2bf30 53 55 53 45 20 65 72 72 6f 72 0a 2a 2a 20 69 73  SUSE error.** is
2bf40 20 62 72 6f 6b 65 6e 20 62 79 20 64 65 66 69 6e   broken by defin
2bf50 69 74 69 6f 6e 2e 20 20 54 68 65 20 5b 53 51 4c  ition.  The [SQL
2bf60 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 52 45 53  ITE_OMIT_AUTORES
2bf70 45 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  ET] compile-time
2bf80 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61 6e 20 62   option.** can b
2bf90 65 20 75 73 65 64 20 74 6f 20 72 65 73 74 6f 72  e used to restor
2bfa0 65 20 74 68 65 20 6c 65 67 61 63 79 20 62 65 68  e the legacy beh
2bfb0 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e  avior..**.** <b>
2bfc0 47 6f 6f 66 79 20 49 6e 74 65 72 66 61 63 65 20  Goofy Interface 
2bfd0 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 68  Alert:</b> In th
2bfe0 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61  e legacy interfa
2bff0 63 65 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ce, the sqlite3_
2c000 73 74 65 70 28 29 0a 2a 2a 20 41 50 49 20 61 6c  step().** API al
2c010 77 61 79 73 20 72 65 74 75 72 6e 73 20 61 20 67  ways returns a g
2c020 65 6e 65 72 69 63 20 65 72 72 6f 72 20 63 6f 64  eneric error cod
2c030 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  e, [SQLITE_ERROR
2c040 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79  ], following any
2c050 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68 65 72 20  .** error other 
2c060 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53  than [SQLITE_BUS
2c070 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d  Y] and [SQLITE_M
2c080 49 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73  ISUSE].  You mus
2c090 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74  t call.** [sqlit
2c0a0 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b  e3_reset()] or [
2c0b0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2c0c0 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ()] in order to 
2c0d0 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65 0a  find one of the.
2c0e0 2a 2a 20 73 70 65 63 69 66 69 63 20 5b 65 72 72  ** specific [err
2c0f0 6f 72 20 63 6f 64 65 73 5d 20 74 68 61 74 20 62  or codes] that b
2c100 65 74 74 65 72 20 64 65 73 63 72 69 62 65 73 20  etter describes 
2c110 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65  the error..** We
2c120 20 61 64 6d 69 74 20 74 68 61 74 20 74 68 69 73   admit that this
2c130 20 69 73 20 61 20 67 6f 6f 66 79 20 64 65 73 69   is a goofy desi
2c140 67 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c 65 6d  gn.  The problem
2c150 20 68 61 73 20 62 65 65 6e 20 66 69 78 65 64 0a   has been fixed.
2c160 2a 2a 20 77 69 74 68 20 74 68 65 20 22 76 32 22  ** with the "v2"
2c170 20 69 6e 74 65 72 66 61 63 65 2e 20 20 49 66 20   interface.  If 
2c180 79 6f 75 20 70 72 65 70 61 72 65 20 61 6c 6c 20  you prepare all 
2c190 6f 66 20 79 6f 75 72 20 53 51 4c 20 73 74 61 74  of your SQL stat
2c1a0 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20  ements.** using 
2c1b0 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f  either [sqlite3_
2c1c0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
2c1d0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2c1e0 65 31 36 5f 76 32 28 29 5d 20 69 6e 73 74 65 61  e16_v2()] instea
2c1f0 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67 61  d.** of the lega
2c200 63 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  cy [sqlite3_prep
2c210 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  are()] and [sqli
2c220 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
2c230 20 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a 2a 20   interfaces,.** 
2c240 74 68 65 6e 20 74 68 65 20 6d 6f 72 65 20 73 70  then the more sp
2c250 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f  ecific [error co
2c260 64 65 73 5d 20 61 72 65 20 72 65 74 75 72 6e 65  des] are returne
2c270 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79  d directly.** by
2c280 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e   sqlite3_step().
2c290 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65    The use of the
2c2a0 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 20   "v2" interface 
2c2b0 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a  is recommended..
2c2c0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
2c2d0 74 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 73  t sqlite3_step(s
2c2e0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a  qlite3_stmt*);..
2c2f0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2c300 4e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  Number of column
2c310 73 20 69 6e 20 61 20 72 65 73 75 6c 74 20 73 65  s in a result se
2c320 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  t.**.** ^The sql
2c330 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
2c340 50 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  P) interface ret
2c350 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
2c360 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68  of columns in th
2c370 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 72 6f 77  e.** current row
2c380 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
2c390 65 74 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20  et of [prepared 
2c3a0 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a  statement] P..**
2c3b0 20 5e 49 66 20 70 72 65 70 61 72 65 64 20 73 74   ^If prepared st
2c3c0 61 74 65 6d 65 6e 74 20 50 20 64 6f 65 73 20 6e  atement P does n
2c3d0 6f 74 20 68 61 76 65 20 72 65 73 75 6c 74 73 20  ot have results 
2c3e0 72 65 61 64 79 20 74 6f 20 72 65 74 75 72 6e 0a  ready to return.
2c3f0 2a 2a 20 28 76 69 61 20 63 61 6c 6c 73 20 74 6f  ** (via calls to
2c400 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   the [sqlite3_co
2c410 6c 75 6d 6e 5f 69 6e 74 20 7c 20 73 71 6c 69 74  lumn_int | sqlit
2c420 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 28 29 5d 20 6f  e3_column_*()] o
2c430 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 29  f.** interfaces)
2c440 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 64 61   then sqlite3_da
2c450 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 65 74 75  ta_count(P) retu
2c460 72 6e 73 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 73  rns 0..** ^The s
2c470 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
2c480 74 28 50 29 20 72 6f 75 74 69 6e 65 20 61 6c 73  t(P) routine als
2c490 6f 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 50  o returns 0 if P
2c4a0 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
2c4b0 65 72 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  er..**.** See al
2c4c0 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  so: [sqlite3_col
2c4d0 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a  umn_count()].*/.
2c4e0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
2c4f0 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
2c500 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  t(sqlite3_stmt *
2c510 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
2c520 41 50 49 33 52 45 46 3a 20 46 75 6e 64 61 6d 65  API3REF: Fundame
2c530 6e 74 61 6c 20 44 61 74 61 74 79 70 65 73 0a 2a  ntal Datatypes.*
2c540 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49  * KEYWORDS: SQLI
2c550 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20 5e 28  TE_TEXT.**.** ^(
2c560 45 76 65 72 79 20 76 61 6c 75 65 20 69 6e 20 53  Every value in S
2c570 51 4c 69 74 65 20 68 61 73 20 6f 6e 65 20 6f 66  QLite has one of
2c580 20 66 69 76 65 20 66 75 6e 64 61 6d 65 6e 74 61   five fundamenta
2c590 6c 20 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a  l datatypes:.**.
2c5a0 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
2c5b0 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e  64-bit signed in
2c5c0 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34  teger.** <li> 64
2c5d0 2d 62 69 74 20 49 45 45 45 20 66 6c 6f 61 74 69  -bit IEEE floati
2c5e0 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a  ng point number.
2c5f0 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a  ** <li> string.*
2c600 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c  * <li> BLOB.** <
2c610 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c  li> NULL.** </ul
2c620 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  >)^.**.** These 
2c630 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 63 6f  constants are co
2c640 64 65 73 20 66 6f 72 20 65 61 63 68 20 6f 66 20  des for each of 
2c650 74 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a  those types..**.
2c660 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65  ** Note that the
2c670 20 53 51 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e   SQLITE_TEXT con
2c680 73 74 61 6e 74 20 77 61 73 20 61 6c 73 6f 20 75  stant was also u
2c690 73 65 64 20 69 6e 20 53 51 4c 69 74 65 20 76 65  sed in SQLite ve
2c6a0 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61  rsion 2.** for a
2c6b0 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66 66   completely diff
2c6c0 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20  erent meaning.  
2c6d0 53 6f 66 74 77 61 72 65 20 74 68 61 74 20 6c 69  Software that li
2c6e0 6e 6b 73 20 61 67 61 69 6e 73 74 20 62 6f 74 68  nks against both
2c6f0 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69  .** SQLite versi
2c700 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69 74 65 20  on 2 and SQLite 
2c710 76 65 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64  version 3 should
2c720 20 75 73 65 20 53 51 4c 49 54 45 33 5f 54 45 58   use SQLITE3_TEX
2c730 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45  T, not.** SQLITE
2c740 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e  _TEXT..*/.#defin
2c750 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52  e SQLITE_INTEGER
2c760 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
2c770 54 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23 64  TE_FLOAT    2.#d
2c780 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f  efine SQLITE_BLO
2c790 42 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20  B     4.#define 
2c7a0 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20  SQLITE_NULL     
2c7b0 35 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f  5.#ifdef SQLITE_
2c7c0 54 45 58 54 0a 23 20 75 6e 64 65 66 20 53 51 4c  TEXT.# undef SQL
2c7d0 49 54 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23  ITE_TEXT.#else.#
2c7e0 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54   define SQLITE_T
2c7f0 45 58 54 20 20 20 20 20 33 0a 23 65 6e 64 69 66  EXT     3.#endif
2c800 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33  .#define SQLITE3
2c810 5f 54 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a  _TEXT     3../*.
2c820 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73  ** CAPI3REF: Res
2c830 75 6c 74 20 56 61 6c 75 65 73 20 46 72 6f 6d 20  ult Values From 
2c840 41 20 51 75 65 72 79 0a 2a 2a 20 4b 45 59 57 4f  A Query.** KEYWO
2c850 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63 63  RDS: {column acc
2c860 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a  ess functions}.*
2c870 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
2c880 6e 65 73 20 66 6f 72 6d 20 74 68 65 20 22 72 65  nes form the "re
2c890 73 75 6c 74 20 73 65 74 22 20 69 6e 74 65 72 66  sult set" interf
2c8a0 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  ace..**.** ^Thes
2c8b0 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  e routines retur
2c8c0 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62  n information ab
2c8d0 6f 75 74 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c  out a single col
2c8e0 75 6d 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65  umn of the curre
2c8f0 6e 74 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77  nt.** result row
2c900 20 6f 66 20 61 20 71 75 65 72 79 2e 20 20 5e 49   of a query.  ^I
2c910 6e 20 65 76 65 72 79 20 63 61 73 65 20 74 68 65  n every case the
2c920 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
2c930 69 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  is a pointer.** 
2c940 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  to the [prepared
2c950 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
2c960 20 69 73 20 62 65 69 6e 67 20 65 76 61 6c 75 61   is being evalua
2c970 74 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65  ted (the [sqlite
2c980 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74  3_stmt*].** that
2c990 20 77 61 73 20 72 65 74 75 72 6e 65 64 20 66 72   was returned fr
2c9a0 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  om [sqlite3_prep
2c9b0 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65  are_v2()] or one
2c9c0 20 6f 66 20 69 74 73 20 76 61 72 69 61 6e 74 73   of its variants
2c9d0 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 73 65 63  ).** and the sec
2c9e0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ond argument is 
2c9f0 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65  the index of the
2ca00 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69 63   column for whic
2ca10 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a  h information.**
2ca20 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72   should be retur
2ca30 6e 65 64 2e 20 5e 54 68 65 20 6c 65 66 74 6d 6f  ned. ^The leftmo
2ca40 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65  st column of the
2ca50 20 72 65 73 75 6c 74 20 73 65 74 20 68 61 73 20   result set has 
2ca60 74 68 65 20 69 6e 64 65 78 20 30 2e 0a 2a 2a 20  the index 0..** 
2ca70 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63  ^The number of c
2ca80 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65  olumns in the re
2ca90 73 75 6c 74 20 63 61 6e 20 62 65 20 64 65 74 65  sult can be dete
2caa0 72 6d 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20  rmined using.** 
2cab0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
2cac0 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  count()]..**.** 
2cad0 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  If the SQL state
2cae0 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 75  ment does not cu
2caf0 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f  rrently point to
2cb00 20 61 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72   a valid row, or
2cb10 20 69 66 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d   if the.** colum
2cb20 6e 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f  n index is out o
2cb30 66 20 72 61 6e 67 65 2c 20 74 68 65 20 72 65 73  f range, the res
2cb40 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ult is undefined
2cb50 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  ..** These routi
2cb60 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20  nes may only be 
2cb70 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20  called when the 
2cb80 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c  most recent call
2cb90 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
2cba0 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75  step()] has retu
2cbb0 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57  rned [SQLITE_ROW
2cbc0 5d 20 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a  ] and neither.**
2cbd0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2cbe0 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f  )] nor [sqlite3_
2cbf0 66 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61 76 65  finalize()] have
2cc00 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 73 75 62   been called sub
2cc10 73 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66  sequently..** If
2cc20 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f   any of these ro
2cc30 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65  utines are calle
2cc40 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33  d after [sqlite3
2cc50 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20  _reset()] or.** 
2cc60 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
2cc70 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 5b 73  e()] or after [s
2cc80 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68  qlite3_step()] h
2cc90 61 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73  as returned.** s
2cca0 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74  omething other t
2ccb0 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  han [SQLITE_ROW]
2ccc0 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  , the results ar
2ccd0 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20  e undefined..** 
2cce0 49 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  If [sqlite3_step
2ccf0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
2cd00 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c  reset()] or [sql
2cd10 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
2cd20 0a 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64 20 66  .** are called f
2cd30 72 6f 6d 20 61 20 64 69 66 66 65 72 65 6e 74 20  rom a different 
2cd40 74 68 72 65 61 64 20 77 68 69 6c 65 20 61 6e 79  thread while any
2cd50 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
2cd60 65 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e  es.** are pendin
2cd70 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73 75  g, then the resu
2cd80 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65  lts are undefine
2cd90 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  d..**.** ^The sq
2cda0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
2cdb0 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  e() routine retu
2cdc0 72 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  rns the.** [SQLI
2cdd0 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74  TE_INTEGER | dat
2cde0 61 74 79 70 65 20 63 6f 64 65 5d 20 66 6f 72 20  atype code] for 
2cdf0 74 68 65 20 69 6e 69 74 69 61 6c 20 64 61 74 61  the initial data
2ce00 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20   type.** of the 
2ce10 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20  result column.  
2ce20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 76 61  ^The returned va
2ce30 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53  lue is one of [S
2ce40 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a  QLITE_INTEGER],.
2ce50 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54  ** [SQLITE_FLOAT
2ce60 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d  ], [SQLITE_TEXT]
2ce70 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c  , [SQLITE_BLOB],
2ce80 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c   or [SQLITE_NULL
2ce90 5d 2e 20 20 54 68 65 20 76 61 6c 75 65 0a 2a 2a  ].  The value.**
2cea0 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
2ceb0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
2cec0 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69  () is only meani
2ced0 6e 67 66 75 6c 20 69 66 20 6e 6f 20 74 79 70 65  ngful if no type
2cee0 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20  .** conversions 
2cef0 68 61 76 65 20 6f 63 63 75 72 72 65 64 20 61 73  have occurred as
2cf00 20 64 65 73 63 72 69 62 65 64 20 62 65 6c 6f 77   described below
2cf10 2e 20 20 41 66 74 65 72 20 61 20 74 79 70 65 20  .  After a type 
2cf20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74  conversion,.** t
2cf30 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
2cf40 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
2cf50 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 75 6e  umn_type() is un
2cf60 64 65 66 69 6e 65 64 2e 20 20 46 75 74 75 72 65  defined.  Future
2cf70 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  .** versions of 
2cf80 53 51 4c 69 74 65 20 6d 61 79 20 63 68 61 6e 67  SQLite may chang
2cf90 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f  e the behavior o
2cfa0 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  f sqlite3_column
2cfb0 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f  _type().** follo
2cfc0 77 69 6e 67 20 61 20 74 79 70 65 20 63 6f 6e 76  wing a type conv
2cfd0 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49  ersion..**.** ^I
2cfe0 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
2cff0 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20  a BLOB or UTF-8 
2d000 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20  string then the 
2d010 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2d020 79 74 65 73 28 29 0a 2a 2a 20 72 6f 75 74 69 6e  ytes().** routin
2d030 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  e returns the nu
2d040 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
2d050 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74   that BLOB or st
2d060 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ring..** ^If the
2d070 20 72 65 73 75 6c 74 20 69 73 20 61 20 55 54 46   result is a UTF
2d080 2d 31 36 20 73 74 72 69 6e 67 2c 20 74 68 65 6e  -16 string, then
2d090 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2d0a0 62 79 74 65 73 28 29 20 63 6f 6e 76 65 72 74 73  bytes() converts
2d0b0 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74  .** the string t
2d0c0 6f 20 55 54 46 2d 38 20 61 6e 64 20 74 68 65 6e  o UTF-8 and then
2d0d0 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
2d0e0 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a  ber of bytes..**
2d0f0 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
2d100 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c  is a numeric val
2d110 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  ue then sqlite3_
2d120 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 75  column_bytes() u
2d130 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ses.** [sqlite3_
2d140 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63  snprintf()] to c
2d150 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c 75  onvert that valu
2d160 65 20 74 6f 20 61 20 55 54 46 2d 38 20 73 74 72  e to a UTF-8 str
2d170 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a  ing and returns.
2d180 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
2d190 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 73   bytes in that s
2d1a0 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68  tring..** ^If th
2d1b0 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c  e result is NULL
2d1c0 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  , then sqlite3_c
2d1d0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 72 65  olumn_bytes() re
2d1e0 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a  turns zero..**.*
2d1f0 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
2d200 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54   is a BLOB or UT
2d210 46 2d 31 36 20 73 74 72 69 6e 67 20 74 68 65 6e  F-16 string then
2d220 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c   the sqlite3_col
2d230 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 0a 2a 2a  umn_bytes16().**
2d240 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
2d250 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
2d260 79 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f  ytes in that BLO
2d270 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20  B or string..** 
2d280 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
2d290 73 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67  s a UTF-8 string
2d2a0 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  , then sqlite3_c
2d2b0 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20  olumn_bytes16() 
2d2c0 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20  converts.** the 
2d2d0 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 31 36  string to UTF-16
2d2e0 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e   and then return
2d2f0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
2d300 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68  bytes..** ^If th
2d310 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75  e result is a nu
2d320 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e  meric value then
2d330 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2d340 62 79 74 65 73 31 36 28 29 20 75 73 65 73 0a 2a  bytes16() uses.*
2d350 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  * [sqlite3_snpri
2d360 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72  ntf()] to conver
2d370 74 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20  t that value to 
2d380 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20  a UTF-16 string 
2d390 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74  and returns.** t
2d3a0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
2d3b0 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e  es in that strin
2d3c0 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  g..** ^If the re
2d3d0 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68  sult is NULL, th
2d3e0 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
2d3f0 6e 5f 62 79 74 65 73 31 36 28 29 20 72 65 74 75  n_bytes16() retu
2d400 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20  rns zero..**.** 
2d410 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65 74 75  ^The values retu
2d420 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
2d430 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d  _column_bytes()]
2d440 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65   and .** [sqlite
2d450 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
2d460 28 29 5d 20 64 6f 20 6e 6f 74 20 69 6e 63 6c 75  ()] do not inclu
2d470 64 65 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d  de the zero term
2d480 69 6e 61 74 6f 72 73 20 61 74 20 74 68 65 20 65  inators at the e
2d490 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74 72  nd.** of the str
2d4a0 69 6e 67 2e 20 20 5e 46 6f 72 20 63 6c 61 72 69  ing.  ^For clari
2d4b0 74 79 3a 20 74 68 65 20 76 61 6c 75 65 73 20 72  ty: the values r
2d4c0 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73  eturned by.** [s
2d4d0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2d4e0 74 65 73 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  tes()] and [sqli
2d4f0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2d500 31 36 28 29 5d 20 61 72 65 20 74 68 65 20 6e 75  16()] are the nu
2d510 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73  mber of.** bytes
2d520 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 2c 20   in the string, 
2d530 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  not the number o
2d540 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a  f characters..**
2d550 0a 2a 2a 20 5e 53 74 72 69 6e 67 73 20 72 65 74  .** ^Strings ret
2d560 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
2d570 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61  _column_text() a
2d580 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
2d590 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65  n_text16(),.** e
2d5a0 76 65 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67  ven empty string
2d5b0 73 2c 20 61 72 65 20 61 6c 77 61 79 73 20 7a 65  s, are always ze
2d5c0 72 6f 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20  ro terminated.  
2d5d0 5e 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76  ^The return.** v
2d5e0 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65  alue from sqlite
2d5f0 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20  3_column_blob() 
2d600 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74  for a zero-lengt
2d610 68 20 42 4c 4f 42 20 69 73 20 61 20 4e 55 4c 4c  h BLOB is a NULL
2d620 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
2d630 5e 54 68 65 20 6f 62 6a 65 63 74 20 72 65 74 75  ^The object retu
2d640 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
2d650 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d  _column_value()]
2d660 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f   is an.** [unpro
2d670 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2d680 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20 41  alue] object.  A
2d690 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71  n unprotected sq
2d6a0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
2d6b0 63 74 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62  ct.** may only b
2d6c0 65 20 75 73 65 64 20 77 69 74 68 20 5b 73 71 6c  e used with [sql
2d6d0 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28  ite3_bind_value(
2d6e0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
2d6f0 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 2e  result_value()].
2d700 0a 2a 2a 20 49 66 20 74 68 65 20 5b 75 6e 70 72  .** If the [unpr
2d710 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2d720 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 72 65  value] object re
2d730 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71  turned by.** [sq
2d740 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c  lite3_column_val
2d750 75 65 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e  ue()] is used in
2d760 20 61 6e 79 20 6f 74 68 65 72 20 77 61 79 2c 20   any other way, 
2d770 69 6e 63 6c 75 64 69 6e 67 20 63 61 6c 6c 73 0a  including calls.
2d780 2a 2a 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c  ** to routines l
2d790 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  ike [sqlite3_val
2d7a0 75 65 5f 69 6e 74 28 29 5d 2c 20 5b 73 71 6c 69  ue_int()], [sqli
2d7b0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29  te3_value_text()
2d7c0 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65  ],.** or [sqlite
2d7d0 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d  3_value_bytes()]
2d7e0 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  , then the behav
2d7f0 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ior is undefined
2d800 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ..**.** These ro
2d810 75 74 69 6e 65 73 20 61 74 74 65 6d 70 74 20 74  utines attempt t
2d820 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61  o convert the va
2d830 6c 75 65 20 77 68 65 72 65 20 61 70 70 72 6f 70  lue where approp
2d840 72 69 61 74 65 2e 20 20 5e 46 6f 72 0a 2a 2a 20  riate.  ^For.** 
2d850 65 78 61 6d 70 6c 65 2c 20 69 66 20 74 68 65 20  example, if the 
2d860 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65  internal represe
2d870 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41 54  ntation is FLOAT
2d880 20 61 6e 64 20 61 20 74 65 78 74 20 72 65 73 75   and a text resu
2d890 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75 65 73 74  lt.** is request
2d8a0 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70  ed, [sqlite3_snp
2d8b0 72 69 6e 74 66 28 29 5d 20 69 73 20 75 73 65 64  rintf()] is used
2d8c0 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 70   internally to p
2d8d0 65 72 66 6f 72 6d 20 74 68 65 0a 2a 2a 20 63 6f  erform the.** co
2d8e0 6e 76 65 72 73 69 6f 6e 20 61 75 74 6f 6d 61 74  nversion automat
2d8f0 69 63 61 6c 6c 79 2e 20 20 5e 28 54 68 65 20 66  ically.  ^(The f
2d900 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20 64  ollowing table d
2d910 65 74 61 69 6c 73 20 74 68 65 20 63 6f 6e 76 65  etails the conve
2d920 72 73 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 61  rsions.** that a
2d930 72 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a  re applied:.**.*
2d940 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  * <blockquote>.*
2d950 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d  * <table border=
2d960 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e  "1">.** <tr><th>
2d970 20 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79 70   Internal<br>Typ
2d980 65 20 3c 74 68 3e 20 52 65 71 75 65 73 74 65 64  e <th> Requested
2d990 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 43  <br>Type <th>  C
2d9a0 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20  onversion.**.** 
2d9b0 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20  <tr><td>  NULL  
2d9c0 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20    <td> INTEGER  
2d9d0 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20   <td> Result is 
2d9e0 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e  0.** <tr><td>  N
2d9f0 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f  ULL    <td>  FLO
2da00 41 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c  AT    <td> Resul
2da10 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e  t is 0.0.** <tr>
2da20 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74  <td>  NULL    <t
2da30 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64  d>   TEXT    <td
2da40 3e 20 52 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c  > Result is NULL
2da50 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e   pointer.** <tr>
2da60 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74  <td>  NULL    <t
2da70 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  d>   BLOB    <td
2da80 3e 20 52 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c  > Result is NULL
2da90 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e   pointer.** <tr>
2daa0 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74  <td> INTEGER  <t
2dab0 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64  d>  FLOAT    <td
2dac0 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69  > Convert from i
2dad0 6e 74 65 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a  nteger to float.
2dae0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45  ** <tr><td> INTE
2daf0 47 45 52 20 20 3c 74 64 3e 20 20 20 54 45 58 54  GER  <td>   TEXT
2db00 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72      <td> ASCII r
2db10 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20  endering of the 
2db20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c  integer.** <tr><
2db30 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64  td> INTEGER  <td
2db40 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  >   BLOB    <td>
2db50 20 53 61 6d 65 20 61 73 20 49 4e 54 45 47 45 52   Same as INTEGER
2db60 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74  ->TEXT.** <tr><t
2db70 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e  d>  FLOAT   <td>
2db80 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20   INTEGER   <td> 
2db90 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 66 6c 6f  Convert from flo
2dba0 61 74 20 74 6f 20 69 6e 74 65 67 65 72 0a 2a 2a  at to integer.**
2dbb0 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54   <tr><td>  FLOAT
2dbc0 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20     <td>   TEXT  
2dbd0 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e    <td> ASCII ren
2dbe0 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6c  dering of the fl
2dbf0 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  oat.** <tr><td> 
2dc00 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20   FLOAT   <td>   
2dc10 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d  BLOB    <td> Sam
2dc20 65 20 61 73 20 46 4c 4f 41 54 2d 3e 54 45 58 54  e as FLOAT->TEXT
2dc30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45  .** <tr><td>  TE
2dc40 58 54 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47  XT    <td> INTEG
2dc50 45 52 20 20 20 3c 74 64 3e 20 55 73 65 20 61 74  ER   <td> Use at
2dc60 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  oi().** <tr><td>
2dc70 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20    TEXT    <td>  
2dc80 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 55 73  FLOAT    <td> Us
2dc90 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e  e atof().** <tr>
2dca0 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74  <td>  TEXT    <t
2dcb0 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  d>   BLOB    <td
2dcc0 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c  > No change.** <
2dcd0 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20  tr><td>  BLOB   
2dce0 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20   <td> INTEGER   
2dcf0 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20  <td> Convert to 
2dd00 54 45 58 54 20 74 68 65 6e 20 75 73 65 20 61 74  TEXT then use at
2dd10 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  oi().** <tr><td>
2dd20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20    BLOB    <td>  
2dd30 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f  FLOAT    <td> Co
2dd40 6e 76 65 72 74 20 74 6f 20 54 45 58 54 20 74 68  nvert to TEXT th
2dd50 65 6e 20 75 73 65 20 61 74 6f 66 28 29 0a 2a 2a  en use atof().**
2dd60 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20   <tr><td>  BLOB 
2dd70 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20     <td>   TEXT  
2dd80 20 20 3c 74 64 3e 20 41 64 64 20 61 20 7a 65 72    <td> Add a zer
2dd90 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 66 20  o terminator if 
2dda0 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c  needed.** </tabl
2ddb0 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f  e>.** </blockquo
2ddc0 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  te>)^.**.** The 
2ddd0 74 61 62 6c 65 20 61 62 6f 76 65 20 6d 61 6b 65  table above make
2dde0 73 20 72 65 66 65 72 65 6e 63 65 20 74 6f 20 73  s reference to s
2ddf0 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72  tandard C librar
2de00 79 20 66 75 6e 63 74 69 6f 6e 73 20 61 74 6f 69  y functions atoi
2de10 28 29 0a 2a 2a 20 61 6e 64 20 61 74 6f 66 28 29  ().** and atof()
2de20 2e 20 20 53 51 4c 69 74 65 20 64 6f 65 73 20 6e  .  SQLite does n
2de30 6f 74 20 72 65 61 6c 6c 79 20 75 73 65 20 74 68  ot really use th
2de40 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20  ese functions.  
2de50 49 74 20 68 61 73 20 69 74 73 0a 2a 2a 20 6f 77  It has its.** ow
2de60 6e 20 65 71 75 69 76 61 6c 65 6e 74 20 69 6e 74  n equivalent int
2de70 65 72 6e 61 6c 20 72 6f 75 74 69 6e 65 73 2e 20  ernal routines. 
2de80 20 54 68 65 20 61 74 6f 69 28 29 20 61 6e 64 20   The atoi() and 
2de90 61 74 6f 66 28 29 20 6e 61 6d 65 73 20 61 72 65  atof() names are
2dea0 0a 2a 2a 20 75 73 65 64 20 69 6e 20 74 68 65 20  .** used in the 
2deb0 74 61 62 6c 65 20 66 6f 72 20 62 72 65 76 69 74  table for brevit
2dec0 79 20 61 6e 64 20 62 65 63 61 75 73 65 20 74 68  y and because th
2ded0 65 79 20 61 72 65 20 66 61 6d 69 6c 69 61 72 20  ey are familiar 
2dee0 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43 20 70 72 6f  to most.** C pro
2def0 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  grammers..**.** 
2df00 4e 6f 74 65 20 74 68 61 74 20 77 68 65 6e 20 74  Note that when t
2df10 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20  ype conversions 
2df20 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65 72 73 20  occur, pointers 
2df30 72 65 74 75 72 6e 65 64 20 62 79 20 70 72 69 6f  returned by prio
2df40 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71  r.** calls to sq
2df50 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
2df60 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c  b(), sqlite3_col
2df70 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f  umn_text(), and/
2df80 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  or.** sqlite3_co
2df90 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d 61  lumn_text16() ma
2dfa0 79 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64  y be invalidated
2dfb0 2e 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65 72  ..** Type conver
2dfc0 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74 65  sions and pointe
2dfd0 72 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73 20  r invalidations 
2dfe0 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 69  might occur.** i
2dff0 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  n the following 
2e000 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  cases:.**.** <ul
2e010 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e  >.** <li> The in
2e020 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73  itial content is
2e030 20 61 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c 69   a BLOB and sqli
2e040 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
2e050 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c  ) or.**      sql
2e060 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2e070 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20  16() is called. 
2e080 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   A zero-terminat
2e090 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20 20  or might.**     
2e0a0 20 6e 65 65 64 20 74 6f 20 62 65 20 61 64 64 65   need to be adde
2e0b0 64 20 74 6f 20 74 68 65 20 73 74 72 69 6e 67 2e  d to the string.
2e0c0 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68  </li>.** <li> Th
2e0d0 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e  e initial conten
2e0e0 74 20 69 73 20 55 54 46 2d 38 20 74 65 78 74 20  t is UTF-8 text 
2e0f0 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
2e100 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 6f 72 0a  mn_bytes16() or.
2e110 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f  **      sqlite3_
2e120 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20  column_text16() 
2e130 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20  is called.  The 
2e140 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20  content must be 
2e150 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20  converted.**    
2e160 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c 69    to UTF-16.</li
2e170 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e  >.** <li> The in
2e180 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73  itial content is
2e190 20 55 54 46 2d 31 36 20 74 65 78 74 20 61 6e 64   UTF-16 text and
2e1a0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2e1b0 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20 20  bytes() or.**   
2e1c0 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d     sqlite3_colum
2e1d0 6e 5f 74 65 78 74 28 29 20 69 73 20 63 61 6c 6c  n_text() is call
2e1e0 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74  ed.  The content
2e1f0 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74   must be convert
2e200 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54  ed.**      to UT
2e210 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75  F-8.</li>.** </u
2e220 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76 65 72  l>.**.** ^Conver
2e230 73 69 6f 6e 73 20 62 65 74 77 65 65 6e 20 55 54  sions between UT
2e240 46 2d 31 36 62 65 20 61 6e 64 20 55 54 46 2d 31  F-16be and UTF-1
2e250 36 6c 65 20 61 72 65 20 61 6c 77 61 79 73 20 64  6le are always d
2e260 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 61 6e 64  one in place and
2e270 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c   do.** not inval
2e280 69 64 61 74 65 20 61 20 70 72 69 6f 72 20 70 6f  idate a prior po
2e290 69 6e 74 65 72 2c 20 74 68 6f 75 67 68 20 6f 66  inter, though of
2e2a0 20 63 6f 75 72 73 65 20 74 68 65 20 63 6f 6e 74   course the cont
2e2b0 65 6e 74 20 6f 66 20 74 68 65 20 62 75 66 66 65  ent of the buffe
2e2c0 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 70 72  r.** that the pr
2e2d0 69 6f 72 20 70 6f 69 6e 74 65 72 20 72 65 66 65  ior pointer refe
2e2e0 72 65 6e 63 65 73 20 77 69 6c 6c 20 68 61 76 65  rences will have
2e2f0 20 62 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e 20   been modified. 
2e300 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a 20   Other kinds.** 
2e310 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 72  of conversion ar
2e320 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20  e done in place 
2e330 77 68 65 6e 20 69 74 20 69 73 20 70 6f 73 73 69  when it is possi
2e340 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74 69 6d  ble, but sometim
2e350 65 73 20 74 68 65 79 0a 2a 2a 20 61 72 65 20 6e  es they.** are n
2e360 6f 74 20 70 6f 73 73 69 62 6c 65 20 61 6e 64 20  ot possible and 
2e370 69 6e 20 74 68 6f 73 65 20 63 61 73 65 73 20 70  in those cases p
2e380 72 69 6f 72 20 70 6f 69 6e 74 65 72 73 20 61 72  rior pointers ar
2e390 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a  e invalidated..*
2e3a0 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65 73 74 20  *.** The safest 
2e3b0 61 6e 64 20 65 61 73 69 65 73 74 20 74 6f 20 72  and easiest to r
2e3c0 65 6d 65 6d 62 65 72 20 70 6f 6c 69 63 79 20 69  emember policy i
2e3d0 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73  s to invoke thes
2e3e0 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e  e routines.** in
2e3f0 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c   one of the foll
2e400 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a  owing ways:.**.*
2e410 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73  * <ul>.**  <li>s
2e420 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2e430 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79  xt() followed by
2e440 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2e450 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20  bytes()</li>.** 
2e460 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c   <li>sqlite3_col
2e470 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f  umn_blob() follo
2e480 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  wed by sqlite3_c
2e490 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c  olumn_bytes()</l
2e4a0 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74  i>.**  <li>sqlit
2e4b0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
2e4c0 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73  () followed by s
2e4d0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2e4e0 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20  tes16()</li>.** 
2e4f0 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f  </ul>.**.** In o
2e500 74 68 65 72 20 77 6f 72 64 73 2c 20 79 6f 75 20  ther words, you 
2e510 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69  should call sqli
2e520 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
2e530 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  ),.** sqlite3_co
2e540 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 20  lumn_blob(), or 
2e550 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2e560 65 78 74 31 36 28 29 20 66 69 72 73 74 20 74 6f  ext16() first to
2e570 20 66 6f 72 63 65 20 74 68 65 20 72 65 73 75 6c   force the resul
2e580 74 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64 65  t.** into the de
2e590 73 69 72 65 64 20 66 6f 72 6d 61 74 2c 20 74 68  sired format, th
2e5a0 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65  en invoke sqlite
2e5b0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
2e5c0 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   or.** sqlite3_c
2e5d0 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20  olumn_bytes16() 
2e5e0 74 6f 20 66 69 6e 64 20 74 68 65 20 73 69 7a 65  to find the size
2e5f0 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 2e 20   of the result. 
2e600 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c   Do not mix call
2e610 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f  s.** to sqlite3_
2e620 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72  column_text() or
2e630 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2e640 62 6c 6f 62 28 29 20 77 69 74 68 20 63 61 6c 6c  blob() with call
2e650 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  s to.** sqlite3_
2e660 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
2e670 2c 20 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 78  , and do not mix
2e680 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
2e690 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
2e6a0 29 0a 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73 20  ).** with calls 
2e6b0 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  to sqlite3_colum
2e6c0 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a  n_bytes()..**.**
2e6d0 20 5e 54 68 65 20 70 6f 69 6e 74 65 72 73 20 72   ^The pointers r
2e6e0 65 74 75 72 6e 65 64 20 61 72 65 20 76 61 6c 69  eturned are vali
2e6f0 64 20 75 6e 74 69 6c 20 61 20 74 79 70 65 20 63  d until a type c
2e700 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73  onversion occurs
2e710 20 61 73 0a 2a 2a 20 64 65 73 63 72 69 62 65 64   as.** described
2e720 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c   above, or until
2e730 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2e740 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
2e750 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  set()] or.** [sq
2e760 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
2e770 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 5e 54  ] is called.  ^T
2e780 68 65 20 6d 65 6d 6f 72 79 20 73 70 61 63 65 20  he memory space 
2e790 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 73 74 72  used to hold str
2e7a0 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42  ings.** and BLOB
2e7b0 73 20 69 73 20 66 72 65 65 64 20 61 75 74 6f 6d  s is freed autom
2e7c0 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20 3c 62  atically.  Do <b
2e7d0 3e 6e 6f 74 3c 2f 62 3e 20 70 61 73 73 20 74 68  >not</b> pass th
2e7e0 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72  e pointers retur
2e7f0 6e 65 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ned.** [sqlite3_
2e800 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20  column_blob()], 
2e810 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
2e820 74 65 78 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e  text()], etc. in
2e830 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  to.** [sqlite3_f
2e840 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ree()]..**.** ^(
2e850 49 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  If a memory allo
2e860 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63  cation error occ
2e870 75 72 73 20 64 75 72 69 6e 67 20 74 68 65 20 65  urs during the e
2e880 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79  valuation of any
2e890 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20 72 6f 75  .** of these rou
2e8a0 74 69 6e 65 73 2c 20 61 20 64 65 66 61 75 6c 74  tines, a default
2e8b0 20 76 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e   value is return
2e8c0 65 64 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74  ed.  The default
2e8d0 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74   value.** is eit
2e8e0 68 65 72 20 74 68 65 20 69 6e 74 65 67 65 72 20  her the integer 
2e8f0 30 2c 20 74 68 65 20 66 6c 6f 61 74 69 6e 67 20  0, the floating 
2e900 70 6f 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30  point number 0.0
2e910 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70  , or a NULL.** p
2e920 6f 69 6e 74 65 72 2e 20 20 53 75 62 73 65 71 75  ointer.  Subsequ
2e930 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  ent calls to [sq
2e940 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d  lite3_errcode()]
2e950 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20   will return.** 
2e960 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 29  [SQLITE_NOMEM].)
2e970 5e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ^.*/.SQLITE_API 
2e980 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
2e990 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
2e9a0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2e9b0 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45  nt iCol);.SQLITE
2e9c0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
2e9d0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71  _column_bytes(sq
2e9e0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2e9f0 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41   iCol);.SQLITE_A
2ea00 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  PI int sqlite3_c
2ea10 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 73 71  olumn_bytes16(sq
2ea20 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2ea30 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41   iCol);.SQLITE_A
2ea40 50 49 20 64 6f 75 62 6c 65 20 73 71 6c 69 74 65  PI double sqlite
2ea50 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28  3_column_double(
2ea60 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2ea70 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45  nt iCol);.SQLITE
2ea80 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
2ea90 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69  _column_int(sqli
2eaa0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
2eab0 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  Col);.SQLITE_API
2eac0 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73   sqlite3_int64 s
2ead0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e  qlite3_column_in
2eae0 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  t64(sqlite3_stmt
2eaf0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51  *, int iCol);.SQ
2eb00 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 75  LITE_API const u
2eb10 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71  nsigned char *sq
2eb20 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2eb30 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  t(sqlite3_stmt*,
2eb40 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49   int iCol);.SQLI
2eb50 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69  TE_API const voi
2eb60 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
2eb70 6e 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33  n_text16(sqlite3
2eb80 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
2eb90 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
2eba0 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
2ebb0 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74  _type(sqlite3_st
2ebc0 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
2ebd0 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74  SQLITE_API sqlit
2ebe0 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c 69 74 65  e3_value *sqlite
2ebf0 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 73  3_column_value(s
2ec00 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2ec10 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20  t iCol);../*.** 
2ec20 43 41 50 49 33 52 45 46 3a 20 44 65 73 74 72 6f  CAPI3REF: Destro
2ec30 79 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61  y A Prepared Sta
2ec40 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a  tement Object.**
2ec50 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2ec60 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63  _finalize() func
2ec70 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74  tion is called t
2ec80 6f 20 64 65 6c 65 74 65 20 61 20 5b 70 72 65 70  o delete a [prep
2ec90 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
2eca0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74  .** ^If the most
2ecb0 20 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69   recent evaluati
2ecc0 6f 6e 20 6f 66 20 74 68 65 20 73 74 61 74 65 6d  on of the statem
2ecd0 65 6e 74 20 65 6e 63 6f 75 6e 74 65 72 65 64 20  ent encountered 
2ece0 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 72 20  no errors.** or 
2ecf0 69 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  if the statement
2ed00 20 69 73 20 6e 65 76 65 72 20 62 65 65 6e 20 65   is never been e
2ed10 76 61 6c 75 61 74 65 64 2c 20 74 68 65 6e 20 73  valuated, then s
2ed20 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2ed30 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 53 51 4c  ) returns.** SQL
2ed40 49 54 45 5f 4f 4b 2e 20 20 5e 49 66 20 74 68 65  ITE_OK.  ^If the
2ed50 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 76 61   most recent eva
2ed60 6c 75 61 74 69 6f 6e 20 6f 66 20 73 74 61 74 65  luation of state
2ed70 6d 65 6e 74 20 53 20 66 61 69 6c 65 64 2c 20 74  ment S failed, t
2ed80 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66  hen.** sqlite3_f
2ed90 69 6e 61 6c 69 7a 65 28 53 29 20 72 65 74 75 72  inalize(S) retur
2eda0 6e 73 20 74 68 65 20 61 70 70 72 6f 70 72 69 61  ns the appropria
2edb0 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  te [error code] 
2edc0 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  or.** [extended 
2edd0 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a  error code]..**.
2ede0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2edf0 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 6f 75 74  finalize(S) rout
2ee00 69 6e 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65  ine can be calle
2ee10 64 20 61 74 20 61 6e 79 20 70 6f 69 6e 74 20 64  d at any point d
2ee20 75 72 69 6e 67 0a 2a 2a 20 74 68 65 20 6c 69 66  uring.** the lif
2ee30 65 20 63 79 63 6c 65 20 6f 66 20 5b 70 72 65 70  e cycle of [prep
2ee40 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2ee50 53 3a 0a 2a 2a 20 62 65 66 6f 72 65 20 73 74 61  S:.** before sta
2ee60 74 65 6d 65 6e 74 20 53 20 69 73 20 65 76 65 72  tement S is ever
2ee70 20 65 76 61 6c 75 61 74 65 64 2c 20 61 66 74 65   evaluated, afte
2ee80 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  r.** one or more
2ee90 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
2eea0 65 33 5f 72 65 73 65 74 28 29 5d 2c 20 6f 72 20  e3_reset()], or 
2eeb0 61 66 74 65 72 20 61 6e 79 20 63 61 6c 6c 0a 2a  after any call.*
2eec0 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  * to [sqlite3_st
2eed0 65 70 28 29 5d 20 72 65 67 61 72 64 6c 65 73 73  ep()] regardless
2eee0 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e   of whether or n
2eef0 6f 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  ot the statement
2ef00 20 68 61 73 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65   has.** complete
2ef10 64 20 65 78 65 63 75 74 69 6f 6e 2e 0a 2a 2a 0a  d execution..**.
2ef20 2a 2a 20 5e 49 6e 76 6f 6b 69 6e 67 20 73 71 6c  ** ^Invoking sql
2ef30 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20  ite3_finalize() 
2ef40 6f 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  on a NULL pointe
2ef50 72 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20  r is a harmless 
2ef60 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  no-op..**.** The
2ef70 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
2ef80 74 20 66 69 6e 61 6c 69 7a 65 20 65 76 65 72 79  t finalize every
2ef90 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2efa0 6d 65 6e 74 5d 20 69 6e 20 6f 72 64 65 72 20 74  ment] in order t
2efb0 6f 20 61 76 6f 69 64 0a 2a 2a 20 72 65 73 6f 75  o avoid.** resou
2efc0 72 63 65 20 6c 65 61 6b 73 2e 20 20 49 74 20 69  rce leaks.  It i
2efd0 73 20 61 20 67 72 69 65 76 6f 75 73 20 65 72 72  s a grievous err
2efe0 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70 6c 69  or for the appli
2eff0 63 61 74 69 6f 6e 20 74 6f 20 74 72 79 20 74 6f  cation to try to
2f000 20 75 73 65 0a 2a 2a 20 61 20 70 72 65 70 61 72   use.** a prepar
2f010 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74  ed statement aft
2f020 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 66  er it has been f
2f030 69 6e 61 6c 69 7a 65 64 2e 20 20 41 6e 79 20 75  inalized.  Any u
2f040 73 65 20 6f 66 20 61 20 70 72 65 70 61 72 65 64  se of a prepared
2f050 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 66  .** statement af
2f060 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20  ter it has been 
2f070 66 69 6e 61 6c 69 7a 65 64 20 63 61 6e 20 72 65  finalized can re
2f080 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65  sult in undefine
2f090 64 20 61 6e 64 0a 2a 2a 20 75 6e 64 65 73 69 72  d and.** undesir
2f0a0 61 62 6c 65 20 62 65 68 61 76 69 6f 72 20 73 75  able behavior su
2f0b0 63 68 20 61 73 20 73 65 67 66 61 75 6c 74 73 20  ch as segfaults 
2f0c0 61 6e 64 20 68 65 61 70 20 63 6f 72 72 75 70 74  and heap corrupt
2f0d0 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ion..*/.SQLITE_A
2f0e0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 66  PI int sqlite3_f
2f0f0 69 6e 61 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f  inalize(sqlite3_
2f100 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
2f110 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
2f120 65 73 65 74 20 41 20 50 72 65 70 61 72 65 64 20  eset A Prepared 
2f130 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74  Statement Object
2f140 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
2f150 65 33 5f 72 65 73 65 74 28 29 20 66 75 6e 63 74  e3_reset() funct
2f160 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f  ion is called to
2f170 20 72 65 73 65 74 20 61 20 5b 70 72 65 70 61 72   reset a [prepar
2f180 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a  ed statement].**
2f190 20 6f 62 6a 65 63 74 20 62 61 63 6b 20 74 6f 20   object back to 
2f1a0 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74  its initial stat
2f1b0 65 2c 20 72 65 61 64 79 20 74 6f 20 62 65 20 72  e, ready to be r
2f1c0 65 2d 65 78 65 63 75 74 65 64 2e 0a 2a 2a 20 5e  e-executed..** ^
2f1d0 41 6e 79 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  Any SQL statemen
2f1e0 74 20 76 61 72 69 61 62 6c 65 73 20 74 68 61 74  t variables that
2f1f0 20 68 61 64 20 76 61 6c 75 65 73 20 62 6f 75 6e   had values boun
2f200 64 20 74 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a  d to them using.
2f210 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** the [sqlite3_
2f220 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69  bind_blob | sqli
2f230 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49  te3_bind_*() API
2f240 5d 20 72 65 74 61 69 6e 20 74 68 65 69 72 20 76  ] retain their v
2f250 61 6c 75 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73  alues..** Use [s
2f260 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e  qlite3_clear_bin
2f270 64 69 6e 67 73 28 29 5d 20 74 6f 20 72 65 73 65  dings()] to rese
2f280 74 20 74 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a  t the bindings..
2f290 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69  **.** ^The [sqli
2f2a0 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e  te3_reset(S)] in
2f2b0 74 65 72 66 61 63 65 20 72 65 73 65 74 73 20 74  terface resets t
2f2c0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
2f2d0 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20 62 61 63  tement] S.** bac
2f2e0 6b 20 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69  k to the beginni
2f2f0 6e 67 20 6f 66 20 69 74 73 20 70 72 6f 67 72 61  ng of its progra
2f300 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  m..**.** ^If the
2f310 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c   most recent cal
2f320 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  l to [sqlite3_st
2f330 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a  ep(S)] for the.*
2f340 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
2f350 65 6d 65 6e 74 5d 20 53 20 72 65 74 75 72 6e 65  ement] S returne
2f360 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f  d [SQLITE_ROW] o
2f370 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c  r [SQLITE_DONE],
2f380 0a 2a 2a 20 6f 72 20 69 66 20 5b 73 71 6c 69 74  .** or if [sqlit
2f390 65 33 5f 73 74 65 70 28 53 29 5d 20 68 61 73 20  e3_step(S)] has 
2f3a0 6e 65 76 65 72 20 62 65 66 6f 72 65 20 62 65 65  never before bee
2f3b0 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a  n called on S,.*
2f3c0 2a 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f  * then [sqlite3_
2f3d0 72 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e  reset(S)] return
2f3e0 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a  s [SQLITE_OK]..*
2f3f0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73  *.** ^If the mos
2f400 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f  t recent call to
2f410 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
2f420 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70  )] for the.** [p
2f430 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2f440 74 5d 20 53 20 69 6e 64 69 63 61 74 65 64 20 61  t] S indicated a
2f450 6e 20 65 72 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a  n error, then.**
2f460 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2f470 53 29 5d 20 72 65 74 75 72 6e 73 20 61 6e 20 61  S)] returns an a
2f480 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f  ppropriate [erro
2f490 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  r code]..**.** ^
2f4a0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  The [sqlite3_res
2f4b0 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65  et(S)] interface
2f4c0 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65   does not change
2f4d0 20 74 68 65 20 76 61 6c 75 65 73 0a 2a 2a 20 6f   the values.** o
2f4e0 66 20 61 6e 79 20 5b 73 71 6c 69 74 65 33 5f 62  f any [sqlite3_b
2f4f0 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e 67  ind_blob|binding
2f500 73 5d 20 6f 6e 20 74 68 65 20 5b 70 72 65 70 61  s] on the [prepa
2f510 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
2f520 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
2f530 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 73 65  int sqlite3_rese
2f540 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  t(sqlite3_stmt *
2f550 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
2f560 41 50 49 33 52 45 46 3a 20 43 72 65 61 74 65 20  API3REF: Create 
2f570 4f 72 20 52 65 64 65 66 69 6e 65 20 53 51 4c 20  Or Redefine SQL 
2f580 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59  Functions.** KEY
2f590 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e  WORDS: {function
2f5a0 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e   creation routin
2f5b0 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  es}.** KEYWORDS:
2f5c0 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   {application-de
2f5d0 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
2f5e0 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  on}.** KEYWORDS:
2f5f0 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   {application-de
2f600 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
2f610 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  ons}.**.** ^Thes
2f620 65 20 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c  e functions (col
2f630 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20  lectively known 
2f640 61 73 20 22 66 75 6e 63 74 69 6f 6e 20 63 72 65  as "function cre
2f650 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29  ation routines")
2f660 0a 2a 2a 20 61 72 65 20 75 73 65 64 20 74 6f 20  .** are used to 
2f670 61 64 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  add SQL function
2f680 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 20  s or aggregates 
2f690 6f 72 20 74 6f 20 72 65 64 65 66 69 6e 65 20 74  or to redefine t
2f6a0 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f  he behavior.** o
2f6b0 66 20 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66  f existing SQL f
2f6c0 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72  unctions or aggr
2f6d0 65 67 61 74 65 73 2e 20 20 54 68 65 20 6f 6e 6c  egates.  The onl
2f6e0 79 20 64 69 66 66 65 72 65 6e 63 65 73 20 62 65  y differences be
2f6f0 74 77 65 65 6e 0a 2a 2a 20 74 68 65 73 65 20 72  tween.** these r
2f700 6f 75 74 69 6e 65 73 20 61 72 65 20 74 68 65 20  outines are the 
2f710 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 65 78  text encoding ex
2f720 70 65 63 74 65 64 20 66 6f 72 0a 2a 2a 20 74 68  pected for.** th
2f730 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
2f740 65 72 20 28 74 68 65 20 6e 61 6d 65 20 6f 66 20  er (the name of 
2f750 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 62 65 69  the function bei
2f760 6e 67 20 63 72 65 61 74 65 64 29 0a 2a 2a 20 61  ng created).** a
2f770 6e 64 20 74 68 65 20 70 72 65 73 65 6e 63 65 20  nd the presence 
2f780 6f 72 20 61 62 73 65 6e 63 65 20 6f 66 20 61 20  or absence of a 
2f790 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62  destructor callb
2f7a0 61 63 6b 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61  ack for.** the a
2f7b0 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20  pplication data 
2f7c0 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  pointer..**.** ^
2f7d0 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
2f7e0 74 65 72 20 69 73 20 74 68 65 20 5b 64 61 74 61  ter is the [data
2f7f0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
2f800 20 74 6f 20 77 68 69 63 68 20 74 68 65 20 53 51   to which the SQ
2f810 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73  L.** function is
2f820 20 74 6f 20 62 65 20 61 64 64 65 64 2e 20 20 5e   to be added.  ^
2f830 49 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  If an applicatio
2f840 6e 20 75 73 65 73 20 6d 6f 72 65 20 74 68 61 6e  n uses more than
2f850 20 6f 6e 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   one database.**
2f860 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 65 6e   connection then
2f870 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
2f880 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
2f890 6e 73 20 6d 75 73 74 20 62 65 20 61 64 64 65 64  ns must be added
2f8a0 0a 2a 2a 20 74 6f 20 65 61 63 68 20 64 61 74 61  .** to each data
2f8b0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
2f8c0 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a  separately..**.*
2f8d0 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61  * ^The second pa
2f8e0 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e  rameter is the n
2f8f0 61 6d 65 20 6f 66 20 74 68 65 20 53 51 4c 20 66  ame of the SQL f
2f900 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 63 72  unction to be cr
2f910 65 61 74 65 64 20 6f 72 0a 2a 2a 20 72 65 64 65  eated or.** rede
2f920 66 69 6e 65 64 2e 20 20 5e 54 68 65 20 6c 65 6e  fined.  ^The len
2f930 67 74 68 20 6f 66 20 74 68 65 20 6e 61 6d 65 20  gth of the name 
2f940 69 73 20 6c 69 6d 69 74 65 64 20 74 6f 20 32 35  is limited to 25
2f950 35 20 62 79 74 65 73 20 69 6e 20 61 20 55 54 46  5 bytes in a UTF
2f960 2d 38 0a 2a 2a 20 72 65 70 72 65 73 65 6e 74 61  -8.** representa
2f970 74 69 6f 6e 2c 20 65 78 63 6c 75 73 69 76 65 20  tion, exclusive 
2f980 6f 66 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d  of the zero-term
2f990 69 6e 61 74 6f 72 2e 20 20 5e 4e 6f 74 65 20 74  inator.  ^Note t
2f9a0 68 61 74 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20  hat the name.** 
2f9b0 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20 69 73 20  length limit is 
2f9c0 69 6e 20 55 54 46 2d 38 20 62 79 74 65 73 2c 20  in UTF-8 bytes, 
2f9d0 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 20 6e  not characters n
2f9e0 6f 72 20 55 54 46 2d 31 36 20 62 79 74 65 73 2e  or UTF-16 bytes.
2f9f0 20 20 0a 2a 2a 20 5e 41 6e 79 20 61 74 74 65 6d    .** ^Any attem
2fa00 70 74 20 74 6f 20 63 72 65 61 74 65 20 61 20 66  pt to create a f
2fa10 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 6c  unction with a l
2fa20 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69  onger name.** wi
2fa30 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20 5b 53 51  ll result in [SQ
2fa40 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 62 65 69  LITE_MISUSE] bei
2fa50 6e 67 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  ng returned..**.
2fa60 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 70 61  ** ^The third pa
2fa70 72 61 6d 65 74 65 72 20 28 6e 41 72 67 29 0a 2a  rameter (nArg).*
2fa80 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  * is the number 
2fa90 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61  of arguments tha
2faa0 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  t the SQL functi
2fab0 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61  on or.** aggrega
2fac0 74 65 20 74 61 6b 65 73 2e 20 5e 49 66 20 74 68  te takes. ^If th
2fad0 69 73 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  is parameter is 
2fae0 2d 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c  -1, then the SQL
2faf0 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20   function or.** 
2fb00 61 67 67 72 65 67 61 74 65 20 6d 61 79 20 74 61  aggregate may ta
2fb10 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66  ke any number of
2fb20 20 61 72 67 75 6d 65 6e 74 73 20 62 65 74 77 65   arguments betwe
2fb30 65 6e 20 30 20 61 6e 64 20 74 68 65 20 6c 69 6d  en 0 and the lim
2fb40 69 74 0a 2a 2a 20 73 65 74 20 62 79 20 5b 73 71  it.** set by [sq
2fb50 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51  lite3_limit]([SQ
2fb60 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54  LITE_LIMIT_FUNCT
2fb70 49 4f 4e 5f 41 52 47 5d 29 2e 20 20 49 66 20 74  ION_ARG]).  If t
2fb80 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61  he third.** para
2fb90 6d 65 74 65 72 20 69 73 20 6c 65 73 73 20 74 68  meter is less th
2fba0 61 6e 20 2d 31 20 6f 72 20 67 72 65 61 74 65 72  an -1 or greater
2fbb0 20 74 68 61 6e 20 31 32 37 20 74 68 65 6e 20 74   than 127 then t
2fbc0 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 0a 2a  he behavior is.*
2fbd0 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  * undefined..**.
2fbe0 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70  ** ^The fourth p
2fbf0 61 72 61 6d 65 74 65 72 2c 20 65 54 65 78 74 52  arameter, eTextR
2fc00 65 70 2c 20 73 70 65 63 69 66 69 65 73 20 77 68  ep, specifies wh
2fc10 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54  at.** [SQLITE_UT
2fc20 46 38 20 7c 20 74 65 78 74 20 65 6e 63 6f 64 69  F8 | text encodi
2fc30 6e 67 5d 20 74 68 69 73 20 53 51 4c 20 66 75 6e  ng] this SQL fun
2fc40 63 74 69 6f 6e 20 70 72 65 66 65 72 73 20 66 6f  ction prefers fo
2fc50 72 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d 65 74  r.** its paramet
2fc60 65 72 73 2e 20 20 45 76 65 72 79 20 53 51 4c 20  ers.  Every SQL 
2fc70 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65  function impleme
2fc80 6e 74 61 74 69 6f 6e 20 6d 75 73 74 20 62 65 20  ntation must be 
2fc90 61 62 6c 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20  able to work.** 
2fca0 77 69 74 68 20 55 54 46 2d 38 2c 20 55 54 46 2d  with UTF-8, UTF-
2fcb0 31 36 6c 65 2c 20 6f 72 20 55 54 46 2d 31 36 62  16le, or UTF-16b
2fcc0 65 2e 20 20 42 75 74 20 73 6f 6d 65 20 69 6d 70  e.  But some imp
2fcd0 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 61 79  lementations may
2fce0 20 62 65 0a 2a 2a 20 6d 6f 72 65 20 65 66 66 69   be.** more effi
2fcf0 63 69 65 6e 74 20 77 69 74 68 20 6f 6e 65 20 65  cient with one e
2fd00 6e 63 6f 64 69 6e 67 20 74 68 61 6e 20 61 6e 6f  ncoding than ano
2fd10 74 68 65 72 2e 20 20 5e 41 6e 20 61 70 70 6c 69  ther.  ^An appli
2fd20 63 61 74 69 6f 6e 20 6d 61 79 0a 2a 2a 20 69 6e  cation may.** in
2fd30 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65  voke sqlite3_cre
2fd40 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20 6f  ate_function() o
2fd50 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  r sqlite3_create
2fd60 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 20 6d 75  _function16() mu
2fd70 6c 74 69 70 6c 65 0a 2a 2a 20 74 69 6d 65 73 20  ltiple.** times 
2fd80 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 66 75  with the same fu
2fd90 6e 63 74 69 6f 6e 20 62 75 74 20 77 69 74 68 20  nction but with 
2fda0 64 69 66 66 65 72 65 6e 74 20 76 61 6c 75 65 73  different values
2fdb0 20 6f 66 20 65 54 65 78 74 52 65 70 2e 0a 2a 2a   of eTextRep..**
2fdc0 20 5e 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20   ^When multiple 
2fdd0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
2fde0 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63  of the same func
2fdf0 74 69 6f 6e 20 61 72 65 20 61 76 61 69 6c 61 62  tion are availab
2fe00 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69  le, SQLite.** wi
2fe10 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e 65 20  ll pick the one 
2fe20 74 68 61 74 20 69 6e 76 6f 6c 76 65 73 20 74 68  that involves th
2fe30 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f  e least amount o
2fe40 66 20 64 61 74 61 20 63 6f 6e 76 65 72 73 69 6f  f data conversio
2fe50 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 72 65 20 69  n..** If there i
2fe60 73 20 6f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20  s only a single 
2fe70 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77  implementation w
2fe80 68 69 63 68 20 64 6f 65 73 20 6e 6f 74 20 63 61  hich does not ca
2fe90 72 65 20 77 68 61 74 20 74 65 78 74 0a 2a 2a 20  re what text.** 
2fea0 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64  encoding is used
2feb0 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 75 72 74  , then the fourt
2fec0 68 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c  h argument shoul
2fed0 64 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 4e 59  d be [SQLITE_ANY
2fee0 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66  ]..**.** ^(The f
2fef0 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  ifth parameter i
2ff00 73 20 61 6e 20 61 72 62 69 74 72 61 72 79 20 70  s an arbitrary p
2ff10 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 69 6d 70  ointer.  The imp
2ff20 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74  lementation of t
2ff30 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 63  he.** function c
2ff40 61 6e 20 67 61 69 6e 20 61 63 63 65 73 73 20 74  an gain access t
2ff50 6f 20 74 68 69 73 20 70 6f 69 6e 74 65 72 20 75  o this pointer u
2ff60 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 75 73  sing [sqlite3_us
2ff70 65 72 5f 64 61 74 61 28 29 5d 2e 29 5e 0a 2a 2a  er_data()].)^.**
2ff80 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74 68 2c 20  .** ^The sixth, 
2ff90 73 65 76 65 6e 74 68 20 61 6e 64 20 65 69 67 68  seventh and eigh
2ffa0 74 68 20 70 61 72 61 6d 65 74 65 72 73 2c 20 78  th parameters, x
2ffb0 46 75 6e 63 2c 20 78 53 74 65 70 20 61 6e 64 20  Func, xStep and 
2ffc0 78 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20 70  xFinal, are.** p
2ffd0 6f 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61 6e  ointers to C-lan
2ffe0 67 75 61 67 65 20 66 75 6e 63 74 69 6f 6e 73 20  guage functions 
2fff0 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74  that implement t
30000 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
30010 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 2e  or.** aggregate.
30020 20 5e 41 20 73 63 61 6c 61 72 20 53 51 4c 20 66   ^A scalar SQL f
30030 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73  unction requires
30040 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69   an implementati
30050 6f 6e 20 6f 66 20 74 68 65 20 78 46 75 6e 63 0a  on of the xFunc.
30060 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79  ** callback only
30070 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20  ; NULL pointers 
30080 6d 75 73 74 20 62 65 20 70 61 73 73 65 64 20 61  must be passed a
30090 73 20 74 68 65 20 78 53 74 65 70 20 61 6e 64 20  s the xStep and 
300a0 78 46 69 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d 65  xFinal.** parame
300b0 74 65 72 73 2e 20 5e 41 6e 20 61 67 67 72 65 67  ters. ^An aggreg
300c0 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ate SQL function
300d0 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70   requires an imp
300e0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 78  lementation of x
300f0 53 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69 6e  Step.** and xFin
30100 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 70 6f 69 6e  al and NULL poin
30110 74 65 72 20 6d 75 73 74 20 62 65 20 70 61 73 73  ter must be pass
30120 65 64 20 66 6f 72 20 78 46 75 6e 63 2e 20 5e 54  ed for xFunc. ^T
30130 6f 20 64 65 6c 65 74 65 20 61 6e 20 65 78 69 73  o delete an exis
30140 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 6e 63  ting.** SQL func
30150 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74  tion or aggregat
30160 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20 70 6f 69  e, pass NULL poi
30170 6e 74 65 72 73 20 66 6f 72 20 61 6c 6c 20 74 68  nters for all th
30180 72 65 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ree function.** 
30190 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a  callbacks..**.**
301a0 20 5e 28 49 66 20 74 68 65 20 6e 69 6e 74 68 20   ^(If the ninth 
301b0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
301c0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
301d0 74 69 6f 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74  tion_v2() is not
301e0 20 4e 55 4c 4c 2c 0a 2a 2a 20 74 68 65 6e 20 69   NULL,.** then i
301f0 74 20 69 73 20 64 65 73 74 72 75 63 74 6f 72 20  t is destructor 
30200 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61 74  for the applicat
30210 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72  ion data pointer
30220 2e 20 0a 2a 2a 20 54 68 65 20 64 65 73 74 72 75  . .** The destru
30230 63 74 6f 72 20 69 73 20 69 6e 76 6f 6b 65 64 20  ctor is invoked 
30240 77 68 65 6e 20 74 68 65 20 66 75 6e 63 74 69 6f  when the functio
30250 6e 20 69 73 20 64 65 6c 65 74 65 64 2c 20 65 69  n is deleted, ei
30260 74 68 65 72 20 62 79 20 62 65 69 6e 67 0a 2a 2a  ther by being.**
30270 20 6f 76 65 72 6c 6f 61 64 65 64 20 6f 72 20 77   overloaded or w
30280 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
30290 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73   connection clos
302a0 65 73 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 64 65  es.)^.** ^The de
302b0 73 74 72 75 63 74 6f 72 20 69 73 20 61 6c 73 6f  structor is also
302c0 20 69 6e 76 6f 6b 65 64 20 69 66 20 74 68 65 20   invoked if the 
302d0 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  call to.** sqlit
302e0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
302f0 6f 6e 5f 76 32 28 29 20 66 61 69 6c 73 2e 0a 2a  on_v2() fails..*
30300 2a 20 5e 57 68 65 6e 20 74 68 65 20 64 65 73 74  * ^When the dest
30310 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20  ructor callback 
30320 6f 66 20 74 68 65 20 74 65 6e 74 68 20 70 61 72  of the tenth par
30330 61 6d 65 74 65 72 20 69 73 20 69 6e 76 6f 6b 65  ameter is invoke
30340 64 2c 20 69 74 0a 2a 2a 20 69 73 20 70 61 73 73  d, it.** is pass
30350 65 64 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  ed a single argu
30360 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20  ment which is a 
30370 63 6f 70 79 20 6f 66 20 74 68 65 20 61 70 70 6c  copy of the appl
30380 69 63 61 74 69 6f 6e 20 64 61 74 61 20 0a 2a 2a  ication data .**
30390 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 20 77   pointer which w
303a0 61 73 20 74 68 65 20 66 69 66 74 68 20 70 61 72  as the fifth par
303b0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
303c0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
303d0 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49  n_v2()..**.** ^I
303e0 74 20 69 73 20 70 65 72 6d 69 74 74 65 64 20 74  t is permitted t
303f0 6f 20 72 65 67 69 73 74 65 72 20 6d 75 6c 74 69  o register multi
30400 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ple implementati
30410 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 0a  ons of the same.
30420 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 77 69 74  ** functions wit
30430 68 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20  h the same name 
30440 62 75 74 20 77 69 74 68 20 65 69 74 68 65 72 20  but with either 
30450 64 69 66 66 65 72 69 6e 67 20 6e 75 6d 62 65 72  differing number
30460 73 20 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  s of.** argument
30470 73 20 6f 72 20 64 69 66 66 65 72 69 6e 67 20 70  s or differing p
30480 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e  referred text en
30490 63 6f 64 69 6e 67 73 2e 20 20 5e 53 51 4c 69 74  codings.  ^SQLit
304a0 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 74 68  e will use.** th
304b0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
304c0 20 74 68 61 74 20 6d 6f 73 74 20 63 6c 6f 73 65   that most close
304d0 6c 79 20 6d 61 74 63 68 65 73 20 74 68 65 20 77  ly matches the w
304e0 61 79 20 69 6e 20 77 68 69 63 68 20 74 68 65 0a  ay in which the.
304f0 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ** SQL function 
30500 69 73 20 75 73 65 64 2e 20 20 5e 41 20 66 75 6e  is used.  ^A fun
30510 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  ction implementa
30520 74 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e 2d  tion with a non-
30530 6e 65 67 61 74 69 76 65 0a 2a 2a 20 6e 41 72 67  negative.** nArg
30540 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
30550 62 65 74 74 65 72 20 6d 61 74 63 68 20 74 68 61  better match tha
30560 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70  n a function imp
30570 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68  lementation with
30580 0a 2a 2a 20 61 20 6e 65 67 61 74 69 76 65 20 6e  .** a negative n
30590 41 72 67 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f  Arg.  ^A functio
305a0 6e 20 77 68 65 72 65 20 74 68 65 20 70 72 65 66  n where the pref
305b0 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64  erred text encod
305c0 69 6e 67 0a 2a 2a 20 6d 61 74 63 68 65 73 20 74  ing.** matches t
305d0 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 63 6f  he database enco
305e0 64 69 6e 67 20 69 73 20 61 20 62 65 74 74 65 72  ding is a better
305f0 0a 2a 2a 20 6d 61 74 63 68 20 74 68 61 6e 20 61  .** match than a
30600 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20   function where 
30610 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20  the encoding is 
30620 64 69 66 66 65 72 65 6e 74 2e 20 20 0a 2a 2a 20  different.  .** 
30630 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72  ^A function wher
30640 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64  e the encoding d
30650 69 66 66 65 72 65 6e 63 65 20 69 73 20 62 65 74  ifference is bet
30660 77 65 65 6e 20 55 54 46 31 36 6c 65 20 61 6e 64  ween UTF16le and
30670 20 55 54 46 31 36 62 65 0a 2a 2a 20 69 73 20 61   UTF16be.** is a
30680 20 63 6c 6f 73 65 72 20 6d 61 74 63 68 20 74 68   closer match th
30690 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68  an a function wh
306a0 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67  ere the encoding
306b0 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 0a 2a   difference is.*
306c0 2a 20 62 65 74 77 65 65 6e 20 55 54 46 38 20 61  * between UTF8 a
306d0 6e 64 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20  nd UTF16..**.** 
306e0 5e 42 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74 69  ^Built-in functi
306f0 6f 6e 73 20 6d 61 79 20 62 65 20 6f 76 65 72 6c  ons may be overl
30700 6f 61 64 65 64 20 62 79 20 6e 65 77 20 61 70 70  oaded by new app
30710 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
30720 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a   functions..**.*
30730 2a 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 69 6f  * ^An applicatio
30740 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
30750 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 20  on is permitted 
30760 74 6f 20 63 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a  to call other.**
30770 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
30780 65 73 2e 20 20 48 6f 77 65 76 65 72 2c 20 73 75  es.  However, su
30790 63 68 20 63 61 6c 6c 73 20 6d 75 73 74 20 6e 6f  ch calls must no
307a0 74 0a 2a 2a 20 63 6c 6f 73 65 20 74 68 65 20 64  t.** close the d
307b0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
307c0 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c 69 7a 65 20  on nor finalize 
307d0 6f 72 20 72 65 73 65 74 20 74 68 65 20 70 72 65  or reset the pre
307e0 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65  pared.** stateme
307f0 6e 74 20 69 6e 20 77 68 69 63 68 20 74 68 65 20  nt in which the 
30800 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e  function is runn
30810 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ing..*/.SQLITE_A
30820 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  PI int sqlite3_c
30830 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 0a  reate_function(.
30840 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20    sqlite3 *db,. 
30850 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75   const char *zFu
30860 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e  nctionName,.  in
30870 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54  t nArg,.  int eT
30880 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a  extRep,.  void *
30890 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78  pApp,.  void (*x
308a0 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f  Func)(sqlite3_co
308b0 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
308c0 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
308d0 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c  oid (*xStep)(sql
308e0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
308f0 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
30900 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69  *),.  void (*xFi
30910 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  nal)(sqlite3_con
30920 74 65 78 74 2a 29 0a 29 3b 0a 53 51 4c 49 54 45  text*).);.SQLITE
30930 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
30940 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
30950 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  16(.  sqlite3 *d
30960 62 2c 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  b,.  const void 
30970 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a  *zFunctionName,.
30980 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e    int nArg,.  in
30990 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f  t eTextRep,.  vo
309a0 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64  id *pApp,.  void
309b0 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65   (*xFunc)(sqlite
309c0 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
309d0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
309e0 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29  .  void (*xStep)
309f0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
30a00 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
30a10 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
30a20 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33  *xFinal)(sqlite3
30a30 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 53 51  _context*).);.SQ
30a40 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
30a50 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
30a60 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74  tion_v2(.  sqlit
30a70 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20  e3 *db,.  const 
30a80 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e  char *zFunctionN
30a90 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c  ame,.  int nArg,
30aa0 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c  .  int eTextRep,
30ab0 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20  .  void *pApp,. 
30ac0 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73   void (*xFunc)(s
30ad0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
30ae0 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
30af0 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
30b00 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f  Step)(sqlite3_co
30b10 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
30b20 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
30b30 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71  oid (*xFinal)(sq
30b40 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 2c  lite3_context*),
30b50 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f  .  void(*xDestro
30b60 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a  y)(void*).);../*
30b70 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65  .** CAPI3REF: Te
30b80 78 74 20 45 6e 63 6f 64 69 6e 67 73 0a 2a 2a 0a  xt Encodings.**.
30b90 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
30ba0 74 20 64 65 66 69 6e 65 20 69 6e 74 65 67 65 72  t define integer
30bb0 20 63 6f 64 65 73 20 74 68 61 74 20 72 65 70 72   codes that repr
30bc0 65 73 65 6e 74 20 74 68 65 20 76 61 72 69 6f 75  esent the variou
30bd0 73 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64 69  s.** text encodi
30be0 6e 67 73 20 73 75 70 70 6f 72 74 65 64 20 62 79  ngs supported by
30bf0 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66   SQLite..*/.#def
30c00 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 38 20  ine SQLITE_UTF8 
30c10 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66            1.#def
30c20 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36  ine SQLITE_UTF16
30c30 4c 45 20 20 20 20 20 20 20 20 32 0a 23 64 65 66  LE        2.#def
30c40 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36  ine SQLITE_UTF16
30c50 42 45 20 20 20 20 20 20 20 20 33 0a 23 64 65 66  BE        3.#def
30c60 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36  ine SQLITE_UTF16
30c70 20 20 20 20 20 20 20 20 20 20 34 20 20 20 20 2f            4    /
30c80 2a 20 55 73 65 20 6e 61 74 69 76 65 20 62 79 74  * Use native byt
30c90 65 20 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66 69  e order */.#defi
30ca0 6e 65 20 53 51 4c 49 54 45 5f 41 4e 59 20 20 20  ne SQLITE_ANY   
30cb0 20 20 20 20 20 20 20 20 20 35 20 20 20 20 2f 2a           5    /*
30cc0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
30cd0 66 75 6e 63 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f  function only */
30ce0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
30cf0 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 20 20 38  UTF16_ALIGNED  8
30d00 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63      /* sqlite3_c
30d10 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20  reate_collation 
30d20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  only */../*.** C
30d30 41 50 49 33 52 45 46 3a 20 44 65 70 72 65 63 61  API3REF: Depreca
30d40 74 65 64 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  ted Functions.**
30d50 20 44 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a   DEPRECATED.**.*
30d60 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  * These function
30d70 73 20 61 72 65 20 5b 64 65 70 72 65 63 61 74 65  s are [deprecate
30d80 64 5d 2e 20 20 49 6e 20 6f 72 64 65 72 20 74 6f  d].  In order to
30d90 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63   maintain.** bac
30da0 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
30db0 6c 69 74 79 20 77 69 74 68 20 6f 6c 64 65 72 20  lity with older 
30dc0 63 6f 64 65 2c 20 74 68 65 73 65 20 66 75 6e 63  code, these func
30dd0 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 0a  tions continue .
30de0 2a 2a 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74  ** to be support
30df0 65 64 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e 65  ed.  However, ne
30e00 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 73  w applications s
30e10 68 6f 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74  hould avoid.** t
30e20 68 65 20 75 73 65 20 6f 66 20 74 68 65 73 65 20  he use of these 
30e30 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20 68  functions.  To h
30e40 65 6c 70 20 65 6e 63 6f 75 72 61 67 65 20 70 65  elp encourage pe
30e50 6f 70 6c 65 20 74 6f 20 61 76 6f 69 64 0a 2a 2a  ople to avoid.**
30e60 20 75 73 69 6e 67 20 74 68 65 73 65 20 66 75 6e   using these fun
30e70 63 74 69 6f 6e 73 2c 20 77 65 20 61 72 65 20 6e  ctions, we are n
30e80 6f 74 20 67 6f 69 6e 67 20 74 6f 20 74 65 6c 6c  ot going to tell
30e90 20 79 6f 75 20 77 68 61 74 20 74 68 65 79 20 64   you what they d
30ea0 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51  o..*/.#ifndef SQ
30eb0 4c 49 54 45 5f 4f 4d 49 54 5f 44 45 50 52 45 43  LITE_OMIT_DEPREC
30ec0 41 54 45 44 0a 53 51 4c 49 54 45 5f 41 50 49 20  ATED.SQLITE_API 
30ed0 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
30ee0 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 61 67  D int sqlite3_ag
30ef0 67 72 65 67 61 74 65 5f 63 6f 75 6e 74 28 73 71  gregate_count(sq
30f00 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
30f10 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49  .SQLITE_API SQLI
30f20 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e  TE_DEPRECATED in
30f30 74 20 73 71 6c 69 74 65 33 5f 65 78 70 69 72 65  t sqlite3_expire
30f40 64 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  d(sqlite3_stmt*)
30f50 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c  ;.SQLITE_API SQL
30f60 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69  ITE_DEPRECATED i
30f70 6e 74 20 73 71 6c 69 74 65 33 5f 74 72 61 6e 73  nt sqlite3_trans
30f80 66 65 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c  fer_bindings(sql
30f90 69 74 65 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69  ite3_stmt*, sqli
30fa0 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49  te3_stmt*);.SQLI
30fb0 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45  TE_API SQLITE_DE
30fc0 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c  PRECATED int sql
30fd0 69 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f  ite3_global_reco
30fe0 76 65 72 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54  ver(void);.SQLIT
30ff0 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50  E_API SQLITE_DEP
31000 52 45 43 41 54 45 44 20 76 6f 69 64 20 73 71 6c  RECATED void sql
31010 69 74 65 33 5f 74 68 72 65 61 64 5f 63 6c 65 61  ite3_thread_clea
31020 6e 75 70 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54  nup(void);.SQLIT
31030 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50  E_API SQLITE_DEP
31040 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69  RECATED int sqli
31050 74 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d  te3_memory_alarm
31060 28 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73  (void(*)(void*,s
31070 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c 69 6e 74  qlite3_int64,int
31080 29 2c 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f  ),void*,sqlite3_
31090 69 6e 74 36 34 29 3b 0a 23 65 6e 64 69 66 0a 0a  int64);.#endif..
310a0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
310b0 4f 62 74 61 69 6e 69 6e 67 20 53 51 4c 20 46 75  Obtaining SQL Fu
310c0 6e 63 74 69 6f 6e 20 50 61 72 61 6d 65 74 65 72  nction Parameter
310d0 20 56 61 6c 75 65 73 0a 2a 2a 0a 2a 2a 20 54 68   Values.**.** Th
310e0 65 20 43 2d 6c 61 6e 67 75 61 67 65 20 69 6d 70  e C-language imp
310f0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 53  lementation of S
31100 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64  QL functions and
31110 20 61 67 67 72 65 67 61 74 65 73 20 75 73 65 73   aggregates uses
31120 0a 2a 2a 20 74 68 69 73 20 73 65 74 20 6f 66 20  .** this set of 
31130 69 6e 74 65 72 66 61 63 65 20 72 6f 75 74 69 6e  interface routin
31140 65 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65  es to access the
31150 20 70 61 72 61 6d 65 74 65 72 20 76 61 6c 75 65   parameter value
31160 73 20 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 6e 63  s on.** the func
31170 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74  tion or aggregat
31180 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 75  e..**.** The xFu
31190 6e 63 20 28 66 6f 72 20 73 63 61 6c 61 72 20 66  nc (for scalar f
311a0 75 6e 63 74 69 6f 6e 73 29 20 6f 72 20 78 53 74  unctions) or xSt
311b0 65 70 20 28 66 6f 72 20 61 67 67 72 65 67 61 74  ep (for aggregat
311c0 65 73 29 20 70 61 72 61 6d 65 74 65 72 73 0a 2a  es) parameters.*
311d0 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72  * to [sqlite3_cr
311e0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
311f0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72   and [sqlite3_cr
31200 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
31210 29 5d 0a 2a 2a 20 64 65 66 69 6e 65 20 63 61 6c  )].** define cal
31220 6c 62 61 63 6b 73 20 74 68 61 74 20 69 6d 70 6c  lbacks that impl
31230 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75  ement the SQL fu
31240 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72  nctions and aggr
31250 65 67 61 74 65 73 2e 0a 2a 2a 20 54 68 65 20 33  egates..** The 3
31260 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
31270 74 68 65 73 65 20 63 61 6c 6c 62 61 63 6b 73 20  these callbacks 
31280 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  is an array of p
31290 6f 69 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 5b 70  ointers to.** [p
312a0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
312b0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e  _value] objects.
312c0 20 20 54 68 65 72 65 20 69 73 20 6f 6e 65 20 5b    There is one [
312d0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
312e0 62 6a 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63  bject for.** eac
312f0 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
31300 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e  he SQL function.
31310 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73    These routines
31320 20 61 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20   are used to.** 
31330 65 78 74 72 61 63 74 20 76 61 6c 75 65 73 20 66  extract values f
31340 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33  rom the [sqlite3
31350 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e  _value] objects.
31360 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
31370 74 69 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 20  tines work only 
31380 77 69 74 68 20 5b 70 72 6f 74 65 63 74 65 64 20  with [protected 
31390 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
313a0 62 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 61  bjects..** Any a
313b0 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68  ttempt to use th
313c0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 20  ese routines on 
313d0 61 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  an [unprotected 
313e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a  sqlite3_value].*
313f0 2a 20 6f 62 6a 65 63 74 20 72 65 73 75 6c 74 73  * object results
31400 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65   in undefined be
31410 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  havior..**.** ^T
31420 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f  hese routines wo
31430 72 6b 20 6a 75 73 74 20 6c 69 6b 65 20 74 68 65  rk just like the
31440 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 5b   corresponding [
31450 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75  column access fu
31460 6e 63 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65  nctions].** exce
31470 70 74 20 74 68 61 74 20 20 74 68 65 73 65 20 72  pt that  these r
31480 6f 75 74 69 6e 65 73 20 74 61 6b 65 20 61 20 73  outines take a s
31490 69 6e 67 6c 65 20 5b 70 72 6f 74 65 63 74 65 64  ingle [protected
314a0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
314b0 6f 62 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e 74 65  object.** pointe
314c0 72 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 5b  r instead of a [
314d0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20 70  sqlite3_stmt*] p
314e0 6f 69 6e 74 65 72 20 61 6e 64 20 61 6e 20 69 6e  ointer and an in
314f0 74 65 67 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d  teger column num
31500 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ber..**.** ^The 
31510 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
31520 78 74 31 36 28 29 20 69 6e 74 65 72 66 61 63 65  xt16() interface
31530 20 65 78 74 72 61 63 74 73 20 61 20 55 54 46 2d   extracts a UTF-
31540 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69 6e 20  16 string.** in 
31550 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 2d  the native byte-
31560 6f 72 64 65 72 20 6f 66 20 74 68 65 20 68 6f 73  order of the hos
31570 74 20 6d 61 63 68 69 6e 65 2e 20 20 5e 54 68 65  t machine.  ^The
31580 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
31590 65 5f 74 65 78 74 31 36 62 65 28 29 20 61 6e 64  e_text16be() and
315a0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
315b0 65 78 74 31 36 6c 65 28 29 20 69 6e 74 65 72 66  ext16le() interf
315c0 61 63 65 73 0a 2a 2a 20 65 78 74 72 61 63 74 20  aces.** extract 
315d0 55 54 46 2d 31 36 20 73 74 72 69 6e 67 73 20 61  UTF-16 strings a
315e0 73 20 62 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64  s big-endian and
315f0 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72   little-endian r
31600 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a  espectively..**.
31610 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33  ** ^(The sqlite3
31620 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74  _value_numeric_t
31630 79 70 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  ype() interface 
31640 61 74 74 65 6d 70 74 73 20 74 6f 20 61 70 70 6c  attempts to appl
31650 79 0a 2a 2a 20 6e 75 6d 65 72 69 63 20 61 66 66  y.** numeric aff
31660 69 6e 69 74 79 20 74 6f 20 74 68 65 20 76 61 6c  inity to the val
31670 75 65 2e 20 20 54 68 69 73 20 6d 65 61 6e 73 20  ue.  This means 
31680 74 68 61 74 20 61 6e 20 61 74 74 65 6d 70 74 20  that an attempt 
31690 69 73 0a 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f  is.** made to co
316a0 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75 65 20  nvert the value 
316b0 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 6f 72  to an integer or
316c0 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e   floating point.
316d0 20 20 49 66 0a 2a 2a 20 73 75 63 68 20 61 20 63    If.** such a c
316e0 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 6f 73  onversion is pos
316f0 73 69 62 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f  sible without lo
31700 73 73 20 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f  ss of informatio
31710 6e 20 28 69 6e 20 6f 74 68 65 72 0a 2a 2a 20 77  n (in other.** w
31720 6f 72 64 73 2c 20 69 66 20 74 68 65 20 76 61 6c  ords, if the val
31730 75 65 20 69 73 20 61 20 73 74 72 69 6e 67 20 74  ue is a string t
31740 68 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61  hat looks like a
31750 20 6e 75 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e   number).** then
31760 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20   the conversion 
31770 69 73 20 70 65 72 66 6f 72 6d 65 64 2e 20 20 4f  is performed.  O
31780 74 68 65 72 77 69 73 65 20 6e 6f 20 63 6f 6e 76  therwise no conv
31790 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a  ersion occurs..*
317a0 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 4e  * The [SQLITE_IN
317b0 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65  TEGER | datatype
317c0 5d 20 61 66 74 65 72 20 63 6f 6e 76 65 72 73 69  ] after conversi
317d0 6f 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29  on is returned.)
317e0 5e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 70  ^.**.** Please p
317f0 61 79 20 70 61 72 74 69 63 75 6c 61 72 20 61 74  ay particular at
31800 74 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65 20 66  tention to the f
31810 61 63 74 20 74 68 61 74 20 74 68 65 20 70 6f 69  act that the poi
31820 6e 74 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a  nter returned.**
31830 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76   from [sqlite3_v
31840 61 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73  alue_blob()], [s
31850 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
31860 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c  t()], or.** [sql
31870 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
31880 36 28 29 5d 20 63 61 6e 20 62 65 20 69 6e 76 61  6()] can be inva
31890 6c 69 64 61 74 65 64 20 62 79 20 61 20 73 75 62  lidated by a sub
318a0 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 0a  sequent call to.
318b0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ** [sqlite3_valu
318c0 65 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73 71 6c  e_bytes()], [sql
318d0 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
318e0 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  16()], [sqlite3_
318f0 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a  value_text()],.*
31900 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61  * or [sqlite3_va
31910 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 2e 0a 2a  lue_text16()]..*
31920 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
31930 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  nes must be call
31940 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65  ed from the same
31950 20 74 68 72 65 61 64 20 61 73 0a 2a 2a 20 74 68   thread as.** th
31960 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74  e SQL function t
31970 68 61 74 20 73 75 70 70 6c 69 65 64 20 74 68 65  hat supplied the
31980 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a   [sqlite3_value*
31990 5d 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2f  ] parameters..*/
319a0 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
319b0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
319c0 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 69 74  value_blob(sqlit
319d0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49  e3_value*);.SQLI
319e0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
319f0 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 73  e3_value_bytes(s
31a00 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
31a10 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
31a20 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
31a30 65 73 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c  es16(sqlite3_val
31a40 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  ue*);.SQLITE_API
31a50 20 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f   double sqlite3_
31a60 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73 71 6c  value_double(sql
31a70 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51  ite3_value*);.SQ
31a80 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
31a90 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 73  ite3_value_int(s
31aa0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
31ab0 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74  SQLITE_API sqlit
31ac0 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
31ad0 5f 76 61 6c 75 65 5f 69 6e 74 36 34 28 73 71 6c  _value_int64(sql
31ae0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51  ite3_value*);.SQ
31af0 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 75  LITE_API const u
31b00 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71  nsigned char *sq
31b10 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
31b20 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
31b30 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  ;.SQLITE_API con
31b40 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
31b50 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 73 71  _value_text16(sq
31b60 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53  lite3_value*);.S
31b70 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
31b80 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61  void *sqlite3_va
31b90 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 73 71 6c  lue_text16le(sql
31ba0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51  ite3_value*);.SQ
31bb0 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76  LITE_API const v
31bc0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c  oid *sqlite3_val
31bd0 75 65 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69  ue_text16be(sqli
31be0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c  te3_value*);.SQL
31bf0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
31c00 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 73  te3_value_type(s
31c10 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
31c20 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
31c30 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d  qlite3_value_num
31c40 65 72 69 63 5f 74 79 70 65 28 73 71 6c 69 74 65  eric_type(sqlite
31c50 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a  3_value*);../*.*
31c60 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61  * CAPI3REF: Obta
31c70 69 6e 20 41 67 67 72 65 67 61 74 65 20 46 75 6e  in Aggregate Fun
31c80 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 0a 2a 2a  ction Context.**
31c90 0a 2a 2a 20 49 6d 70 6c 65 6d 65 6e 74 61 74 69  .** Implementati
31ca0 6f 6e 73 20 6f 66 20 61 67 67 72 65 67 61 74 65  ons of aggregate
31cb0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 75   SQL functions u
31cc0 73 65 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69  se this.** routi
31cd0 6e 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d  ne to allocate m
31ce0 65 6d 6f 72 79 20 66 6f 72 20 73 74 6f 72 69 6e  emory for storin
31cf0 67 20 74 68 65 69 72 20 73 74 61 74 65 2e 0a 2a  g their state..*
31d00 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
31d10 74 69 6d 65 20 74 68 65 20 73 71 6c 69 74 65 33  time the sqlite3
31d20 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
31d30 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20  xt(C,N) routine 
31d40 69 73 20 63 61 6c 6c 65 64 20 0a 2a 2a 20 66 6f  is called .** fo
31d50 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 61  r a particular a
31d60 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f  ggregate functio
31d70 6e 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6c 6c  n, SQLite.** all
31d80 6f 63 61 74 65 73 20 4e 20 6f 66 20 6d 65 6d 6f  ocates N of memo
31d90 72 79 2c 20 7a 65 72 6f 65 73 20 6f 75 74 20 74  ry, zeroes out t
31da0 68 61 74 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 20  hat memory, and 
31db0 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
31dc0 72 0a 2a 2a 20 74 6f 20 74 68 65 20 6e 65 77 20  r.** to the new 
31dd0 6d 65 6d 6f 72 79 2e 20 5e 4f 6e 20 73 65 63 6f  memory. ^On seco
31de0 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e  nd and subsequen
31df0 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71  t calls to.** sq
31e00 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
31e10 63 6f 6e 74 65 78 74 28 29 20 66 6f 72 20 74 68  context() for th
31e20 65 20 73 61 6d 65 20 61 67 67 72 65 67 61 74 65  e same aggregate
31e30 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e   function instan
31e40 63 65 2c 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20  ce,.** the same 
31e50 62 75 66 66 65 72 20 69 73 20 72 65 74 75 72 6e  buffer is return
31e60 65 64 2e 20 20 53 71 6c 69 74 65 33 5f 61 67 67  ed.  Sqlite3_agg
31e70 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29  regate_context()
31e80 20 69 73 20 6e 6f 72 6d 61 6c 6c 79 0a 2a 2a 20   is normally.** 
31e90 63 61 6c 6c 65 64 20 6f 6e 63 65 20 66 6f 72 20  called once for 
31ea0 65 61 63 68 20 69 6e 76 6f 63 61 74 69 6f 6e 20  each invocation 
31eb0 6f 66 20 74 68 65 20 78 53 74 65 70 20 63 61 6c  of the xStep cal
31ec0 6c 62 61 63 6b 20 61 6e 64 20 74 68 65 6e 20 6f  lback and then o
31ed0 6e 65 0a 2a 2a 20 6c 61 73 74 20 74 69 6d 65 20  ne.** last time 
31ee0 77 68 65 6e 20 74 68 65 20 78 46 69 6e 61 6c 20  when the xFinal 
31ef0 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
31f00 6b 65 64 2e 20 20 5e 28 57 68 65 6e 20 6e 6f 20  ked.  ^(When no 
31f10 72 6f 77 73 20 6d 61 74 63 68 0a 2a 2a 20 61 6e  rows match.** an
31f20 20 61 67 67 72 65 67 61 74 65 20 71 75 65 72 79   aggregate query
31f30 2c 20 74 68 65 20 78 53 74 65 70 28 29 20 63 61  , the xStep() ca
31f40 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 61 67  llback of the ag
31f50 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e  gregate function
31f60 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
31f70 6f 6e 20 69 73 20 6e 65 76 65 72 20 63 61 6c 6c  on is never call
31f80 65 64 20 61 6e 64 20 78 46 69 6e 61 6c 28 29 20  ed and xFinal() 
31f90 69 73 20 63 61 6c 6c 65 64 20 65 78 61 63 74 6c  is called exactl
31fa0 79 20 6f 6e 63 65 2e 0a 2a 2a 20 49 6e 20 74 68  y once..** In th
31fb0 6f 73 65 20 63 61 73 65 73 2c 20 73 71 6c 69 74  ose cases, sqlit
31fc0 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
31fd0 74 65 78 74 28 29 20 6d 69 67 68 74 20 62 65 20  text() might be 
31fe0 63 61 6c 6c 65 64 20 66 6f 72 20 74 68 65 0a 2a  called for the.*
31ff0 2a 20 66 69 72 73 74 20 74 69 6d 65 20 66 72 6f  * first time fro
32000 6d 20 77 69 74 68 69 6e 20 78 46 69 6e 61 6c 28  m within xFinal(
32010 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ).)^.**.** ^The 
32020 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
32030 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72  e_context(C,N) r
32040 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61  outine returns a
32050 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66   NULL pointer if
32060 20 4e 20 69 73 0a 2a 2a 20 6c 65 73 73 20 74 68   N is.** less th
32070 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a  an or equal to z
32080 65 72 6f 20 6f 72 20 69 66 20 61 20 6d 65 6d 6f  ero or if a memo
32090 72 79 20 61 6c 6c 6f 63 61 74 65 20 65 72 72 6f  ry allocate erro
320a0 72 20 6f 63 63 75 72 73 2e 0a 2a 2a 0a 2a 2a 20  r occurs..**.** 
320b0 5e 28 54 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20  ^(The amount of 
320c0 73 70 61 63 65 20 61 6c 6c 6f 63 61 74 65 64 20  space allocated 
320d0 62 79 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  by sqlite3_aggre
320e0 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e  gate_context(C,N
320f0 29 20 69 73 0a 2a 2a 20 64 65 74 65 72 6d 69 6e  ) is.** determin
32100 65 64 20 62 79 20 74 68 65 20 4e 20 70 61 72 61  ed by the N para
32110 6d 65 74 65 72 20 6f 6e 20 66 69 72 73 74 20 73  meter on first s
32120 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 2e 20  uccessful call. 
32130 20 43 68 61 6e 67 69 6e 67 20 74 68 65 0a 2a 2a   Changing the.**
32140 20 76 61 6c 75 65 20 6f 66 20 4e 20 69 6e 20 73   value of N in s
32150 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74  ubsequent call t
32160 6f 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  o sqlite3_aggreg
32170 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 77 69  ate_context() wi
32180 74 68 69 6e 0a 2a 2a 20 74 68 65 20 73 61 6d 65  thin.** the same
32190 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74   aggregate funct
321a0 69 6f 6e 20 69 6e 73 74 61 6e 63 65 20 77 69 6c  ion instance wil
321b0 6c 20 6e 6f 74 20 72 65 73 69 7a 65 20 74 68 65  l not resize the
321c0 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63   memory.** alloc
321d0 61 74 69 6f 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  ation.)^.**.** ^
321e0 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 63  SQLite automatic
321f0 61 6c 6c 79 20 66 72 65 65 73 20 74 68 65 20 6d  ally frees the m
32200 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65 64 20  emory allocated 
32210 62 79 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61  by .** sqlite3_a
32220 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
32230 28 29 20 77 68 65 6e 20 74 68 65 20 61 67 67 72  () when the aggr
32240 65 67 61 74 65 20 71 75 65 72 79 20 63 6f 6e 63  egate query conc
32250 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ludes..**.** The
32260 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
32270 20 6d 75 73 74 20 62 65 20 61 20 63 6f 70 79 20   must be a copy 
32280 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  of the.** [sqlit
32290 65 33 5f 63 6f 6e 74 65 78 74 20 7c 20 53 51 4c  e3_context | SQL
322a0 20 66 75 6e 63 74 69 6f 6e 20 63 6f 6e 74 65 78   function contex
322b0 74 5d 20 74 68 61 74 20 69 73 20 74 68 65 20 66  t] that is the f
322c0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 0a 2a  irst parameter.*
322d0 2a 20 74 6f 20 74 68 65 20 78 53 74 65 70 20 6f  * to the xStep o
322e0 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63  r xFinal callbac
322f0 6b 20 72 6f 75 74 69 6e 65 20 74 68 61 74 20 69  k routine that i
32300 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 61 67  mplements the ag
32310 67 72 65 67 61 74 65 0a 2a 2a 20 66 75 6e 63 74  gregate.** funct
32320 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ion..**.** This 
32330 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20  routine must be 
32340 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20  called from the 
32350 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77  same thread in w
32360 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 67 67 72  hich.** the aggr
32370 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69  egate SQL functi
32380 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  on is running..*
32390 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  /.SQLITE_API voi
323a0 64 20 2a 73 71 6c 69 74 65 33 5f 61 67 67 72 65  d *sqlite3_aggre
323b0 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c  gate_context(sql
323c0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
323d0 6e 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a  nt nBytes);../*.
323e0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 55 73 65  ** CAPI3REF: Use
323f0 72 20 44 61 74 61 20 46 6f 72 20 46 75 6e 63 74  r Data For Funct
32400 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ions.**.** ^The 
32410 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74  sqlite3_user_dat
32420 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  a() interface re
32430 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a  turns a copy of.
32440 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74  ** the pointer t
32450 68 61 74 20 77 61 73 20 74 68 65 20 70 55 73 65  hat was the pUse
32460 72 44 61 74 61 20 70 61 72 61 6d 65 74 65 72 20  rData parameter 
32470 28 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74  (the 5th paramet
32480 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73  er).** of the [s
32490 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
324a0 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64  nction()].** and
324b0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
324c0 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72  _function16()] r
324d0 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69  outines that ori
324e0 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73  ginally.** regis
324f0 74 65 72 65 64 20 74 68 65 20 61 70 70 6c 69 63  tered the applic
32500 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75  ation defined fu
32510 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68  nction..**.** Th
32520 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20  is routine must 
32530 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74  be called from t
32540 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69  he same thread i
32550 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61  n which.** the a
32560 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
32570 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  ed function is r
32580 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54  unning..*/.SQLIT
32590 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69  E_API void *sqli
325a0 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 73 71  te3_user_data(sq
325b0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
325c0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
325d0 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65  : Database Conne
325e0 63 74 69 6f 6e 20 46 6f 72 20 46 75 6e 63 74 69  ction For Functi
325f0 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ons.**.** ^The s
32600 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64  qlite3_context_d
32610 62 5f 68 61 6e 64 6c 65 28 29 20 69 6e 74 65 72  b_handle() inter
32620 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 63  face returns a c
32630 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f  opy of.** the po
32640 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 64 61  inter to the [da
32650 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
32660 6e 5d 20 28 74 68 65 20 31 73 74 20 70 61 72 61  n] (the 1st para
32670 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65  meter).** of the
32680 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
32690 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20  _function()].** 
326a0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  and [sqlite3_cre
326b0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
326c0 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20  ] routines that 
326d0 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65  originally.** re
326e0 67 69 73 74 65 72 65 64 20 74 68 65 20 61 70 70  gistered the app
326f0 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64  lication defined
32700 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2f 0a 53 51   function..*/.SQ
32710 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33  LITE_API sqlite3
32720 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78   *sqlite3_contex
32730 74 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69  t_db_handle(sqli
32740 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a  te3_context*);..
32750 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
32760 46 75 6e 63 74 69 6f 6e 20 41 75 78 69 6c 69 61  Function Auxilia
32770 72 79 20 44 61 74 61 0a 2a 2a 0a 2a 2a 20 54 68  ry Data.**.** Th
32780 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 77 6f 20  e following two 
32790 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65  functions may be
327a0 20 75 73 65 64 20 62 79 20 73 63 61 6c 61 72 20   used by scalar 
327b0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f  SQL functions to
327c0 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 20 6d 65  .** associate me
327d0 74 61 64 61 74 61 20 77 69 74 68 20 61 72 67 75  tadata with argu
327e0 6d 65 6e 74 20 76 61 6c 75 65 73 2e 20 49 66 20  ment values. If 
327f0 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65 20 69  the same value i
32800 73 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 6d  s passed to.** m
32810 75 6c 74 69 70 6c 65 20 69 6e 76 6f 63 61 74 69  ultiple invocati
32820 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ons of the same 
32830 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 64 75 72  SQL function dur
32840 69 6e 67 20 71 75 65 72 79 20 65 78 65 63 75 74  ing query execut
32850 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a 20 73 6f  ion, under.** so
32860 6d 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73  me circumstances
32870 20 74 68 65 20 61 73 73 6f 63 69 61 74 65 64 20   the associated 
32880 6d 65 74 61 64 61 74 61 20 6d 61 79 20 62 65 20  metadata may be 
32890 70 72 65 73 65 72 76 65 64 2e 20 54 68 69 73 20  preserved. This 
328a0 6d 61 79 0a 2a 2a 20 62 65 20 75 73 65 64 2c 20  may.** be used, 
328b0 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 74 6f 20  for example, to 
328c0 61 64 64 20 61 20 72 65 67 75 6c 61 72 2d 65 78  add a regular-ex
328d0 70 72 65 73 73 69 6f 6e 20 6d 61 74 63 68 69 6e  pression matchin
328e0 67 20 73 63 61 6c 61 72 0a 2a 2a 20 66 75 6e 63  g scalar.** func
328f0 74 69 6f 6e 2e 20 54 68 65 20 63 6f 6d 70 69 6c  tion. The compil
32900 65 64 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68  ed version of th
32910 65 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73  e regular expres
32920 73 69 6f 6e 20 69 73 20 73 74 6f 72 65 64 20 61  sion is stored a
32930 73 0a 2a 2a 20 6d 65 74 61 64 61 74 61 20 61 73  s.** metadata as
32940 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
32950 65 20 53 51 4c 20 76 61 6c 75 65 20 70 61 73 73  e SQL value pass
32960 65 64 20 61 73 20 74 68 65 20 72 65 67 75 6c 61  ed as the regula
32970 72 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20  r expression.** 
32980 70 61 74 74 65 72 6e 2e 20 20 54 68 65 20 63 6f  pattern.  The co
32990 6d 70 69 6c 65 64 20 72 65 67 75 6c 61 72 20 65  mpiled regular e
329a0 78 70 72 65 73 73 69 6f 6e 20 63 61 6e 20 62 65  xpression can be
329b0 20 72 65 75 73 65 64 20 6f 6e 20 6d 75 6c 74 69   reused on multi
329c0 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f  ple.** invocatio
329d0 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66  ns of the same f
329e0 75 6e 63 74 69 6f 6e 20 73 6f 20 74 68 61 74 20  unction so that 
329f0 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 70 61 74  the original pat
32a00 74 65 72 6e 20 73 74 72 69 6e 67 0a 2a 2a 20 64  tern string.** d
32a10 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20  oes not need to 
32a20 62 65 20 72 65 63 6f 6d 70 69 6c 65 64 20 6f 6e  be recompiled on
32a30 20 65 61 63 68 20 69 6e 76 6f 63 61 74 69 6f 6e   each invocation
32a40 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
32a50 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
32a60 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  () interface ret
32a70 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
32a80 6f 20 74 68 65 20 6d 65 74 61 64 61 74 61 0a 2a  o the metadata.*
32a90 2a 20 61 73 73 6f 63 69 61 74 65 64 20 62 79 20  * associated by 
32aa0 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  the sqlite3_set_
32ab0 61 75 78 64 61 74 61 28 29 20 66 75 6e 63 74 69  auxdata() functi
32ac0 6f 6e 20 77 69 74 68 20 74 68 65 20 4e 74 68 20  on with the Nth 
32ad0 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 61 6c 75  argument.** valu
32ae0 65 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61  e to the applica
32af0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
32b00 63 74 69 6f 6e 2e 20 5e 49 66 20 6e 6f 20 6d 65  ction. ^If no me
32b10 74 61 64 61 74 61 20 68 61 73 20 62 65 65 6e 20  tadata has been 
32b20 65 76 65 72 0a 2a 2a 20 62 65 65 6e 20 73 65 74  ever.** been set
32b30 20 66 6f 72 20 74 68 65 20 4e 74 68 20 61 72 67   for the Nth arg
32b40 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 66 75 6e  ument of the fun
32b50 63 74 69 6f 6e 2c 20 6f 72 20 69 66 20 74 68 65  ction, or if the
32b60 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a   corresponding.*
32b70 2a 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d  * function param
32b80 65 74 65 72 20 68 61 73 20 63 68 61 6e 67 65 64  eter has changed
32b90 20 73 69 6e 63 65 20 74 68 65 20 6d 65 74 61 2d   since the meta-
32ba0 64 61 74 61 20 77 61 73 20 73 65 74 2c 0a 2a 2a  data was set,.**
32bb0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 67 65   then sqlite3_ge
32bc0 74 5f 61 75 78 64 61 74 61 28 29 20 72 65 74 75  t_auxdata() retu
32bd0 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  rns a NULL point
32be0 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  er..**.** ^The s
32bf0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
32c00 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  ta() interface s
32c10 61 76 65 73 20 74 68 65 20 6d 65 74 61 64 61 74  aves the metadat
32c20 61 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20  a.** pointed to 
32c30 62 79 20 69 74 73 20 33 72 64 20 70 61 72 61 6d  by its 3rd param
32c40 65 74 65 72 20 61 73 20 74 68 65 20 6d 65 74 61  eter as the meta
32c50 64 61 74 61 20 66 6f 72 20 74 68 65 20 4e 2d 74  data for the N-t
32c60 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6f 66  h.** argument of
32c70 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
32c80 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
32c90 6e 2e 20 20 53 75 62 73 65 71 75 65 6e 74 0a 2a  n.  Subsequent.*
32ca0 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  * calls to sqlit
32cb0 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29  e3_get_auxdata()
32cc0 20 6d 69 67 68 74 20 72 65 74 75 72 6e 20 74 68   might return th
32cd0 69 73 20 64 61 74 61 2c 20 69 66 20 69 74 20 68  is data, if it h
32ce0 61 73 0a 2a 2a 20 6e 6f 74 20 62 65 65 6e 20 64  as.** not been d
32cf0 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 20 5e 49 66  estroyed..** ^If
32d00 20 69 74 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c   it is not NULL,
32d10 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76   SQLite will inv
32d20 6f 6b 65 20 74 68 65 20 64 65 73 74 72 75 63 74  oke the destruct
32d30 6f 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 67  or.** function g
32d40 69 76 65 6e 20 62 79 20 74 68 65 20 34 74 68 20  iven by the 4th 
32d50 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
32d60 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
32d70 28 29 20 6f 6e 0a 2a 2a 20 74 68 65 20 6d 65 74  () on.** the met
32d80 61 64 61 74 61 20 77 68 65 6e 20 74 68 65 20 63  adata when the c
32d90 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 66 75 6e  orresponding fun
32da0 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20  ction parameter 
32db0 63 68 61 6e 67 65 73 0a 2a 2a 20 6f 72 20 77 68  changes.** or wh
32dc0 65 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  en the SQL state
32dd0 6d 65 6e 74 20 63 6f 6d 70 6c 65 74 65 73 2c 20  ment completes, 
32de0 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65 73 20  whichever comes 
32df0 66 69 72 73 74 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c  first..**.** SQL
32e00 69 74 65 20 69 73 20 66 72 65 65 20 74 6f 20 63  ite is free to c
32e10 61 6c 6c 20 74 68 65 20 64 65 73 74 72 75 63 74  all the destruct
32e20 6f 72 20 61 6e 64 20 64 72 6f 70 20 6d 65 74 61  or and drop meta
32e30 64 61 74 61 20 6f 6e 20 61 6e 79 0a 2a 2a 20 70  data on any.** p
32e40 61 72 61 6d 65 74 65 72 20 6f 66 20 61 6e 79 20  arameter of any 
32e50 66 75 6e 63 74 69 6f 6e 20 61 74 20 61 6e 79 20  function at any 
32e60 74 69 6d 65 2e 20 20 5e 54 68 65 20 6f 6e 6c 79  time.  ^The only
32e70 20 67 75 61 72 61 6e 74 65 65 20 69 73 20 74 68   guarantee is th
32e80 61 74 0a 2a 2a 20 74 68 65 20 64 65 73 74 72 75  at.** the destru
32e90 63 74 6f 72 20 77 69 6c 6c 20 62 65 20 63 61 6c  ctor will be cal
32ea0 6c 65 64 20 62 65 66 6f 72 65 20 74 68 65 20 6d  led before the m
32eb0 65 74 61 64 61 74 61 20 69 73 20 64 72 6f 70 70  etadata is dropp
32ec0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 70  ed..**.** ^(In p
32ed0 72 61 63 74 69 63 65 2c 20 6d 65 74 61 64 61 74  ractice, metadat
32ee0 61 20 69 73 20 70 72 65 73 65 72 76 65 64 20 62  a is preserved b
32ef0 65 74 77 65 65 6e 20 66 75 6e 63 74 69 6f 6e 20  etween function 
32f00 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20 65 78 70  calls for.** exp
32f10 72 65 73 73 69 6f 6e 73 20 74 68 61 74 20 61 72  ressions that ar
32f20 65 20 63 6f 6e 73 74 61 6e 74 20 61 74 20 63 6f  e constant at co
32f30 6d 70 69 6c 65 20 74 69 6d 65 2e 20 54 68 69 73  mpile time. This
32f40 20 69 6e 63 6c 75 64 65 73 20 6c 69 74 65 72 61   includes litera
32f50 6c 0a 2a 2a 20 76 61 6c 75 65 73 20 61 6e 64 20  l.** values and 
32f60 5b 70 61 72 61 6d 65 74 65 72 73 5d 2e 29 5e 0a  [parameters].)^.
32f70 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
32f80 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c  ines must be cal
32f90 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d  led from the sam
32fa0 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63  e thread in whic
32fb0 68 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e  h.** the SQL fun
32fc0 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67  ction is running
32fd0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
32fe0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 67 65  void *sqlite3_ge
32ff0 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74 65  t_auxdata(sqlite
33000 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20  3_context*, int 
33010 4e 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  N);.SQLITE_API v
33020 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  oid sqlite3_set_
33030 61 75 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f  auxdata(sqlite3_
33040 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 2c  context*, int N,
33050 20 76 6f 69 64 2a 2c 20 76 6f 69 64 20 28 2a 29   void*, void (*)
33060 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a  (void*));.../*.*
33070 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 73  * CAPI3REF: Cons
33080 74 61 6e 74 73 20 44 65 66 69 6e 69 6e 67 20 53  tants Defining S
33090 70 65 63 69 61 6c 20 44 65 73 74 72 75 63 74 6f  pecial Destructo
330a0 72 20 42 65 68 61 76 69 6f 72 0a 2a 2a 0a 2a 2a  r Behavior.**.**
330b0 20 54 68 65 73 65 20 61 72 65 20 73 70 65 63 69   These are speci
330c0 61 6c 20 76 61 6c 75 65 73 20 66 6f 72 20 74 68  al values for th
330d0 65 20 64 65 73 74 72 75 63 74 6f 72 20 74 68 61  e destructor tha
330e0 74 20 69 73 20 70 61 73 73 65 64 20 69 6e 20 61  t is passed in a
330f0 73 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 61  s the.** final a
33100 72 67 75 6d 65 6e 74 20 74 6f 20 72 6f 75 74 69  rgument to routi
33110 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65  nes like [sqlite
33120 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 5d  3_result_blob()]
33130 2e 20 20 5e 49 66 20 74 68 65 20 64 65 73 74 72  .  ^If the destr
33140 75 63 74 6f 72 0a 2a 2a 20 61 72 67 75 6d 65 6e  uctor.** argumen
33150 74 20 69 73 20 53 51 4c 49 54 45 5f 53 54 41 54  t is SQLITE_STAT
33160 49 43 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61  IC, it means tha
33170 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 70 6f  t the content po
33180 69 6e 74 65 72 20 69 73 20 63 6f 6e 73 74 61 6e  inter is constan
33190 74 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c 20 6e 65  t.** and will ne
331a0 76 65 72 20 63 68 61 6e 67 65 2e 20 20 49 74 20  ver change.  It 
331b0 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f  does not need to
331c0 20 62 65 20 64 65 73 74 72 6f 79 65 64 2e 20 20   be destroyed.  
331d0 5e 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 54  ^The.** SQLITE_T
331e0 52 41 4e 53 49 45 4e 54 20 76 61 6c 75 65 20 6d  RANSIENT value m
331f0 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f  eans that the co
33200 6e 74 65 6e 74 20 77 69 6c 6c 20 6c 69 6b 65 6c  ntent will likel
33210 79 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 74  y change in.** t
33220 68 65 20 6e 65 61 72 20 66 75 74 75 72 65 20 61  he near future a
33230 6e 64 20 74 68 61 74 20 53 51 4c 69 74 65 20 73  nd that SQLite s
33240 68 6f 75 6c 64 20 6d 61 6b 65 20 69 74 73 20 6f  hould make its o
33250 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20  wn private copy 
33260 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e  of.** the conten
33270 74 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69  t before returni
33280 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 79  ng..**.** The ty
33290 70 65 64 65 66 20 69 73 20 6e 65 63 65 73 73 61  pedef is necessa
332a0 72 79 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e  ry to work aroun
332b0 64 20 70 72 6f 62 6c 65 6d 73 20 69 6e 20 63 65  d problems in ce
332c0 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d  rtain.** C++ com
332d0 70 69 6c 65 72 73 2e 20 20 53 65 65 20 74 69 63  pilers.  See tic
332e0 6b 65 74 20 23 32 31 39 31 2e 0a 2a 2f 0a 74 79  ket #2191..*/.ty
332f0 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c  pedef void (*sql
33300 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f  ite3_destructor_
33310 74 79 70 65 29 28 76 6f 69 64 2a 29 3b 0a 23 64  type)(void*);.#d
33320 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41  efine SQLITE_STA
33330 54 49 43 20 20 20 20 20 20 28 28 73 71 6c 69 74  TIC      ((sqlit
33340 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79  e3_destructor_ty
33350 70 65 29 30 29 0a 23 64 65 66 69 6e 65 20 53 51  pe)0).#define SQ
33360 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 20  LITE_TRANSIENT  
33370 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72   ((sqlite3_destr
33380 75 63 74 6f 72 5f 74 79 70 65 29 2d 31 29 0a 0a  uctor_type)-1)..
33390 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
333a0 53 65 74 74 69 6e 67 20 54 68 65 20 52 65 73 75  Setting The Resu
333b0 6c 74 20 4f 66 20 41 6e 20 53 51 4c 20 46 75 6e  lt Of An SQL Fun
333c0 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ction.**.** Thes
333d0 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75  e routines are u
333e0 73 65 64 20 62 79 20 74 68 65 20 78 46 75 6e 63  sed by the xFunc
333f0 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62   or xFinal callb
33400 61 63 6b 73 20 74 68 61 74 0a 2a 2a 20 69 6d 70  acks that.** imp
33410 6c 65 6d 65 6e 74 20 53 51 4c 20 66 75 6e 63 74  lement SQL funct
33420 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61  ions and aggrega
33430 74 65 73 2e 20 20 53 65 65 0a 2a 2a 20 5b 73 71  tes.  See.** [sq
33440 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
33450 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71  ction()] and [sq
33460 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
33470 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 66 6f  ction16()].** fo
33480 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66  r additional inf
33490 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  ormation..**.** 
334a0 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  These functions 
334b0 77 6f 72 6b 20 76 65 72 79 20 6d 75 63 68 20 6c  work very much l
334c0 69 6b 65 20 74 68 65 20 5b 70 61 72 61 6d 65 74  ike the [paramet
334d0 65 72 20 62 69 6e 64 69 6e 67 5d 20 66 61 6d 69  er binding] fami
334e0 6c 79 20 6f 66 0a 2a 2a 20 66 75 6e 63 74 69 6f  ly of.** functio
334f0 6e 73 20 75 73 65 64 20 74 6f 20 62 69 6e 64 20  ns used to bind 
33500 76 61 6c 75 65 73 20 74 6f 20 68 6f 73 74 20 70  values to host p
33510 61 72 61 6d 65 74 65 72 73 20 69 6e 20 70 72 65  arameters in pre
33520 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
33530 2e 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 74 68  ..** Refer to th
33540 65 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72  e [SQL parameter
33550 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20  ] documentation 
33560 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69  for additional i
33570 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  nformation..**.*
33580 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
33590 65 73 75 6c 74 5f 62 6c 6f 62 28 29 20 69 6e 74  esult_blob() int
335a0 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20  erface sets the 
335b0 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61  result from.** a
335c0 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  n application-de
335d0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
335e0 6f 20 62 65 20 74 68 65 20 42 4c 4f 42 20 77 68  o be the BLOB wh
335f0 6f 73 65 20 63 6f 6e 74 65 6e 74 20 69 73 20 70  ose content is p
33600 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f 20 62 79 20  ointed.** to by 
33610 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
33620 65 74 65 72 20 61 6e 64 20 77 68 69 63 68 20 69  eter and which i
33630 73 20 4e 20 62 79 74 65 73 20 6c 6f 6e 67 20 77  s N bytes long w
33640 68 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a  here N is the.**
33650 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
33660 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
33670 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f  ite3_result_zero
33680 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 63 65  blob() interface
33690 73 20 73 65 74 20 74 68 65 20 72 65 73 75 6c 74  s set the result
336a0 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69   of.** the appli
336b0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
336c0 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20  unction to be a 
336d0 42 4c 4f 42 20 63 6f 6e 74 61 69 6e 69 6e 67 20  BLOB containing 
336e0 61 6c 6c 20 7a 65 72 6f 0a 2a 2a 20 62 79 74 65  all zero.** byte
336f0 73 20 61 6e 64 20 4e 20 62 79 74 65 73 20 69 6e  s and N bytes in
33700 20 73 69 7a 65 2c 20 77 68 65 72 65 20 4e 20 69   size, where N i
33710 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  s the value of t
33720 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
33730 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
33740 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62  ite3_result_doub
33750 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  le() interface s
33760 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 66  ets the result f
33770 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63  rom.** an applic
33780 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
33790 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 66  nction to be a f
337a0 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61  loating point va
337b0 6c 75 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a  lue specified.**
337c0 20 62 79 20 69 74 73 20 32 6e 64 20 61 72 67 75   by its 2nd argu
337d0 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ment..**.** ^The
337e0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
337f0 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69  error() and sqli
33800 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
33810 31 36 28 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a  16() functions.*
33820 2a 20 63 61 75 73 65 20 74 68 65 20 69 6d 70 6c  * cause the impl
33830 65 6d 65 6e 74 65 64 20 53 51 4c 20 66 75 6e 63  emented SQL func
33840 74 69 6f 6e 20 74 6f 20 74 68 72 6f 77 20 61 6e  tion to throw an
33850 20 65 78 63 65 70 74 69 6f 6e 2e 0a 2a 2a 20 5e   exception..** ^
33860 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20  SQLite uses the 
33870 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 64 20 74  string pointed t
33880 6f 20 62 79 20 74 68 65 0a 2a 2a 20 32 6e 64 20  o by the.** 2nd 
33890 70 61 72 61 6d 65 74 65 72 20 6f 66 20 73 71 6c  parameter of sql
338a0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
338b0 72 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  r() or sqlite3_r
338c0 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a  esult_error16().
338d0 2a 2a 20 61 73 20 74 68 65 20 74 65 78 74 20 6f  ** as the text o
338e0 66 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61  f an error messa
338f0 67 65 2e 20 20 5e 53 51 4c 69 74 65 20 69 6e 74  ge.  ^SQLite int
33900 65 72 70 72 65 74 73 20 74 68 65 20 65 72 72 6f  erprets the erro
33910 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 73 74 72  r.** message str
33920 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ing from sqlite3
33930 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20  _result_error() 
33940 61 73 20 55 54 46 2d 38 2e 20 5e 53 51 4c 69 74  as UTF-8. ^SQLit
33950 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 73 20  e.** interprets 
33960 74 68 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20  the string from 
33970 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
33980 72 72 6f 72 31 36 28 29 20 61 73 20 55 54 46 2d  rror16() as UTF-
33990 31 36 20 69 6e 20 6e 61 74 69 76 65 0a 2a 2a 20  16 in native.** 
339a0 62 79 74 65 20 6f 72 64 65 72 2e 20 20 5e 49 66  byte order.  ^If
339b0 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
339c0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
339d0 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a  result_error().*
339e0 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73  * or sqlite3_res
339f0 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69 73  ult_error16() is
33a00 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 53   negative then S
33a10 51 4c 69 74 65 20 74 61 6b 65 73 20 61 73 20 74  QLite takes as t
33a20 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73  he error.** mess
33a30 61 67 65 20 61 6c 6c 20 74 65 78 74 20 75 70 20  age all text up 
33a40 74 68 72 6f 75 67 68 20 74 68 65 20 66 69 72 73  through the firs
33a50 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72  t zero character
33a60 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74 68 69  ..** ^If the thi
33a70 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
33a80 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
33a90 72 72 6f 72 28 29 20 6f 72 0a 2a 2a 20 73 71 6c  rror() or.** sql
33aa0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
33ab0 72 31 36 28 29 20 69 73 20 6e 6f 6e 2d 6e 65 67  r16() is non-neg
33ac0 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74  ative then SQLit
33ad0 65 20 74 61 6b 65 73 20 74 68 61 74 20 6d 61 6e  e takes that man
33ae0 79 0a 2a 2a 20 62 79 74 65 73 20 28 6e 6f 74 20  y.** bytes (not 
33af0 63 68 61 72 61 63 74 65 72 73 29 20 66 72 6f 6d  characters) from
33b00 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
33b10 65 72 20 61 73 20 74 68 65 20 65 72 72 6f 72 20  er as the error 
33b20 6d 65 73 73 61 67 65 2e 0a 2a 2a 20 5e 54 68 65  message..** ^The
33b30 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
33b40 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69  error() and sqli
33b50 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
33b60 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  16().** routines
33b70 20 6d 61 6b 65 20 61 20 70 72 69 76 61 74 65 20   make a private 
33b80 63 6f 70 79 20 6f 66 20 74 68 65 20 65 72 72 6f  copy of the erro
33b90 72 20 6d 65 73 73 61 67 65 20 74 65 78 74 20 62  r message text b
33ba0 65 66 6f 72 65 0a 2a 2a 20 74 68 65 79 20 72 65  efore.** they re
33bb0 74 75 72 6e 2e 20 20 48 65 6e 63 65 2c 20 74 68  turn.  Hence, th
33bc0 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69  e calling functi
33bd0 6f 6e 20 63 61 6e 20 64 65 61 6c 6c 6f 63 61 74  on can deallocat
33be0 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66 79 20 74  e or.** modify t
33bf0 68 65 20 74 65 78 74 20 61 66 74 65 72 20 74 68  he text after th
33c00 65 79 20 72 65 74 75 72 6e 20 77 69 74 68 6f 75  ey return withou
33c10 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 54 68 65 20  t harm..** ^The 
33c20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
33c30 72 72 6f 72 5f 63 6f 64 65 28 29 20 66 75 6e 63  rror_code() func
33c40 74 69 6f 6e 20 63 68 61 6e 67 65 73 20 74 68 65  tion changes the
33c50 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 72   error code.** r
33c60 65 74 75 72 6e 65 64 20 62 79 20 53 51 4c 69 74  eturned by SQLit
33c70 65 20 61 73 20 61 20 72 65 73 75 6c 74 20 6f 66  e as a result of
33c80 20 61 6e 20 65 72 72 6f 72 20 69 6e 20 61 20 66   an error in a f
33c90 75 6e 63 74 69 6f 6e 2e 20 20 5e 42 79 20 64 65  unction.  ^By de
33ca0 66 61 75 6c 74 2c 0a 2a 2a 20 74 68 65 20 65 72  fault,.** the er
33cb0 72 6f 72 20 63 6f 64 65 20 69 73 20 53 51 4c 49  ror code is SQLI
33cc0 54 45 5f 45 52 52 4f 52 2e 20 20 5e 41 20 73 75  TE_ERROR.  ^A su
33cd0 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f  bsequent call to
33ce0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
33cf0 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71  error().** or sq
33d00 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
33d10 6f 72 31 36 28 29 20 72 65 73 65 74 73 20 74 68  or16() resets th
33d20 65 20 65 72 72 6f 72 20 63 6f 64 65 20 74 6f 20  e error code to 
33d30 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 0a 2a 2a  SQLITE_ERROR..**
33d40 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
33d50 5f 72 65 73 75 6c 74 5f 74 6f 6f 62 69 67 28 29  _result_toobig()
33d60 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65   interface cause
33d70 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f  s SQLite to thro
33d80 77 20 61 6e 20 65 72 72 6f 72 0a 2a 2a 20 69 6e  w an error.** in
33d90 64 69 63 61 74 69 6e 67 20 74 68 61 74 20 61 20  dicating that a 
33da0 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 69  string or BLOB i
33db0 73 20 74 6f 6f 20 6c 6f 6e 67 20 74 6f 20 72 65  s too long to re
33dc0 70 72 65 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e  present..**.** ^
33dd0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
33de0 6c 74 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74 65 72  lt_nomem() inter
33df0 66 61 63 65 20 63 61 75 73 65 73 20 53 51 4c 69  face causes SQLi
33e00 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65  te to throw an e
33e10 72 72 6f 72 0a 2a 2a 20 69 6e 64 69 63 61 74 69  rror.** indicati
33e20 6e 67 20 74 68 61 74 20 61 20 6d 65 6d 6f 72 79  ng that a memory
33e30 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c   allocation fail
33e40 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
33e50 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e  qlite3_result_in
33e60 74 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65  t() interface se
33e70 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  ts the return va
33e80 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70  lue.** of the ap
33e90 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
33ea0 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
33eb0 20 74 68 65 20 33 32 2d 62 69 74 20 73 69 67 6e   the 32-bit sign
33ec0 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61  ed integer.** va
33ed0 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65  lue given in the
33ee0 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a   2nd argument..*
33ef0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
33f00 65 73 75 6c 74 5f 69 6e 74 36 34 28 29 20 69 6e  esult_int64() in
33f10 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
33f20 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a   return value.**
33f30 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74   of the applicat
33f40 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
33f50 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 36  tion to be the 6
33f60 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74  4-bit signed int
33f70 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69  eger.** value gi
33f80 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61  ven in the 2nd a
33f90 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e  rgument..**.** ^
33fa0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
33fb0 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e 74 65 72 66  lt_null() interf
33fc0 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74  ace sets the ret
33fd0 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20  urn value.** of 
33fe0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
33ff0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
34000 20 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a   to be NULL..**.
34010 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
34020 72 65 73 75 6c 74 5f 74 65 78 74 28 29 2c 20 73  result_text(), s
34030 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
34040 78 74 31 36 28 29 2c 0a 2a 2a 20 73 71 6c 69 74  xt16(),.** sqlit
34050 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
34060 6c 65 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 65  le(), and sqlite
34070 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62  3_result_text16b
34080 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  e() interfaces.*
34090 2a 20 73 65 74 20 74 68 65 20 72 65 74 75 72 6e  * set the return
340a0 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 61 70   value of the ap
340b0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
340c0 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
340d0 0a 2a 2a 20 61 20 74 65 78 74 20 73 74 72 69 6e  .** a text strin
340e0 67 20 77 68 69 63 68 20 69 73 20 72 65 70 72 65  g which is repre
340f0 73 65 6e 74 65 64 20 61 73 20 55 54 46 2d 38 2c  sented as UTF-8,
34100 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62   UTF-16 native b
34110 79 74 65 20 6f 72 64 65 72 2c 0a 2a 2a 20 55 54  yte order,.** UT
34120 46 2d 31 36 20 6c 69 74 74 6c 65 20 65 6e 64 69  F-16 little endi
34130 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20 62 69  an, or UTF-16 bi
34140 67 20 65 6e 64 69 61 6e 2c 20 72 65 73 70 65 63  g endian, respec
34150 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 53 51 4c 69  tively..** ^SQLi
34160 74 65 20 74 61 6b 65 73 20 74 68 65 20 74 65 78  te takes the tex
34170 74 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 74 68  t result from th
34180 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 66 72  e application fr
34190 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e 64 20 70 61  om.** the 2nd pa
341a0 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65 20 73  rameter of the s
341b0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
341c0 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 2e 0a  xt* interfaces..
341d0 2a 2a 20 5e 49 66 20 74 68 65 20 33 72 64 20 70  ** ^If the 3rd p
341e0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
341f0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
34200 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a  ext* interfaces.
34210 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  ** is negative, 
34220 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65  then SQLite take
34230 73 20 72 65 73 75 6c 74 20 74 65 78 74 20 66 72  s result text fr
34240 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  om the 2nd param
34250 65 74 65 72 0a 2a 2a 20 74 68 72 6f 75 67 68 20  eter.** through 
34260 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63  the first zero c
34270 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 66  haracter..** ^If
34280 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74   the 3rd paramet
34290 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  er to the sqlite
342a0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69  3_result_text* i
342b0 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20  nterfaces.** is 
342c0 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68  non-negative, th
342d0 65 6e 20 61 73 20 6d 61 6e 79 20 62 79 74 65 73  en as many bytes
342e0 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73   (not characters
342f0 29 20 6f 66 20 74 68 65 20 74 65 78 74 0a 2a 2a  ) of the text.**
34300 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74   pointed to by t
34310 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
34320 20 61 72 65 20 74 61 6b 65 6e 20 61 73 20 74 68   are taken as th
34330 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
34340 66 69 6e 65 64 0a 2a 2a 20 66 75 6e 63 74 69 6f  fined.** functio
34350 6e 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66  n result..** ^If
34360 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74   the 4th paramet
34370 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  er to the sqlite
34380 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69  3_result_text* i
34390 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20  nterfaces.** or 
343a0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
343b0 6c 6f 62 20 69 73 20 61 20 6e 6f 6e 2d 4e 55 4c  lob is a non-NUL
343c0 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20  L pointer, then 
343d0 53 51 4c 69 74 65 20 63 61 6c 6c 73 20 74 68 61  SQLite calls tha
343e0 74 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 61 73  t.** function as
343f0 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   the destructor 
34400 6f 6e 20 74 68 65 20 74 65 78 74 20 6f 72 20 42  on the text or B
34410 4c 4f 42 20 72 65 73 75 6c 74 20 77 68 65 6e 20  LOB result when 
34420 69 74 20 68 61 73 0a 2a 2a 20 66 69 6e 69 73 68  it has.** finish
34430 65 64 20 75 73 69 6e 67 20 74 68 61 74 20 72 65  ed using that re
34440 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  sult..** ^If the
34450 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   4th parameter t
34460 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65  o the sqlite3_re
34470 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72  sult_text* inter
34480 66 61 63 65 73 20 6f 72 20 74 6f 0a 2a 2a 20 73  faces or to.** s
34490 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
344a0 6f 62 20 69 73 20 74 68 65 20 73 70 65 63 69 61  ob is the specia
344b0 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54  l constant SQLIT
344c0 45 5f 53 54 41 54 49 43 2c 20 74 68 65 6e 20 53  E_STATIC, then S
344d0 51 4c 69 74 65 0a 2a 2a 20 61 73 73 75 6d 65 73  QLite.** assumes
344e0 20 74 68 61 74 20 74 68 65 20 74 65 78 74 20 6f   that the text o
344f0 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 20 69 73  r BLOB result is
34500 20 69 6e 20 63 6f 6e 73 74 61 6e 74 20 73 70 61   in constant spa
34510 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 0a  ce and does not.
34520 2a 2a 20 63 6f 70 79 20 74 68 65 20 63 6f 6e 74  ** copy the cont
34530 65 6e 74 20 6f 66 20 74 68 65 20 70 61 72 61 6d  ent of the param
34540 65 74 65 72 20 6e 6f 72 20 63 61 6c 6c 20 61 20  eter nor call a 
34550 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 74 68  destructor on th
34560 65 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 77 68 65  e content.** whe
34570 6e 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65  n it has finishe
34580 64 20 75 73 69 6e 67 20 74 68 61 74 20 72 65 73  d using that res
34590 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ult..** ^If the 
345a0 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  4th parameter to
345b0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   the sqlite3_res
345c0 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66  ult_text* interf
345d0 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74  aces.** or sqlit
345e0 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69  e3_result_blob i
345f0 73 20 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f  s the special co
34600 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 54 52  nstant SQLITE_TR
34610 41 4e 53 49 45 4e 54 0a 2a 2a 20 74 68 65 6e 20  ANSIENT.** then 
34620 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63  SQLite makes a c
34630 6f 70 79 20 6f 66 20 74 68 65 20 72 65 73 75 6c  opy of the resul
34640 74 20 69 6e 74 6f 20 73 70 61 63 65 20 6f 62 74  t into space obt
34650 61 69 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 66 72  ained from.** fr
34660 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
34670 6f 63 28 29 5d 20 62 65 66 6f 72 65 20 69 74 20  oc()] before it 
34680 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  returns..**.** ^
34690 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
346a0 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72  lt_value() inter
346b0 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65  face sets the re
346c0 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61  sult of.** the a
346d0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
346e0 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
346f0 65 20 61 20 63 6f 70 79 20 74 68 65 0a 2a 2a 20  e a copy the.** 
34700 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  [unprotected sql
34710 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
34720 63 74 20 73 70 65 63 69 66 69 65 64 20 62 79 20  ct specified by 
34730 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
34740 72 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69  r.  ^The.** sqli
34750 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
34760 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d 61 6b  () interface mak
34770 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  es a copy of the
34780 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
34790 0a 2a 2a 20 73 6f 20 74 68 61 74 20 74 68 65 20  .** so that the 
347a0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20  [sqlite3_value] 
347b0 73 70 65 63 69 66 69 65 64 20 69 6e 20 74 68 65  specified in the
347c0 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 63   parameter may c
347d0 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 62 65 20 64  hange or.** be d
347e0 65 61 6c 6c 6f 63 61 74 65 64 20 61 66 74 65 72  eallocated after
347f0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
34800 76 61 6c 75 65 28 29 20 72 65 74 75 72 6e 73 20  value() returns 
34810 77 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a  without harm..**
34820 20 5e 41 20 5b 70 72 6f 74 65 63 74 65 64 20 73   ^A [protected s
34830 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
34840 6a 65 63 74 20 6d 61 79 20 61 6c 77 61 79 73 20  ject may always 
34850 62 65 20 75 73 65 64 20 77 68 65 72 65 20 61 6e  be used where an
34860 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64  .** [unprotected
34870 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
34880 6f 62 6a 65 63 74 20 69 73 20 72 65 71 75 69 72  object is requir
34890 65 64 2c 20 73 6f 20 65 69 74 68 65 72 0a 2a 2a  ed, so either.**
348a0 20 6b 69 6e 64 20 6f 66 20 5b 73 71 6c 69 74 65   kind of [sqlite
348b0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
348c0 63 61 6e 20 62 65 20 75 73 65 64 20 77 69 74 68  can be used with
348d0 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e   this interface.
348e0 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 73 65 20  .**.** If these 
348f0 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c  routines are cal
34900 6c 65 64 20 66 72 6f 6d 20 77 69 74 68 69 6e 20  led from within 
34910 74 68 65 20 64 69 66 66 65 72 65 6e 74 20 74 68  the different th
34920 72 65 61 64 0a 2a 2a 20 74 68 61 6e 20 74 68 65  read.** than the
34930 20 6f 6e 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20   one containing 
34940 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
34950 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
34960 20 74 68 61 74 20 72 65 63 65 69 76 65 64 0a 2a   that received.*
34970 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  * the [sqlite3_c
34980 6f 6e 74 65 78 74 5d 20 70 6f 69 6e 74 65 72 2c  ontext] pointer,
34990 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
349a0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 53   undefined..*/.S
349b0 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73  QLITE_API void s
349c0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
349d0 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ob(sqlite3_conte
349e0 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  xt*, const void*
349f0 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76  , int, void(*)(v
34a00 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41  oid*));.SQLITE_A
34a10 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  PI void sqlite3_
34a20 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 73 71  result_double(sq
34a30 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
34a40 64 6f 75 62 6c 65 29 3b 0a 53 51 4c 49 54 45 5f  double);.SQLITE_
34a50 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33  API void sqlite3
34a60 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 73 71  _result_error(sq
34a70 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
34a80 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74  const char*, int
34a90 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  );.SQLITE_API vo
34aa0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
34ab0 74 5f 65 72 72 6f 72 31 36 28 73 71 6c 69 74 65  t_error16(sqlite
34ac0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
34ad0 74 20 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 53  t void*, int);.S
34ae0 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73  QLITE_API void s
34af0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
34b00 72 6f 72 5f 74 6f 6f 62 69 67 28 73 71 6c 69 74  ror_toobig(sqlit
34b10 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51  e3_context*);.SQ
34b20 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71  LITE_API void sq
34b30 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
34b40 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c 69 74 65 33  or_nomem(sqlite3
34b50 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49  _context*);.SQLI
34b60 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69  TE_API void sqli
34b70 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
34b80 5f 63 6f 64 65 28 73 71 6c 69 74 65 33 5f 63 6f  _code(sqlite3_co
34b90 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 53 51  ntext*, int);.SQ
34ba0 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71  LITE_API void sq
34bb0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74  lite3_result_int
34bc0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
34bd0 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f  *, int);.SQLITE_
34be0 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33  API void sqlite3
34bf0 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 73 71  _result_int64(sq
34c00 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
34c10 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a  sqlite3_int64);.
34c20 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
34c30 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e  sqlite3_result_n
34c40 75 6c 6c 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ull(sqlite3_cont
34c50 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  ext*);.SQLITE_AP
34c60 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  I void sqlite3_r
34c70 65 73 75 6c 74 5f 74 65 78 74 28 73 71 6c 69 74  esult_text(sqlit
34c80 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
34c90 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 2c 20 76  st char*, int, v
34ca0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
34cb0 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
34cc0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
34cd0 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 63 6f  ext16(sqlite3_co
34ce0 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f  ntext*, const vo
34cf0 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a  id*, int, void(*
34d00 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54  )(void*));.SQLIT
34d10 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74  E_API void sqlit
34d20 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
34d30 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  le(sqlite3_conte
34d40 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  xt*, const void*
34d50 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f  , int,void(*)(vo
34d60 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50  id*));.SQLITE_AP
34d70 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  I void sqlite3_r
34d80 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 73  esult_text16be(s
34d90 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
34da0 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
34db0 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  t,void(*)(void*)
34dc0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  );.SQLITE_API vo
34dd0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
34de0 74 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f  t_value(sqlite3_
34df0 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65  context*, sqlite
34e00 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54  3_value*);.SQLIT
34e10 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74  E_API void sqlit
34e20 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c  e3_result_zerobl
34e30 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ob(sqlite3_conte
34e40 78 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a  xt*, int n);../*
34e50 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
34e60 66 69 6e 65 20 4e 65 77 20 43 6f 6c 6c 61 74 69  fine New Collati
34e70 6e 67 20 53 65 71 75 65 6e 63 65 73 0a 2a 2a 0a  ng Sequences.**.
34e80 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69  ** ^These functi
34e90 6f 6e 73 20 61 64 64 2c 20 72 65 6d 6f 76 65 2c  ons add, remove,
34ea0 20 6f 72 20 6d 6f 64 69 66 79 20 61 20 5b 63 6f   or modify a [co
34eb0 6c 6c 61 74 69 6f 6e 5d 20 61 73 73 6f 63 69 61  llation] associa
34ec0 74 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ted.** with the 
34ed0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
34ee0 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20  tion] specified 
34ef0 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67  as the first arg
34f00 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ument..**.** ^Th
34f10 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f  e name of the co
34f20 6c 6c 61 74 69 6f 6e 20 69 73 20 61 20 55 54 46  llation is a UTF
34f30 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 66 6f 72  -8 string.** for
34f40 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
34f50 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 61 6e 64 20  collation() and 
34f60 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
34f70 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 0a 2a 2a  ollation_v2().**
34f80 20 61 6e 64 20 61 20 55 54 46 2d 31 36 20 73 74   and a UTF-16 st
34f90 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62  ring in native b
34fa0 79 74 65 20 6f 72 64 65 72 20 66 6f 72 20 73 71  yte order for sq
34fb0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
34fc0 6c 61 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a 20 5e  lation16()..** ^
34fd0 43 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65 73 20  Collation names 
34fe0 74 68 61 74 20 63 6f 6d 70 61 72 65 20 65 71 75  that compare equ
34ff0 61 6c 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20  al according to 
35000 5b 73 71 6c 69 74 65 33 5f 73 74 72 6e 69 63 6d  [sqlite3_strnicm
35010 70 28 29 5d 20 61 72 65 0a 2a 2a 20 63 6f 6e 73  p()] are.** cons
35020 69 64 65 72 65 64 20 74 6f 20 62 65 20 74 68 65  idered to be the
35030 20 73 61 6d 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a   same name..**.*
35040 2a 20 5e 28 54 68 65 20 74 68 69 72 64 20 61 72  * ^(The third ar
35050 67 75 6d 65 6e 74 20 28 65 54 65 78 74 52 65 70  gument (eTextRep
35060 29 20 6d 75 73 74 20 62 65 20 6f 6e 65 20 6f 66  ) must be one of
35070 20 74 68 65 20 63 6f 6e 73 74 61 6e 74 73 3a 0a   the constants:.
35080 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
35090 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 0a 2a  [SQLITE_UTF8],.*
350a0 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55  * <li> [SQLITE_U
350b0 54 46 31 36 4c 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e  TF16LE],.** <li>
350c0 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45   [SQLITE_UTF16BE
350d0 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  ],.** <li> [SQLI
350e0 54 45 5f 55 54 46 31 36 5d 2c 20 6f 72 0a 2a 2a  TE_UTF16], or.**
350f0 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54   <li> [SQLITE_UT
35100 46 31 36 5f 41 4c 49 47 4e 45 44 5d 2e 0a 2a 2a  F16_ALIGNED]..**
35110 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 54 68 65   </ul>)^.** ^The
35120 20 65 54 65 78 74 52 65 70 20 61 72 67 75 6d 65   eTextRep argume
35130 6e 74 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68  nt determines th
35140 65 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20 73 74  e encoding of st
35150 72 69 6e 67 73 20 70 61 73 73 65 64 0a 2a 2a 20  rings passed.** 
35160 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67  to the collating
35170 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61   function callba
35180 63 6b 2c 20 78 43 61 6c 6c 62 61 63 6b 2e 0a 2a  ck, xCallback..*
35190 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 55  * ^The [SQLITE_U
351a0 54 46 31 36 5d 20 61 6e 64 20 5b 53 51 4c 49 54  TF16] and [SQLIT
351b0 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d  E_UTF16_ALIGNED]
351c0 20 76 61 6c 75 65 73 20 66 6f 72 20 65 54 65 78   values for eTex
351d0 74 52 65 70 0a 2a 2a 20 66 6f 72 63 65 20 73 74  tRep.** force st
351e0 72 69 6e 67 73 20 74 6f 20 62 65 20 55 54 46 31  rings to be UTF1
351f0 36 20 77 69 74 68 20 6e 61 74 69 76 65 20 62 79  6 with native by
35200 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 20 5e 54 68  te order..** ^Th
35210 65 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f  e [SQLITE_UTF16_
35220 41 4c 49 47 4e 45 44 5d 20 76 61 6c 75 65 20 66  ALIGNED] value f
35230 6f 72 20 65 54 65 78 74 52 65 70 20 66 6f 72 63  or eTextRep forc
35240 65 73 20 73 74 72 69 6e 67 73 20 74 6f 20 62 65  es strings to be
35250 67 69 6e 0a 2a 2a 20 6f 6e 20 61 6e 20 65 76 65  gin.** on an eve
35260 6e 20 62 79 74 65 20 61 64 64 72 65 73 73 2e 0a  n byte address..
35270 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74  **.** ^The fourt
35280 68 20 61 72 67 75 6d 65 6e 74 2c 20 70 41 72 67  h argument, pArg
35290 2c 20 69 73 20 61 6e 20 61 70 70 6c 69 63 61 74  , is an applicat
352a0 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72  ion data pointer
352b0 20 74 68 61 74 20 69 73 20 70 61 73 73 65 64 0a   that is passed.
352c0 2a 2a 20 74 68 72 6f 75 67 68 20 61 73 20 74 68  ** through as th
352d0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
352e0 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e   to the collatin
352f0 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62  g function callb
35300 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ack..**.** ^The 
35310 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 2c 20  fifth argument, 
35320 78 43 61 6c 6c 62 61 63 6b 2c 20 69 73 20 61 20  xCallback, is a 
35330 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 63  pointer to the c
35340 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
35350 6e 2e 0a 2a 2a 20 5e 4d 75 6c 74 69 70 6c 65 20  n..** ^Multiple 
35360 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
35370 6f 6e 73 20 63 61 6e 20 62 65 20 72 65 67 69 73  ons can be regis
35380 74 65 72 65 64 20 75 73 69 6e 67 20 74 68 65 20  tered using the 
35390 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 0a 2a 2a  same name but.**
353a0 20 77 69 74 68 20 64 69 66 66 65 72 65 6e 74 20   with different 
353b0 65 54 65 78 74 52 65 70 20 70 61 72 61 6d 65 74  eTextRep paramet
353c0 65 72 73 20 61 6e 64 20 53 51 4c 69 74 65 20 77  ers and SQLite w
353d0 69 6c 6c 20 75 73 65 20 77 68 69 63 68 65 76 65  ill use whicheve
353e0 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65  r.** function re
353f0 71 75 69 72 65 73 20 74 68 65 20 6c 65 61 73 74  quires the least
35400 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61 20   amount of data 
35410 74 72 61 6e 73 66 6f 72 6d 61 74 69 6f 6e 2e 0a  transformation..
35420 2a 2a 20 5e 49 66 20 74 68 65 20 78 43 61 6c 6c  ** ^If the xCall
35430 62 61 63 6b 20 61 72 67 75 6d 65 6e 74 20 69 73  back argument is
35440 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 63   NULL then the c
35450 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
35460 6e 20 69 73 0a 2a 2a 20 64 65 6c 65 74 65 64 2e  n is.** deleted.
35470 20 20 5e 57 68 65 6e 20 61 6c 6c 20 63 6f 6c 6c    ^When all coll
35480 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20  ating functions 
35490 68 61 76 69 6e 67 20 74 68 65 20 73 61 6d 65 20  having the same 
354a0 6e 61 6d 65 20 61 72 65 20 64 65 6c 65 74 65 64  name are deleted
354b0 2c 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 6c 61 74  ,.** that collat
354c0 69 6f 6e 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72  ion is no longer
354d0 20 75 73 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e   usable..**.** ^
354e0 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  The collating fu
354f0 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 20  nction callback 
35500 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20  is invoked with 
35510 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 70 41  a copy of the pA
35520 72 67 20 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69  rg .** applicati
35530 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 20  on data pointer 
35540 61 6e 64 20 77 69 74 68 20 74 77 6f 20 73 74 72  and with two str
35550 69 6e 67 73 20 69 6e 20 74 68 65 20 65 6e 63 6f  ings in the enco
35560 64 69 6e 67 20 73 70 65 63 69 66 69 65 64 0a 2a  ding specified.*
35570 2a 20 62 79 20 74 68 65 20 65 54 65 78 74 52 65  * by the eTextRe
35580 70 20 61 72 67 75 6d 65 6e 74 2e 20 20 54 68 65  p argument.  The
35590 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
355a0 69 6f 6e 20 6d 75 73 74 20 72 65 74 75 72 6e 20  ion must return 
355b0 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 74 68  an.** integer th
355c0 61 74 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  at is negative, 
355d0 7a 65 72 6f 2c 20 6f 72 20 70 6f 73 69 74 69 76  zero, or positiv
355e0 65 0a 2a 2a 20 69 66 20 74 68 65 20 66 69 72 73  e.** if the firs
355f0 74 20 73 74 72 69 6e 67 20 69 73 20 6c 65 73 73  t string is less
35600 20 74 68 61 6e 2c 20 65 71 75 61 6c 20 74 6f 2c   than, equal to,
35610 20 6f 72 20 67 72 65 61 74 65 72 20 74 68 61 6e   or greater than
35620 20 74 68 65 20 73 65 63 6f 6e 64 2c 0a 2a 2a 20   the second,.** 
35630 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20 20 41  respectively.  A
35640 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
35650 69 6f 6e 20 6d 75 73 74 20 61 6c 77 61 79 73 20  ion must always 
35660 72 65 74 75 72 6e 20 74 68 65 20 73 61 6d 65 20  return the same 
35670 61 6e 73 77 65 72 0a 2a 2a 20 67 69 76 65 6e 20  answer.** given 
35680 74 68 65 20 73 61 6d 65 20 69 6e 70 75 74 73 2e  the same inputs.
35690 20 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65    If two or more
356a0 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
356b0 69 6f 6e 73 20 61 72 65 20 72 65 67 69 73 74 65  ions are registe
356c0 72 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20 73 61  red.** to the sa
356d0 6d 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d  me collation nam
356e0 65 20 28 75 73 69 6e 67 20 64 69 66 66 65 72 65  e (using differe
356f0 6e 74 20 65 54 65 78 74 52 65 70 20 76 61 6c 75  nt eTextRep valu
35700 65 73 29 20 74 68 65 6e 20 61 6c 6c 0a 2a 2a 20  es) then all.** 
35710 6d 75 73 74 20 67 69 76 65 20 61 6e 20 65 71 75  must give an equ
35720 69 76 61 6c 65 6e 74 20 61 6e 73 77 65 72 20 77  ivalent answer w
35730 68 65 6e 20 69 6e 76 6f 6b 65 64 20 77 69 74 68  hen invoked with
35740 20 65 71 75 69 76 61 6c 65 6e 74 20 73 74 72 69   equivalent stri
35750 6e 67 73 2e 0a 2a 2a 20 54 68 65 20 63 6f 6c 6c  ngs..** The coll
35760 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d  ating function m
35770 75 73 74 20 6f 62 65 79 20 74 68 65 20 66 6f 6c  ust obey the fol
35780 6c 6f 77 69 6e 67 20 70 72 6f 70 65 72 74 69 65  lowing propertie
35790 73 20 66 6f 72 20 61 6c 6c 0a 2a 2a 20 73 74 72  s for all.** str
357a0 69 6e 67 73 20 41 2c 20 42 2c 20 61 6e 64 20 43  ings A, B, and C
357b0 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20  :.**.** <ol>.** 
357c0 3c 6c 69 3e 20 49 66 20 41 3d 3d 42 20 74 68 65  <li> If A==B the
357d0 6e 20 42 3d 3d 41 2e 0a 2a 2a 20 3c 6c 69 3e 20  n B==A..** <li> 
357e0 49 66 20 41 3d 3d 42 20 61 6e 64 20 42 3d 3d 43  If A==B and B==C
357f0 20 74 68 65 6e 20 41 3d 3d 43 2e 0a 2a 2a 20 3c   then A==C..** <
35800 6c 69 3e 20 49 66 20 41 26 6c 74 3b 42 20 54 48  li> If A&lt;B TH
35810 45 4e 20 42 26 67 74 3b 41 2e 0a 2a 2a 20 3c 6c  EN B&gt;A..** <l
35820 69 3e 20 49 66 20 41 26 6c 74 3b 42 20 61 6e 64  i> If A&lt;B and
35830 20 42 26 6c 74 3b 43 20 74 68 65 6e 20 41 26 6c   B&lt;C then A&l
35840 74 3b 43 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a  t;C..** </ol>.**
35850 0a 2a 2a 20 49 66 20 61 20 63 6f 6c 6c 61 74 69  .** If a collati
35860 6e 67 20 66 75 6e 63 74 69 6f 6e 20 66 61 69 6c  ng function fail
35870 73 20 61 6e 79 20 6f 66 20 74 68 65 20 61 62 6f  s any of the abo
35880 76 65 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 61  ve constraints a
35890 6e 64 20 74 68 61 74 0a 2a 2a 20 63 6f 6c 6c 61  nd that.** colla
358a0 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73  ting function is
358b0 20 20 72 65 67 69 73 74 65 72 65 64 20 61 6e 64    registered and
358c0 20 75 73 65 64 2c 20 74 68 65 6e 20 74 68 65 20   used, then the 
358d0 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69  behavior of SQLi
358e0 74 65 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e  te.** is undefin
358f0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
35900 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
35910 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77 6f 72  llation_v2() wor
35920 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f  ks like sqlite3_
35930 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
35940 28 29 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 61  ().** with the a
35950 64 64 69 74 69 6f 6e 20 74 68 61 74 20 74 68 65  ddition that the
35960 20 78 44 65 73 74 72 6f 79 20 63 61 6c 6c 62 61   xDestroy callba
35970 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e  ck is invoked on
35980 20 70 41 72 67 20 77 68 65 6e 0a 2a 2a 20 74 68   pArg when.** th
35990 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  e collating func
359a0 74 69 6f 6e 20 69 73 20 64 65 6c 65 74 65 64 2e  tion is deleted.
359b0 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6e 67 20 66  .** ^Collating f
359c0 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 64 65 6c  unctions are del
359d0 65 74 65 64 20 77 68 65 6e 20 74 68 65 79 20 61  eted when they a
359e0 72 65 20 6f 76 65 72 72 69 64 64 65 6e 20 62 79  re overridden by
359f0 20 6c 61 74 65 72 0a 2a 2a 20 63 61 6c 6c 73 20   later.** calls 
35a00 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e  to the collation
35a10 20 63 72 65 61 74 69 6f 6e 20 66 75 6e 63 74 69   creation functi
35a20 6f 6e 73 20 6f 72 20 77 68 65 6e 20 74 68 65 0a  ons or when the.
35a30 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
35a40 6e 65 63 74 69 6f 6e 5d 20 69 73 20 63 6c 6f 73  nection] is clos
35a50 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
35a60 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a  3_close()]..**.*
35a70 2a 20 5e 54 68 65 20 78 44 65 73 74 72 6f 79 20  * ^The xDestroy 
35a80 63 61 6c 6c 62 61 63 6b 20 69 73 20 3c 75 3e 6e  callback is <u>n
35a90 6f 74 3c 2f 75 3e 20 63 61 6c 6c 65 64 20 69 66  ot</u> called if
35aa0 20 74 68 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33   the .** sqlite3
35ab0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
35ac0 6e 5f 76 32 28 29 20 66 75 6e 63 74 69 6f 6e 20  n_v2() function 
35ad0 66 61 69 6c 73 2e 20 20 41 70 70 6c 69 63 61 74  fails.  Applicat
35ae0 69 6f 6e 73 20 74 68 61 74 20 69 6e 76 6f 6b 65  ions that invoke
35af0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61  .** sqlite3_crea
35b00 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
35b10 29 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c  ) with a non-NUL
35b20 4c 20 78 44 65 73 74 72 6f 79 20 61 72 67 75 6d  L xDestroy argum
35b30 65 6e 74 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 63  ent should .** c
35b40 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20  heck the return 
35b50 63 6f 64 65 20 61 6e 64 20 64 69 73 70 6f 73 65  code and dispose
35b60 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74   of the applicat
35b70 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72  ion data pointer
35b80 0a 2a 2a 20 74 68 65 6d 73 65 6c 76 65 73 20 72  .** themselves r
35b90 61 74 68 65 72 20 74 68 61 6e 20 65 78 70 65 63  ather than expec
35ba0 74 69 6e 67 20 53 51 4c 69 74 65 20 74 6f 20 64  ting SQLite to d
35bb0 65 61 6c 20 77 69 74 68 20 69 74 20 66 6f 72 20  eal with it for 
35bc0 74 68 65 6d 2e 0a 2a 2a 20 54 68 69 73 20 69 73  them..** This is
35bd0 20 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20   different from 
35be0 65 76 65 72 79 20 6f 74 68 65 72 20 53 51 4c 69  every other SQLi
35bf0 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 54  te interface.  T
35c00 68 65 20 69 6e 63 6f 6e 73 69 73 74 65 6e 63 79  he inconsistency
35c10 20 0a 2a 2a 20 69 73 20 75 6e 66 6f 72 74 75 6e   .** is unfortun
35c20 61 74 65 20 62 75 74 20 63 61 6e 6e 6f 74 20 62  ate but cannot b
35c30 65 20 63 68 61 6e 67 65 64 20 77 69 74 68 6f 75  e changed withou
35c40 74 20 62 72 65 61 6b 69 6e 67 20 62 61 63 6b 77  t breaking backw
35c50 61 72 64 73 20 0a 2a 2a 20 63 6f 6d 70 61 74 69  ards .** compati
35c60 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 53 65  bility..**.** Se
35c70 65 20 61 6c 73 6f 3a 20 20 5b 73 71 6c 69 74 65  e also:  [sqlite
35c80 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
35c90 65 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ed()] and [sqlit
35ca0 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
35cb0 64 65 64 31 36 28 29 5d 2e 0a 2a 2f 0a 53 51 4c  ded16()]..*/.SQL
35cc0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
35cd0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
35ce0 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a  tion(.  sqlite3*
35cf0 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  , .  const char 
35d00 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65  *zName, .  int e
35d10 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64  TextRep, .  void
35d20 20 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78   *pArg,.  int(*x
35d30 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69  Compare)(void*,i
35d40 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69  nt,const void*,i
35d50 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a  nt,const void*).
35d60 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
35d70 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
35d80 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 0a 20  _collation_v2(. 
35d90 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f   sqlite3*, .  co
35da0 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
35db0 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70   .  int eTextRep
35dc0 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41 72 67 2c  , .  void *pArg,
35dd0 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65  .  int(*xCompare
35de0 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  )(void*,int,cons
35df0 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  t void*,int,cons
35e00 74 20 76 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64  t void*),.  void
35e10 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64  (*xDestroy)(void
35e20 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  *).);.SQLITE_API
35e30 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65   int sqlite3_cre
35e40 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28  ate_collation16(
35e50 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
35e60 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 4e 61 6d  const void *zNam
35e70 65 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65  e,.  int eTextRe
35e80 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41 72 67  p, .  void *pArg
35e90 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72  ,.  int(*xCompar
35ea0 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  e)(void*,int,con
35eb0 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  st void*,int,con
35ec0 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a  st void*).);../*
35ed0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
35ee0 6c 6c 61 74 69 6f 6e 20 4e 65 65 64 65 64 20 43  llation Needed C
35ef0 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e  allbacks.**.** ^
35f00 54 6f 20 61 76 6f 69 64 20 68 61 76 69 6e 67 20  To avoid having 
35f10 74 6f 20 72 65 67 69 73 74 65 72 20 61 6c 6c 20  to register all 
35f20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  collation sequen
35f30 63 65 73 20 62 65 66 6f 72 65 20 61 20 64 61 74  ces before a dat
35f40 61 62 61 73 65 0a 2a 2a 20 63 61 6e 20 62 65 20  abase.** can be 
35f50 75 73 65 64 2c 20 61 20 73 69 6e 67 6c 65 20 63  used, a single c
35f60 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
35f70 20 6d 61 79 20 62 65 20 72 65 67 69 73 74 65 72   may be register
35f80 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b  ed with the.** [
35f90 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
35fa0 69 6f 6e 5d 20 74 6f 20 62 65 20 69 6e 76 6f 6b  ion] to be invok
35fb0 65 64 20 77 68 65 6e 65 76 65 72 20 61 6e 20 75  ed whenever an u
35fc0 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69  ndefined collati
35fd0 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 69  on.** sequence i
35fe0 73 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a  s required..**.*
35ff0 2a 20 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69  * ^If the functi
36000 6f 6e 20 69 73 20 72 65 67 69 73 74 65 72 65 64  on is registered
36010 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74   using the sqlit
36020 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
36030 64 65 64 28 29 20 41 50 49 2c 0a 2a 2a 20 74 68  ded() API,.** th
36040 65 6e 20 69 74 20 69 73 20 70 61 73 73 65 64 20  en it is passed 
36050 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 75 6e 64  the names of und
36060 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e  efined collation
36070 20 73 65 71 75 65 6e 63 65 73 20 61 73 20 73 74   sequences as st
36080 72 69 6e 67 73 0a 2a 2a 20 65 6e 63 6f 64 65 64  rings.** encoded
36090 20 69 6e 20 55 54 46 2d 38 2e 20 5e 49 66 20 73   in UTF-8. ^If s
360a0 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
360b0 5f 6e 65 65 64 65 64 31 36 28 29 20 69 73 20 75  _needed16() is u
360c0 73 65 64 2c 0a 2a 2a 20 74 68 65 20 6e 61 6d 65  sed,.** the name
360d0 73 20 61 72 65 20 70 61 73 73 65 64 20 61 73 20  s are passed as 
360e0 55 54 46 2d 31 36 20 69 6e 20 6d 61 63 68 69 6e  UTF-16 in machin
360f0 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  e native byte or
36100 64 65 72 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20  der..** ^A call 
36110 74 6f 20 65 69 74 68 65 72 20 66 75 6e 63 74 69  to either functi
36120 6f 6e 20 72 65 70 6c 61 63 65 73 20 74 68 65 20  on replaces the 
36130 65 78 69 73 74 69 6e 67 20 63 6f 6c 6c 61 74 69  existing collati
36140 6f 6e 2d 6e 65 65 64 65 64 20 63 61 6c 6c 62 61  on-needed callba
36150 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 28 57 68 65 6e  ck..**.** ^(When
36160 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73   the callback is
36170 20 69 6e 76 6f 6b 65 64 2c 20 74 68 65 20 66 69   invoked, the fi
36180 72 73 74 20 61 72 67 75 6d 65 6e 74 20 70 61 73  rst argument pas
36190 73 65 64 20 69 73 20 61 20 63 6f 70 79 0a 2a 2a  sed is a copy.**
361a0 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61   of the second a
361b0 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
361c0 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
361d0 64 65 64 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69  ded() or.** sqli
361e0 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
361f0 65 64 65 64 31 36 28 29 2e 20 20 54 68 65 20 73  eded16().  The s
36200 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69  econd argument i
36210 73 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  s the database.*
36220 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54  * connection.  T
36230 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
36240 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c  t is one of [SQL
36250 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49  ITE_UTF8], [SQLI
36260 54 45 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20  TE_UTF16BE],.** 
36270 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  or [SQLITE_UTF16
36280 4c 45 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67 20  LE], indicating 
36290 74 68 65 20 6d 6f 73 74 20 64 65 73 69 72 61 62  the most desirab
362a0 6c 65 20 66 6f 72 6d 20 6f 66 20 74 68 65 20 63  le form of the c
362b0 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75  ollation.** sequ
362c0 65 6e 63 65 20 66 75 6e 63 74 69 6f 6e 20 72 65  ence function re
362d0 71 75 69 72 65 64 2e 20 20 54 68 65 20 66 6f 75  quired.  The fou
362e0 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  rth parameter is
362f0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
36300 0a 2a 2a 20 72 65 71 75 69 72 65 64 20 63 6f 6c  .** required col
36310 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 2e  lation sequence.
36320 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c  )^.**.** The cal
36330 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 73  lback function s
36340 68 6f 75 6c 64 20 72 65 67 69 73 74 65 72 20 74  hould register t
36350 68 65 20 64 65 73 69 72 65 64 20 63 6f 6c 6c 61  he desired colla
36360 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  tion using.** [s
36370 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
36380 6c 6c 61 74 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c  llation()], [sql
36390 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
363a0 61 74 69 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a  ation16()], or.*
363b0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  * [sqlite3_creat
363c0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29  e_collation_v2()
363d0 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  ]..*/.SQLITE_API
363e0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c   int sqlite3_col
363f0 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 0a 20  lation_needed(. 
36400 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f   sqlite3*, .  vo
36410 69 64 2a 2c 20 0a 20 20 76 6f 69 64 28 2a 29 28  id*, .  void(*)(
36420 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69  void*,sqlite3*,i
36430 6e 74 20 65 54 65 78 74 52 65 70 2c 63 6f 6e 73  nt eTextRep,cons
36440 74 20 63 68 61 72 2a 29 0a 29 3b 0a 53 51 4c 49  t char*).);.SQLI
36450 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
36460 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
36470 64 65 64 31 36 28 0a 20 20 73 71 6c 69 74 65 33  ded16(.  sqlite3
36480 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 76  *, .  void*,.  v
36490 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c  oid(*)(void*,sql
364a0 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52  ite3*,int eTextR
364b0 65 70 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a  ep,const void*).
364c0 29 3b 0a 0a 23 69 66 64 65 66 20 53 51 4c 49 54  );..#ifdef SQLIT
364d0 45 5f 48 41 53 5f 43 4f 44 45 43 0a 2f 2a 0a 2a  E_HAS_CODEC./*.*
364e0 2a 20 53 70 65 63 69 66 79 20 74 68 65 20 6b 65  * Specify the ke
364f0 79 20 66 6f 72 20 61 6e 20 65 6e 63 72 79 70 74  y for an encrypt
36500 65 64 20 64 61 74 61 62 61 73 65 2e 20 20 54 68  ed database.  Th
36510 69 73 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c  is routine shoul
36520 64 20 62 65 0a 2a 2a 20 63 61 6c 6c 65 64 20 72  d be.** called r
36530 69 67 68 74 20 61 66 74 65 72 20 73 71 6c 69 74  ight after sqlit
36540 65 33 5f 6f 70 65 6e 28 29 2e 0a 2a 2a 0a 2a 2a  e3_open()..**.**
36550 20 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70   The code to imp
36560 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20  lement this API 
36570 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65  is not available
36580 20 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72   in the public r
36590 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c  elease.** of SQL
365a0 69 74 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ite..*/.SQLITE_A
365b0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6b  PI int sqlite3_k
365c0 65 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  ey(.  sqlite3 *d
365d0 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  b,              
365e0 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
365f0 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a   to be rekeyed *
36600 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
36610 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20  pKey, int nKey  
36620 20 20 20 2f 2a 20 54 68 65 20 6b 65 79 20 2a 2f     /* The key */
36630 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 68 61 6e 67  .);../*.** Chang
36640 65 20 74 68 65 20 6b 65 79 20 6f 6e 20 61 6e 20  e the key on an 
36650 6f 70 65 6e 20 64 61 74 61 62 61 73 65 2e 20 20  open database.  
36660 49 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 64  If the current d
36670 61 74 61 62 61 73 65 20 69 73 20 6e 6f 74 0a 2a  atabase is not.*
36680 2a 20 65 6e 63 72 79 70 74 65 64 2c 20 74 68 69  * encrypted, thi
36690 73 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 65  s routine will e
366a0 6e 63 72 79 70 74 20 69 74 2e 20 20 49 66 20 70  ncrypt it.  If p
366b0 4e 65 77 3d 3d 30 20 6f 72 20 6e 4e 65 77 3d 3d  New==0 or nNew==
366c0 30 2c 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  0, the.** databa
366d0 73 65 20 69 73 20 64 65 63 72 79 70 74 65 64 2e  se is decrypted.
366e0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20  .**.** The code 
366f0 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69  to implement thi
36700 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76 61  s API is not ava
36710 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70 75  ilable in the pu
36720 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20  blic release.** 
36730 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 53 51  of SQLite..*/.SQ
36740 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
36750 69 74 65 33 5f 72 65 6b 65 79 28 0a 20 20 73 71  ite3_rekey(.  sq
36760 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
36770 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
36780 44 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72  Database to be r
36790 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73  ekeyed */.  cons
367a0 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e  t void *pKey, in
367b0 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68  t nKey     /* Th
367c0 65 20 6e 65 77 20 6b 65 79 20 2a 2f 0a 29 3b 0a  e new key */.);.
367d0 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74  ./*.** Specify t
367e0 68 65 20 61 63 74 69 76 61 74 69 6f 6e 20 6b 65  he activation ke
367f0 79 20 66 6f 72 20 61 20 53 45 45 20 64 61 74 61  y for a SEE data
36800 62 61 73 65 2e 20 20 55 6e 6c 65 73 73 20 0a 2a  base.  Unless .*
36810 2a 20 61 63 74 69 76 61 74 65 64 2c 20 6e 6f 6e  * activated, non
36820 65 20 6f 66 20 74 68 65 20 53 45 45 20 72 6f 75  e of the SEE rou
36830 74 69 6e 65 73 20 77 69 6c 6c 20 77 6f 72 6b 2e  tines will work.
36840 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  .*/.SQLITE_API v
36850 6f 69 64 20 73 71 6c 69 74 65 33 5f 61 63 74 69  oid sqlite3_acti
36860 76 61 74 65 5f 73 65 65 28 0a 20 20 63 6f 6e 73  vate_see(.  cons
36870 74 20 63 68 61 72 20 2a 7a 50 61 73 73 50 68 72  t char *zPassPhr
36880 61 73 65 20 20 20 20 20 20 20 20 2f 2a 20 41 63  ase        /* Ac
36890 74 69 76 61 74 69 6f 6e 20 70 68 72 61 73 65 20  tivation phrase 
368a0 2a 2f 0a 29 3b 0a 23 65 6e 64 69 66 0a 0a 23 69  */.);.#endif..#i
368b0 66 64 65 66 20 53 51 4c 49 54 45 5f 45 4e 41 42  fdef SQLITE_ENAB
368c0 4c 45 5f 43 45 52 4f 44 0a 2f 2a 0a 2a 2a 20 53  LE_CEROD./*.** S
368d0 70 65 63 69 66 79 20 74 68 65 20 61 63 74 69 76  pecify the activ
368e0 61 74 69 6f 6e 20 6b 65 79 20 66 6f 72 20 61 20  ation key for a 
368f0 43 45 52 4f 44 20 64 61 74 61 62 61 73 65 2e 20  CEROD database. 
36900 20 55 6e 6c 65 73 73 20 0a 2a 2a 20 61 63 74 69   Unless .** acti
36910 76 61 74 65 64 2c 20 6e 6f 6e 65 20 6f 66 20 74  vated, none of t
36920 68 65 20 43 45 52 4f 44 20 72 6f 75 74 69 6e 65  he CEROD routine
36930 73 20 77 69 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a  s will work..*/.
36940 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
36950 73 71 6c 69 74 65 33 5f 61 63 74 69 76 61 74 65  sqlite3_activate
36960 5f 63 65 72 6f 64 28 0a 20 20 63 6f 6e 73 74 20  _cerod(.  const 
36970 63 68 61 72 20 2a 7a 50 61 73 73 50 68 72 61 73  char *zPassPhras
36980 65 20 20 20 20 20 20 20 20 2f 2a 20 41 63 74 69  e        /* Acti
36990 76 61 74 69 6f 6e 20 70 68 72 61 73 65 20 2a 2f  vation phrase */
369a0 0a 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a  .);.#endif../*.*
369b0 2a 20 43 41 50 49 33 52 45 46 3a 20 53 75 73 70  * CAPI3REF: Susp
369c0 65 6e 64 20 45 78 65 63 75 74 69 6f 6e 20 46 6f  end Execution Fo
369d0 72 20 41 20 53 68 6f 72 74 20 54 69 6d 65 0a 2a  r A Short Time.*
369e0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
369f0 5f 73 6c 65 65 70 28 29 20 66 75 6e 63 74 69 6f  _sleep() functio
36a00 6e 20 63 61 75 73 65 73 20 74 68 65 20 63 75 72  n causes the cur
36a10 72 65 6e 74 20 74 68 72 65 61 64 20 74 6f 20 73  rent thread to s
36a20 75 73 70 65 6e 64 20 65 78 65 63 75 74 69 6f 6e  uspend execution
36a30 0a 2a 2a 20 66 6f 72 20 61 74 20 6c 65 61 73 74  .** for at least
36a40 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c   a number of mil
36a50 6c 69 73 65 63 6f 6e 64 73 20 73 70 65 63 69 66  liseconds specif
36a60 69 65 64 20 69 6e 20 69 74 73 20 70 61 72 61 6d  ied in its param
36a70 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  eter..**.** If t
36a80 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  he operating sys
36a90 74 65 6d 20 64 6f 65 73 20 6e 6f 74 20 73 75 70  tem does not sup
36aa0 70 6f 72 74 20 73 6c 65 65 70 20 72 65 71 75 65  port sleep reque
36ab0 73 74 73 20 77 69 74 68 0a 2a 2a 20 6d 69 6c 6c  sts with.** mill
36ac0 69 73 65 63 6f 6e 64 20 74 69 6d 65 20 72 65 73  isecond time res
36ad0 6f 6c 75 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68  olution, then th
36ae0 65 20 74 69 6d 65 20 77 69 6c 6c 20 62 65 20 72  e time will be r
36af0 6f 75 6e 64 65 64 20 75 70 20 74 6f 0a 2a 2a 20  ounded up to.** 
36b00 74 68 65 20 6e 65 61 72 65 73 74 20 73 65 63 6f  the nearest seco
36b10 6e 64 2e 20 54 68 65 20 6e 75 6d 62 65 72 20 6f  nd. The number o
36b20 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f  f milliseconds o
36b30 66 20 73 6c 65 65 70 20 61 63 74 75 61 6c 6c 79  f sleep actually
36b40 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20 66 72  .** requested fr
36b50 6f 6d 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67  om the operating
36b60 20 73 79 73 74 65 6d 20 69 73 20 72 65 74 75 72   system is retur
36b70 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69  ned..**.** ^SQLi
36b80 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68  te implements th
36b90 69 73 20 69 6e 74 65 72 66 61 63 65 20 62 79 20  is interface by 
36ba0 63 61 6c 6c 69 6e 67 20 74 68 65 20 78 53 6c 65  calling the xSle
36bb0 65 70 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f  ep().** method o
36bc0 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73  f the default [s
36bd0 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
36be0 63 74 2e 20 20 49 66 20 74 68 65 20 78 53 6c 65  ct.  If the xSle
36bf0 65 70 28 29 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f  ep() method.** o
36c00 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 56 46  f the default VF
36c10 53 20 69 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65  S is not impleme
36c20 6e 74 65 64 20 63 6f 72 72 65 63 74 6c 79 2c 20  nted correctly, 
36c30 6f 72 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74  or not implement
36c40 65 64 20 61 74 0a 2a 2a 20 61 6c 6c 2c 20 74 68  ed at.** all, th
36c50 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
36c60 6f 66 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70  of sqlite3_sleep
36c70 28 29 20 6d 61 79 20 64 65 76 69 61 74 65 20 66  () may deviate f
36c80 72 6f 6d 20 74 68 65 20 64 65 73 63 72 69 70 74  rom the descript
36c90 69 6f 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 70 72  ion.** in the pr
36ca0 65 76 69 6f 75 73 20 70 61 72 61 67 72 61 70 68  evious paragraph
36cb0 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  s..*/.SQLITE_API
36cc0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 6c 65   int sqlite3_sle
36cd0 65 70 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ep(int);../*.** 
36ce0 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f  CAPI3REF: Name O
36cf0 66 20 54 68 65 20 46 6f 6c 64 65 72 20 48 6f 6c  f The Folder Hol
36d00 64 69 6e 67 20 54 65 6d 70 6f 72 61 72 79 20 46  ding Temporary F
36d10 69 6c 65 73 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20  iles.**.** ^(If 
36d20 74 68 69 73 20 67 6c 6f 62 61 6c 20 76 61 72 69  this global vari
36d30 61 62 6c 65 20 69 73 20 6d 61 64 65 20 74 6f 20  able is made to 
36d40 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e  point to a strin
36d50 67 20 77 68 69 63 68 20 69 73 0a 2a 2a 20 74 68  g which is.** th
36d60 65 20 6e 61 6d 65 20 6f 66 20 61 20 66 6f 6c 64  e name of a fold
36d70 65 72 20 28 61 2e 6b 2e 61 2e 20 64 69 72 65 63  er (a.k.a. direc
36d80 74 6f 72 79 29 2c 20 74 68 65 6e 20 61 6c 6c 20  tory), then all 
36d90 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 0a  temporary files.
36da0 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 53 51  ** created by SQ
36db0 4c 69 74 65 20 77 68 65 6e 20 75 73 69 6e 67 20  Lite when using 
36dc0 61 20 62 75 69 6c 74 2d 69 6e 20 5b 73 71 6c 69  a built-in [sqli
36dd0 74 65 33 5f 76 66 73 20 7c 20 56 46 53 5d 0a 2a  te3_vfs | VFS].*
36de0 2a 20 77 69 6c 6c 20 62 65 20 70 6c 61 63 65 64  * will be placed
36df0 20 69 6e 20 74 68 61 74 20 64 69 72 65 63 74 6f   in that directo
36e00 72 79 2e 29 5e 20 20 5e 49 66 20 74 68 69 73 20  ry.)^  ^If this 
36e10 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69 73 20 61  variable.** is a
36e20 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74   NULL pointer, t
36e30 68 65 6e 20 53 51 4c 69 74 65 20 70 65 72 66 6f  hen SQLite perfo
36e40 72 6d 73 20 61 20 73 65 61 72 63 68 20 66 6f 72  rms a search for
36e50 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 0a   an appropriate.
36e60 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c  ** temporary fil
36e70 65 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a  e directory..**.
36e80 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66  ** It is not saf
36e90 65 20 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f 64  e to read or mod
36ea0 69 66 79 20 74 68 69 73 20 76 61 72 69 61 62 6c  ify this variabl
36eb0 65 20 69 6e 20 6d 6f 72 65 20 74 68 61 6e 20 6f  e in more than o
36ec0 6e 65 0a 2a 2a 20 74 68 72 65 61 64 20 61 74 20  ne.** thread at 
36ed0 61 20 74 69 6d 65 2e 20 20 49 74 20 69 73 20 6e  a time.  It is n
36ee0 6f 74 20 73 61 66 65 20 74 6f 20 72 65 61 64 20  ot safe to read 
36ef0 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76  or modify this v
36f00 61 72 69 61 62 6c 65 0a 2a 2a 20 69 66 20 61 20  ariable.** if a 
36f10 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
36f20 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 75  tion] is being u
36f30 73 65 64 20 61 74 20 74 68 65 20 73 61 6d 65 20  sed at the same 
36f40 74 69 6d 65 20 69 6e 20 61 20 73 65 70 61 72 61  time in a separa
36f50 74 65 0a 2a 2a 20 74 68 72 65 61 64 2e 0a 2a 2a  te.** thread..**
36f60 20 49 74 20 69 73 20 69 6e 74 65 6e 64 65 64 20   It is intended 
36f70 74 68 61 74 20 74 68 69 73 20 76 61 72 69 61 62  that this variab
36f80 6c 65 20 62 65 20 73 65 74 20 6f 6e 63 65 0a 2a  le be set once.*
36f90 2a 20 61 73 20 70 61 72 74 20 6f 66 20 70 72 6f  * as part of pro
36fa0 63 65 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74  cess initializat
36fb0 69 6f 6e 20 61 6e 64 20 62 65 66 6f 72 65 20 61  ion and before a
36fc0 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  ny SQLite interf
36fd0 61 63 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20  ace.** routines 
36fe0 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64  have been called
36ff0 20 61 6e 64 20 74 68 61 74 20 74 68 69 73 20 76   and that this v
37000 61 72 69 61 62 6c 65 20 72 65 6d 61 69 6e 20 75  ariable remain u
37010 6e 63 68 61 6e 67 65 64 0a 2a 2a 20 74 68 65 72  nchanged.** ther
37020 65 61 66 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  eafter..**.** ^T
37030 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64  he [temp_store_d
37040 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d  irectory pragma]
37050 20 6d 61 79 20 6d 6f 64 69 66 79 20 74 68 69 73   may modify this
37060 20 76 61 72 69 61 62 6c 65 20 61 6e 64 20 63 61   variable and ca
37070 75 73 65 0a 2a 2a 20 69 74 20 74 6f 20 70 6f 69  use.** it to poi
37080 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74  nt to memory obt
37090 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
370a0 74 65 33 5f 6d 61 6c 6c 6f 63 5d 2e 20 20 5e 46  te3_malloc].  ^F
370b0 75 72 74 68 65 72 6d 6f 72 65 2c 0a 2a 2a 20 74  urthermore,.** t
370c0 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64  he [temp_store_d
370d0 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d  irectory pragma]
370e0 20 61 6c 77 61 79 73 20 61 73 73 75 6d 65 73 20   always assumes 
370f0 74 68 61 74 20 61 6e 79 20 73 74 72 69 6e 67 0a  that any string.
37100 2a 2a 20 74 68 61 74 20 74 68 69 73 20 76 61 72  ** that this var
37110 69 61 62 6c 65 20 70 6f 69 6e 74 73 20 74 6f 20  iable points to 
37120 69 73 20 68 65 6c 64 20 69 6e 20 6d 65 6d 6f 72  is held in memor
37130 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
37140 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  .** [sqlite3_mal
37150 6c 6f 63 5d 20 61 6e 64 20 74 68 65 20 70 72 61  loc] and the pra
37160 67 6d 61 20 6d 61 79 20 61 74 74 65 6d 70 74 20  gma may attempt 
37170 74 6f 20 66 72 65 65 20 74 68 61 74 20 6d 65 6d  to free that mem
37180 6f 72 79 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71  ory.** using [sq
37190 6c 69 74 65 33 5f 66 72 65 65 5d 2e 0a 2a 2a 20  lite3_free]..** 
371a0 48 65 6e 63 65 2c 20 69 66 20 74 68 69 73 20 76  Hence, if this v
371b0 61 72 69 61 62 6c 65 20 69 73 20 6d 6f 64 69 66  ariable is modif
371c0 69 65 64 20 64 69 72 65 63 74 6c 79 2c 20 65 69  ied directly, ei
371d0 74 68 65 72 20 69 74 20 73 68 6f 75 6c 64 20 62  ther it should b
371e0 65 0a 2a 2a 20 6d 61 64 65 20 4e 55 4c 4c 20 6f  e.** made NULL o
371f0 72 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20  r made to point 
37200 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  to memory obtain
37210 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
37220 5f 6d 61 6c 6c 6f 63 5d 0a 2a 2a 20 6f 72 20 65  _malloc].** or e
37230 6c 73 65 20 74 68 65 20 75 73 65 20 6f 66 20 74  lse the use of t
37240 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64  he [temp_store_d
37250 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d  irectory pragma]
37260 20 73 68 6f 75 6c 64 20 62 65 20 61 76 6f 69 64   should be avoid
37270 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  ed..*/.SQLITE_AP
37280 49 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  I char *sqlite3_
37290 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 3b 0a  temp_directory;.
372a0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
372b0 20 54 65 73 74 20 46 6f 72 20 41 75 74 6f 2d 43   Test For Auto-C
372c0 6f 6d 6d 69 74 20 4d 6f 64 65 0a 2a 2a 20 4b 45  ommit Mode.** KE
372d0 59 57 4f 52 44 53 3a 20 7b 61 75 74 6f 63 6f 6d  YWORDS: {autocom
372e0 6d 69 74 20 6d 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20  mit mode}.**.** 
372f0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74  ^The sqlite3_get
37300 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 29 20 69 6e  _autocommit() in
37310 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
37320 6e 6f 6e 2d 7a 65 72 6f 20 6f 72 0a 2a 2a 20 7a  non-zero or.** z
37330 65 72 6f 20 69 66 20 74 68 65 20 67 69 76 65 6e  ero if the given
37340 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
37350 74 69 6f 6e 20 69 73 20 6f 72 20 69 73 20 6e 6f  tion is or is no
37360 74 20 69 6e 20 61 75 74 6f 63 6f 6d 6d 69 74 20  t in autocommit 
37370 6d 6f 64 65 2c 0a 2a 2a 20 72 65 73 70 65 63 74  mode,.** respect
37380 69 76 65 6c 79 2e 20 20 5e 41 75 74 6f 63 6f 6d  ively.  ^Autocom
37390 6d 69 74 20 6d 6f 64 65 20 69 73 20 6f 6e 20 62  mit mode is on b
373a0 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 5e 41  y default..** ^A
373b0 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69  utocommit mode i
373c0 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 61 20  s disabled by a 
373d0 5b 42 45 47 49 4e 5d 20 73 74 61 74 65 6d 65 6e  [BEGIN] statemen
373e0 74 2e 0a 2a 2a 20 5e 41 75 74 6f 63 6f 6d 6d 69  t..** ^Autocommi
373f0 74 20 6d 6f 64 65 20 69 73 20 72 65 2d 65 6e 61  t mode is re-ena
37400 62 6c 65 64 20 62 79 20 61 20 5b 43 4f 4d 4d 49  bled by a [COMMI
37410 54 5d 20 6f 72 20 5b 52 4f 4c 4c 42 41 43 4b 5d  T] or [ROLLBACK]
37420 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 63 65 72 74 61  ..**.** If certa
37430 69 6e 20 6b 69 6e 64 73 20 6f 66 20 65 72 72 6f  in kinds of erro
37440 72 73 20 6f 63 63 75 72 20 6f 6e 20 61 20 73 74  rs occur on a st
37450 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 61  atement within a
37460 20 6d 75 6c 74 69 2d 73 74 61 74 65 6d 65 6e 74   multi-statement
37470 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  .** transaction 
37480 28 65 72 72 6f 72 73 20 69 6e 63 6c 75 64 69 6e  (errors includin
37490 67 20 5b 53 51 4c 49 54 45 5f 46 55 4c 4c 5d 2c  g [SQLITE_FULL],
374a0 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 2c   [SQLITE_IOERR],
374b0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45  .** [SQLITE_NOME
374c0 4d 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  M], [SQLITE_BUSY
374d0 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 49  ], and [SQLITE_I
374e0 4e 54 45 52 52 55 50 54 5d 29 20 74 68 65 6e 20  NTERRUPT]) then 
374f0 74 68 65 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69  the.** transacti
37500 6f 6e 20 6d 69 67 68 74 20 62 65 20 72 6f 6c 6c  on might be roll
37510 65 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69  ed back automati
37520 63 61 6c 6c 79 2e 20 20 54 68 65 20 6f 6e 6c 79  cally.  The only
37530 20 77 61 79 20 74 6f 0a 2a 2a 20 66 69 6e 64 20   way to.** find 
37540 6f 75 74 20 77 68 65 74 68 65 72 20 53 51 4c 69  out whether SQLi
37550 74 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  te automatically
37560 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 74 68 65   rolled back the
37570 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 61 66 74   transaction aft
37580 65 72 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20 69  er.** an error i
37590 73 20 74 6f 20 75 73 65 20 74 68 69 73 20 66 75  s to use this fu
375a0 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66  nction..**.** If
375b0 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 20   another thread 
375c0 63 68 61 6e 67 65 73 20 74 68 65 20 61 75 74 6f  changes the auto
375d0 63 6f 6d 6d 69 74 20 73 74 61 74 75 73 20 6f 66  commit status of
375e0 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
375f0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c   connection whil
37600 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69  e this routine i
37610 73 20 72 75 6e 6e 69 6e 67 2c 20 74 68 65 6e 20  s running, then 
37620 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
37630 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64  .** is undefined
37640 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
37650 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  int sqlite3_get_
37660 61 75 74 6f 63 6f 6d 6d 69 74 28 73 71 6c 69 74  autocommit(sqlit
37670 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
37680 49 33 52 45 46 3a 20 46 69 6e 64 20 54 68 65 20  I3REF: Find The 
37690 44 61 74 61 62 61 73 65 20 48 61 6e 64 6c 65 20  Database Handle 
376a0 4f 66 20 41 20 50 72 65 70 61 72 65 64 20 53 74  Of A Prepared St
376b0 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54  atement.**.** ^T
376c0 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 68 61  he sqlite3_db_ha
376d0 6e 64 6c 65 20 69 6e 74 65 72 66 61 63 65 20 72  ndle interface r
376e0 65 74 75 72 6e 73 20 74 68 65 20 5b 64 61 74 61  eturns the [data
376f0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
37700 20 68 61 6e 64 6c 65 0a 2a 2a 20 74 6f 20 77 68   handle.** to wh
37710 69 63 68 20 61 20 5b 70 72 65 70 61 72 65 64 20  ich a [prepared 
37720 73 74 61 74 65 6d 65 6e 74 5d 20 62 65 6c 6f 6e  statement] belon
37730 67 73 2e 20 20 5e 54 68 65 20 5b 64 61 74 61 62  gs.  ^The [datab
37740 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a  ase connection].
37750 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ** returned by s
37760 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65  qlite3_db_handle
37770 20 69 73 20 74 68 65 20 73 61 6d 65 20 5b 64 61   is the same [da
37780 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
37790 6e 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 74  n].** that was t
377a0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
377b0 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c  t.** to the [sql
377c0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
377d0 29 5d 20 63 61 6c 6c 20 28 6f 72 20 69 74 73 20  )] call (or its 
377e0 76 61 72 69 61 6e 74 73 29 20 74 68 61 74 20 77  variants) that w
377f0 61 73 20 75 73 65 64 20 74 6f 0a 2a 2a 20 63 72  as used to.** cr
37800 65 61 74 65 20 74 68 65 20 73 74 61 74 65 6d 65  eate the stateme
37810 6e 74 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  nt in the first 
37820 70 6c 61 63 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45  place..*/.SQLITE
37830 5f 41 50 49 20 73 71 6c 69 74 65 33 20 2a 73 71  _API sqlite3 *sq
37840 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 28  lite3_db_handle(
37850 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
37860 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
37870 20 46 69 6e 64 20 74 68 65 20 6e 65 78 74 20 70   Find the next p
37880 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
37890 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e  t.**.** ^This in
378a0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
378b0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
378c0 20 6e 65 78 74 20 5b 70 72 65 70 61 72 65 64 20   next [prepared 
378d0 73 74 61 74 65 6d 65 6e 74 5d 20 61 66 74 65 72  statement] after
378e0 0a 2a 2a 20 70 53 74 6d 74 20 61 73 73 6f 63 69  .** pStmt associ
378f0 61 74 65 64 20 77 69 74 68 20 74 68 65 20 5b 64  ated with the [d
37900 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
37910 6f 6e 5d 20 70 44 62 2e 20 20 5e 49 66 20 70 53  on] pDb.  ^If pS
37920 74 6d 74 20 69 73 20 4e 55 4c 4c 0a 2a 2a 20 74  tmt is NULL.** t
37930 68 65 6e 20 74 68 69 73 20 69 6e 74 65 72 66 61  hen this interfa
37940 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ce returns a poi
37950 6e 74 65 72 20 74 6f 20 74 68 65 20 66 69 72 73  nter to the firs
37960 74 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  t prepared state
37970 6d 65 6e 74 0a 2a 2a 20 61 73 73 6f 63 69 61 74  ment.** associat
37980 65 64 20 77 69 74 68 20 74 68 65 20 64 61 74 61  ed with the data
37990 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
379a0 70 44 62 2e 20 20 5e 49 66 20 6e 6f 20 70 72 65  pDb.  ^If no pre
379b0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a  pared statement.
379c0 2a 2a 20 73 61 74 69 73 66 69 65 73 20 74 68 65  ** satisfies the
379d0 20 63 6f 6e 64 69 74 69 6f 6e 73 20 6f 66 20 74   conditions of t
379e0 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 69 74 20  his routine, it 
379f0 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2e 0a 2a 2a  returns NULL..**
37a00 0a 2a 2a 20 54 68 65 20 5b 64 61 74 61 62 61 73  .** The [databas
37a10 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 6f  e connection] po
37a20 69 6e 74 65 72 20 44 20 69 6e 20 61 20 63 61 6c  inter D in a cal
37a30 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  l to.** [sqlite3
37a40 5f 6e 65 78 74 5f 73 74 6d 74 28 44 2c 53 29 5d  _next_stmt(D,S)]
37a50 20 6d 75 73 74 20 72 65 66 65 72 20 74 6f 20 61   must refer to a
37a60 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 0a  n open database.
37a70 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 61 6e  ** connection an
37a80 64 20 69 6e 20 70 61 72 74 69 63 75 6c 61 72 20  d in particular 
37a90 6d 75 73 74 20 6e 6f 74 20 62 65 20 61 20 4e 55  must not be a NU
37aa0 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2f 0a 53  LL pointer..*/.S
37ab0 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65  QLITE_API sqlite
37ac0 33 5f 73 74 6d 74 20 2a 73 71 6c 69 74 65 33 5f  3_stmt *sqlite3_
37ad0 6e 65 78 74 5f 73 74 6d 74 28 73 71 6c 69 74 65  next_stmt(sqlite
37ae0 33 20 2a 70 44 62 2c 20 73 71 6c 69 74 65 33 5f  3 *pDb, sqlite3_
37af0 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
37b00 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
37b10 6f 6d 6d 69 74 20 41 6e 64 20 52 6f 6c 6c 62 61  ommit And Rollba
37b20 63 6b 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20  ck Notification 
37b30 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20  Callbacks.**.** 
37b40 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d  ^The sqlite3_com
37b50 6d 69 74 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72  mit_hook() inter
37b60 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61  face registers a
37b70 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e   callback.** fun
37b80 63 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76 6f  ction to be invo
37b90 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 20 74  ked whenever a t
37ba0 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 5b 43  ransaction is [C
37bb0 4f 4d 4d 49 54 20 7c 20 63 6f 6d 6d 69 74 74 65  OMMIT | committe
37bc0 64 5d 2e 0a 2a 2a 20 5e 41 6e 79 20 63 61 6c 6c  d]..** ^Any call
37bd0 62 61 63 6b 20 73 65 74 20 62 79 20 61 20 70 72  back set by a pr
37be0 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 73  evious call to s
37bf0 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f  qlite3_commit_ho
37c00 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20 74 68 65 20  ok().** for the 
37c10 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f  same database co
37c20 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 72  nnection is over
37c30 72 69 64 64 65 6e 2e 0a 2a 2a 20 5e 54 68 65 20  ridden..** ^The 
37c40 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b  sqlite3_rollback
37c50 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63  _hook() interfac
37c60 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61  e registers a ca
37c70 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69  llback.** functi
37c80 6f 6e 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64  on to be invoked
37c90 20 77 68 65 6e 65 76 65 72 20 61 20 74 72 61 6e   whenever a tran
37ca0 73 61 63 74 69 6f 6e 20 69 73 20 5b 52 4f 4c 4c  saction is [ROLL
37cb0 42 41 43 4b 20 7c 20 72 6f 6c 6c 65 64 20 62 61  BACK | rolled ba
37cc0 63 6b 5d 2e 0a 2a 2a 20 5e 41 6e 79 20 63 61 6c  ck]..** ^Any cal
37cd0 6c 62 61 63 6b 20 73 65 74 20 62 79 20 61 20 70  lback set by a p
37ce0 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20  revious call to 
37cf0 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b  sqlite3_rollback
37d00 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20 74  _hook().** for t
37d10 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
37d20 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f   connection is o
37d30 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20 5e 54  verridden..** ^T
37d40 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74  he pArg argument
37d50 20 69 73 20 70 61 73 73 65 64 20 74 68 72 6f 75   is passed throu
37d60 67 68 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  gh to the callba
37d70 63 6b 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63  ck..** ^If the c
37d80 61 6c 6c 62 61 63 6b 20 6f 6e 20 61 20 63 6f 6d  allback on a com
37d90 6d 69 74 20 68 6f 6f 6b 20 66 75 6e 63 74 69 6f  mit hook functio
37da0 6e 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65  n returns non-ze
37db0 72 6f 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  ro,.** then the 
37dc0 63 6f 6d 6d 69 74 20 69 73 20 63 6f 6e 76 65 72  commit is conver
37dd0 74 65 64 20 69 6e 74 6f 20 61 20 72 6f 6c 6c 62  ted into a rollb
37de0 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ack..**.** ^The 
37df0 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68  sqlite3_commit_h
37e00 6f 6f 6b 28 44 2c 43 2c 50 29 20 61 6e 64 20 73  ook(D,C,P) and s
37e10 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f  qlite3_rollback_
37e20 68 6f 6f 6b 28 44 2c 43 2c 50 29 20 66 75 6e 63  hook(D,C,P) func
37e30 74 69 6f 6e 73 0a 2a 2a 20 72 65 74 75 72 6e 20  tions.** return 
37e40 74 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20 66  the P argument f
37e50 72 6f 6d 20 74 68 65 20 70 72 65 76 69 6f 75 73  rom the previous
37e60 20 63 61 6c 6c 20 6f 66 20 74 68 65 20 73 61 6d   call of the sam
37e70 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6f 6e  e function.** on
37e80 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62   the same [datab
37e90 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
37ea0 44 2c 20 6f 72 20 4e 55 4c 4c 20 66 6f 72 0a 2a  D, or NULL for.*
37eb0 2a 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c  * the first call
37ec0 20 66 6f 72 20 65 61 63 68 20 66 75 6e 63 74 69   for each functi
37ed0 6f 6e 20 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20 54  on on D..**.** T
37ee0 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 6d 70 6c  he callback impl
37ef0 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73 74 20  ementation must 
37f00 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20  not do anything 
37f10 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79  that will modify
37f20 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
37f30 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74   connection that
37f40 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 63 61 6c   invoked the cal
37f50 6c 62 61 63 6b 2e 20 20 41 6e 79 20 61 63 74 69  lback.  Any acti
37f60 6f 6e 73 0a 2a 2a 20 74 6f 20 6d 6f 64 69 66 79  ons.** to modify
37f70 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
37f80 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 62 65  nnection must be
37f90 20 64 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20   deferred until 
37fa0 61 66 74 65 72 20 74 68 65 0a 2a 2a 20 63 6f 6d  after the.** com
37fb0 70 6c 65 74 69 6f 6e 20 6f 66 20 74 68 65 20 5b  pletion of the [
37fc0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
37fd0 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65  call that trigge
37fe0 72 65 64 20 74 68 65 20 63 6f 6d 6d 69 74 0a 2a  red the commit.*
37ff0 2a 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 68 6f  * or rollback ho
38000 6f 6b 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  ok in the first 
38010 70 6c 61 63 65 2e 0a 2a 2a 20 4e 6f 74 65 20 74  place..** Note t
38020 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  hat [sqlite3_pre
38030 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b  pare_v2()] and [
38040 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
38050 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69  both modify thei
38060 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  r.** database co
38070 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68  nnections for th
38080 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f  e meaning of "mo
38090 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61  dify" in this pa
380a0 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e  ragraph..**.** ^
380b0 52 65 67 69 73 74 65 72 69 6e 67 20 61 20 4e 55  Registering a NU
380c0 4c 4c 20 66 75 6e 63 74 69 6f 6e 20 64 69 73 61  LL function disa
380d0 62 6c 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63  bles the callbac
380e0 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 74  k..**.** ^When t
380f0 68 65 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 63  he commit hook c
38100 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20  allback routine 
38110 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20 74 68  returns zero, th
38120 65 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 70  e [COMMIT].** op
38130 65 72 61 74 69 6f 6e 20 69 73 20 61 6c 6c 6f 77  eration is allow
38140 65 64 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 6e  ed to continue n
38150 6f 72 6d 61 6c 6c 79 2e 20 20 5e 49 66 20 74 68  ormally.  ^If th
38160 65 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 0a 2a 2a  e commit hook.**
38170 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72   returns non-zer
38180 6f 2c 20 74 68 65 6e 20 74 68 65 20 5b 43 4f 4d  o, then the [COM
38190 4d 49 54 5d 20 69 73 20 63 6f 6e 76 65 72 74 65  MIT] is converte
381a0 64 20 69 6e 74 6f 20 61 20 5b 52 4f 4c 4c 42 41  d into a [ROLLBA
381b0 43 4b 5d 2e 0a 2a 2a 20 5e 54 68 65 20 72 6f 6c  CK]..** ^The rol
381c0 6c 62 61 63 6b 20 68 6f 6f 6b 20 69 73 20 69 6e  lback hook is in
381d0 76 6f 6b 65 64 20 6f 6e 20 61 20 72 6f 6c 6c 62  voked on a rollb
381e0 61 63 6b 20 74 68 61 74 20 72 65 73 75 6c 74 73  ack that results
381f0 20 66 72 6f 6d 20 61 20 63 6f 6d 6d 69 74 0a 2a   from a commit.*
38200 2a 20 68 6f 6f 6b 20 72 65 74 75 72 6e 69 6e 67  * hook returning
38210 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 6a 75 73 74 20   non-zero, just 
38220 61 73 20 69 74 20 77 6f 75 6c 64 20 62 65 20 77  as it would be w
38230 69 74 68 20 61 6e 79 20 6f 74 68 65 72 20 72 6f  ith any other ro
38240 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 46  llback..**.** ^F
38250 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65 73 20  or the purposes 
38260 6f 66 20 74 68 69 73 20 41 50 49 2c 20 61 20 74  of this API, a t
38270 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 73 61  ransaction is sa
38280 69 64 20 74 6f 20 68 61 76 65 20 62 65 65 6e 0a  id to have been.
38290 2a 2a 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 69  ** rolled back i
382a0 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20 22 52  f an explicit "R
382b0 4f 4c 4c 42 41 43 4b 22 20 73 74 61 74 65 6d 65  OLLBACK" stateme
382c0 6e 74 20 69 73 20 65 78 65 63 75 74 65 64 2c 20  nt is executed, 
382d0 6f 72 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20 6f  or.** an error o
382e0 72 20 63 6f 6e 73 74 72 61 69 6e 74 20 63 61 75  r constraint cau
382f0 73 65 73 20 61 6e 20 69 6d 70 6c 69 63 69 74 20  ses an implicit 
38300 72 6f 6c 6c 62 61 63 6b 20 74 6f 20 6f 63 63 75  rollback to occu
38310 72 2e 0a 2a 2a 20 5e 54 68 65 20 72 6f 6c 6c 62  r..** ^The rollb
38320 61 63 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ack callback is 
38330 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 69 66 20 61  not invoked if a
38340 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 0a   transaction is.
38350 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ** automatically
38360 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62 65 63   rolled back bec
38370 61 75 73 65 20 74 68 65 20 64 61 74 61 62 61 73  ause the databas
38380 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
38390 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 65  closed..**.** Se
383a0 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69  e also the [sqli
383b0 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28  te3_update_hook(
383c0 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f  )] interface..*/
383d0 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
383e0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74   *sqlite3_commit
383f0 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c 20  _hook(sqlite3*, 
38400 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76  int(*)(void*), v
38410 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  oid*);.SQLITE_AP
38420 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  I void *sqlite3_
38430 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 73 71  rollback_hook(sq
38440 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 29 28  lite3*, void(*)(
38450 76 6f 69 64 20 2a 29 2c 20 76 6f 69 64 2a 29 3b  void *), void*);
38460 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
38470 3a 20 44 61 74 61 20 43 68 61 6e 67 65 20 4e 6f  : Data Change No
38480 74 69 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62  tification Callb
38490 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  acks.**.** ^The 
384a0 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68  sqlite3_update_h
384b0 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20  ook() interface 
384c0 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c  registers a call
384d0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  back function.**
384e0 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62   with the [datab
384f0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
38500 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68  identified by th
38510 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
38520 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65  .** to be invoke
38530 64 20 77 68 65 6e 65 76 65 72 20 61 20 72 6f 77  d whenever a row
38540 20 69 73 20 75 70 64 61 74 65 64 2c 20 69 6e 73   is updated, ins
38550 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64  erted or deleted
38560 2e 0a 2a 2a 20 5e 41 6e 79 20 63 61 6c 6c 62 61  ..** ^Any callba
38570 63 6b 20 73 65 74 20 62 79 20 61 20 70 72 65 76  ck set by a prev
38580 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 74 68 69  ious call to thi
38590 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 66 6f  s function.** fo
385a0 72 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  r the same datab
385b0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
385c0 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a  s overridden..**
385d0 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  .** ^The second 
385e0 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f  argument is a po
385f0 69 6e 74 65 72 20 74 6f 20 74 68 65 20 66 75 6e  inter to the fun
38600 63 74 69 6f 6e 20 74 6f 20 69 6e 76 6f 6b 65 20  ction to invoke 
38610 77 68 65 6e 20 61 0a 2a 2a 20 72 6f 77 20 69 73  when a.** row is
38620 20 75 70 64 61 74 65 64 2c 20 69 6e 73 65 72 74   updated, insert
38630 65 64 20 6f 72 20 64 65 6c 65 74 65 64 2e 0a 2a  ed or deleted..*
38640 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67  * ^The first arg
38650 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 63 61 6c  ument to the cal
38660 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20  lback is a copy 
38670 6f 66 20 74 68 65 20 74 68 69 72 64 20 61 72 67  of the third arg
38680 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c 69  ument.** to sqli
38690 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28  te3_update_hook(
386a0 29 2e 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e  )..** ^The secon
386b0 64 20 63 61 6c 6c 62 61 63 6b 20 61 72 67 75 6d  d callback argum
386c0 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53  ent is one of [S
386d0 51 4c 49 54 45 5f 49 4e 53 45 52 54 5d 2c 20 5b  QLITE_INSERT], [
386e0 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 2c 0a  SQLITE_DELETE],.
386f0 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 50  ** or [SQLITE_UP
38700 44 41 54 45 5d 2c 20 64 65 70 65 6e 64 69 6e 67  DATE], depending
38710 20 6f 6e 20 74 68 65 20 6f 70 65 72 61 74 69 6f   on the operatio
38720 6e 20 74 68 61 74 20 63 61 75 73 65 64 20 74 68  n that caused th
38730 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 6f  e callback.** to
38740 20 62 65 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 20   be invoked..** 
38750 5e 54 68 65 20 74 68 69 72 64 20 61 6e 64 20 66  ^The third and f
38760 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 73 20  ourth arguments 
38770 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  to the callback 
38780 63 6f 6e 74 61 69 6e 20 70 6f 69 6e 74 65 72 73  contain pointers
38790 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62   to the.** datab
387a0 61 73 65 20 61 6e 64 20 74