System.Data.SQLite
Hex Artifact Content
Not logged in

Artifact f38df08547efae0ff4343da607b723f588bbd66b:


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 36 2e 20 20 42  ersion 3.7.6.  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 36 22 0a 23 64 65 66 69     "3.7.6".#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 36  N_NUMBER 3007006
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 34 2d 31 32 20 30 31 3a 35 38  2011-04-12 01:58
5a20: 3a 34 30 20 66 39 64 34 33 66 61 33 36 33 64 35  :40 f9d43fa363d5
5a30: 34 62 65 61 62 36 66 34 35 64 62 30 30 35 61 62  4beab6f45db005ab
5a40: 61 63 30 61 37 63 30 63 34 37 61 37 22 0a 0a 2f  ac0a7c0c47a7"../
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 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63   to sqlite3_exec
7c10: 28 29 20 69 73 20 72 65 6c 61 79 65 64 20 74 68  () is relayed th
7c20: 72 6f 75 67 68 20 74 6f 20 74 68 65 20 31 73 74  rough to the 1st
7c30: 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 65 61 63   argument of eac
7c40: 68 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 6e  h.** callback in
7c50: 76 6f 63 61 74 69 6f 6e 2e 20 20 5e 49 66 20 74  vocation.  ^If t
7c60: 68 65 20 63 61 6c 6c 62 61 63 6b 20 70 6f 69 6e  he callback poin
7c70: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
7c80: 78 65 63 28 29 0a 2a 2a 20 69 73 20 4e 55 4c 4c  xec().** is NULL
7c90: 2c 20 74 68 65 6e 20 6e 6f 20 63 61 6c 6c 62 61  , then no callba
7ca0: 63 6b 20 69 73 20 65 76 65 72 20 69 6e 76 6f 6b  ck is ever invok
7cb0: 65 64 20 61 6e 64 20 72 65 73 75 6c 74 20 72 6f  ed and result ro
7cc0: 77 73 20 61 72 65 0a 2a 2a 20 69 67 6e 6f 72 65  ws are.** ignore
7cd0: 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20  d..**.** ^If an 
7ce0: 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 69  error occurs whi
7cf0: 6c 65 20 65 76 61 6c 75 61 74 69 6e 67 20 74 68  le evaluating th
7d00: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
7d10: 20 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20   passed into.** 
7d20: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 2c 20  sqlite3_exec(), 
7d30: 74 68 65 6e 20 65 78 65 63 75 74 69 6f 6e 20 6f  then execution o
7d40: 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74  f the current st
7d50: 61 74 65 6d 65 6e 74 20 73 74 6f 70 73 20 61 6e  atement stops an
7d60: 64 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20  d.** subsequent 
7d70: 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 73  statements are s
7d80: 6b 69 70 70 65 64 2e 20 20 5e 49 66 20 74 68 65  kipped.  ^If the
7d90: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   5th parameter t
7da0: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  o sqlite3_exec()
7db0: 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20  .** is not NULL 
7dc0: 74 68 65 6e 20 61 6e 79 20 65 72 72 6f 72 20 6d  then any error m
7dd0: 65 73 73 61 67 65 20 69 73 20 77 72 69 74 74 65  essage is writte
7de0: 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  n into memory ob
7df0: 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b  tained.** from [
7e00: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
7e10: 5d 20 61 6e 64 20 70 61 73 73 65 64 20 62 61 63  ] and passed bac
7e20: 6b 20 74 68 72 6f 75 67 68 20 74 68 65 20 35 74  k through the 5t
7e30: 68 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20  h parameter..** 
7e40: 54 6f 20 61 76 6f 69 64 20 6d 65 6d 6f 72 79 20  To avoid memory 
7e50: 6c 65 61 6b 73 2c 20 74 68 65 20 61 70 70 6c 69  leaks, the appli
7e60: 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 69 6e  cation should in
7e70: 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72  voke [sqlite3_fr
7e80: 65 65 28 29 5d 0a 2a 2a 20 6f 6e 20 65 72 72 6f  ee()].** on erro
7e90: 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67  r message string
7ea0: 73 20 72 65 74 75 72 6e 65 64 20 74 68 72 6f 75  s returned throu
7eb0: 67 68 20 74 68 65 20 35 74 68 20 70 61 72 61 6d  gh the 5th param
7ec0: 65 74 65 72 20 6f 66 0a 2a 2a 20 6f 66 20 73 71  eter of.** of sq
7ed0: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 61 66 74  lite3_exec() aft
7ee0: 65 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  er the error mes
7ef0: 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6e  sage string is n
7f00: 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64 2e  o longer needed.
7f10: 0a 2a 2a 20 5e 49 66 20 74 68 65 20 35 74 68 20  .** ^If the 5th 
7f20: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
7f30: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e  ite3_exec() is n
7f40: 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20 65  ot NULL and no e
7f50: 72 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72 2c 20  rrors.** occur, 
7f60: 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 65 78 65  then sqlite3_exe
7f70: 63 28 29 20 73 65 74 73 20 74 68 65 20 70 6f 69  c() sets the poi
7f80: 6e 74 65 72 20 69 6e 20 69 74 73 20 35 74 68 20  nter in its 5th 
7f90: 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
7fa0: 4e 55 4c 4c 20 62 65 66 6f 72 65 20 72 65 74 75  NULL before retu
7fb0: 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  rning..**.** ^If
7fc0: 20 61 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63   an sqlite3_exec
7fd0: 28 29 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  () callback retu
7fe0: 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68  rns non-zero, th
7ff0: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  e sqlite3_exec()
8000: 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75  .** routine retu
8010: 72 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f 52 54  rns SQLITE_ABORT
8020: 20 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b 69 6e   without invokin
8030: 67 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61  g the callback a
8040: 67 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69 74 68  gain and.** with
8050: 6f 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79 20  out running any 
8060: 73 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20 73  subsequent SQL s
8070: 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a  tatements..**.**
8080: 20 5e 54 68 65 20 32 6e 64 20 61 72 67 75 6d 65   ^The 2nd argume
8090: 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  nt to the sqlite
80a0: 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63  3_exec() callbac
80b0: 6b 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 68  k function is th
80c0: 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63  e.** number of c
80d0: 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65  olumns in the re
80e0: 73 75 6c 74 2e 20 20 5e 54 68 65 20 33 72 64 20  sult.  ^The 3rd 
80f0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
8100: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a  sqlite3_exec().*
8110: 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e  * callback is an
8120: 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65   array of pointe
8130: 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 6f 62  rs to strings ob
8140: 74 61 69 6e 65 64 20 61 73 20 69 66 20 66 72 6f  tained as if fro
8150: 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  m.** [sqlite3_co
8160: 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 6f 6e  lumn_text()], on
8170: 65 20 66 6f 72 20 65 61 63 68 20 63 6f 6c 75 6d  e for each colum
8180: 6e 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65 6d 65  n.  ^If an eleme
8190: 6e 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73 75 6c  nt of a.** resul
81a0: 74 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20 74 68  t row is NULL th
81b0: 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  en the correspon
81c0: 64 69 6e 67 20 73 74 72 69 6e 67 20 70 6f 69 6e  ding string poin
81d0: 74 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a 20 73  ter for the.** s
81e0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61  qlite3_exec() ca
81f0: 6c 6c 62 61 63 6b 20 69 73 20 61 20 4e 55 4c 4c  llback is a NULL
8200: 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20   pointer.  ^The 
8210: 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  4th argument to 
8220: 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65  the.** sqlite3_e
8230: 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 69  xec() callback i
8240: 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f  s an array of po
8250: 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67  inters to string
8260: 73 20 77 68 65 72 65 20 65 61 63 68 0a 2a 2a 20  s where each.** 
8270: 65 6e 74 72 79 20 72 65 70 72 65 73 65 6e 74 73  entry represents
8280: 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 63 6f 72   the name of cor
8290: 72 65 73 70 6f 6e 64 69 6e 67 20 72 65 73 75 6c  responding resul
82a0: 74 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62 74 61  t column as obta
82b0: 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71  ined.** from [sq
82c0: 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
82d0: 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  e()]..**.** ^If 
82e0: 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
82f0: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65  r to sqlite3_exe
8300: 63 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  c() is a NULL po
8310: 69 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74 65 72  inter, a pointer
8320: 0a 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74 79 20  .** to an empty 
8330: 73 74 72 69 6e 67 2c 20 6f 72 20 61 20 70 6f 69  string, or a poi
8340: 6e 74 65 72 20 74 68 61 74 20 63 6f 6e 74 61 69  nter that contai
8350: 6e 73 20 6f 6e 6c 79 20 77 68 69 74 65 73 70 61  ns only whitespa
8360: 63 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53 51  ce and/or .** SQ
8370: 4c 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65 6e  L comments, then
8380: 20 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   no SQL statemen
8390: 74 73 20 61 72 65 20 65 76 61 6c 75 61 74 65 64  ts are evaluated
83a0: 20 61 6e 64 20 74 68 65 20 64 61 74 61 62 61 73   and the databas
83b0: 65 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e  e.** is not chan
83c0: 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74 72  ged..**.** Restr
83d0: 69 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ictions:.**.** <
83e0: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  ul>.** <li> The 
83f0: 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
8400: 20 69 6e 73 75 72 65 20 74 68 61 74 20 74 68 65   insure that the
8410: 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 20 74   1st parameter t
8420: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  o sqlite3_exec()
8430: 0a 2a 2a 20 20 20 20 20 20 69 73 20 61 20 76 61  .**      is a va
8440: 6c 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b 64 61  lid and open [da
8450: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
8460: 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  n]..** <li> The 
8470: 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
8480: 20 6e 6f 74 20 63 6c 6f 73 65 20 5b 64 61 74 61   not close [data
8490: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
84a0: 20 73 70 65 63 69 66 69 65 64 20 62 79 0a 2a 2a   specified by.**
84b0: 20 20 20 20 20 20 74 68 65 20 31 73 74 20 70 61        the 1st pa
84c0: 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
84d0: 65 33 5f 65 78 65 63 28 29 20 77 68 69 6c 65 20  e3_exec() while 
84e0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
84f0: 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 6c  s running..** <l
8500: 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  i> The applicati
8510: 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 6d 6f 64 69  on must not modi
8520: 66 79 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  fy the SQL state
8530: 6d 65 6e 74 20 74 65 78 74 20 70 61 73 73 65 64  ment text passed
8540: 20 69 6e 74 6f 0a 2a 2a 20 20 20 20 20 20 74 68   into.**      th
8550: 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  e 2nd parameter 
8560: 6f 66 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  of sqlite3_exec(
8570: 29 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f  ) while sqlite3_
8580: 65 78 65 63 28 29 20 69 73 20 72 75 6e 6e 69 6e  exec() is runnin
8590: 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 53  g..** </ul>.*/.S
85a0: 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
85b0: 6c 69 74 65 33 5f 65 78 65 63 28 0a 20 20 73 71  lite3_exec(.  sq
85c0: 6c 69 74 65 33 2a 2c 20 20 20 20 20 20 20 20 20  lite3*,         
85d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
85e0: 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f           /* An o
85f0: 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a  pen database */.
8600: 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71    const char *sq
8610: 6c 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  l,              
8620: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
8630: 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61  SQL to be evalua
8640: 74 65 64 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 63  ted */.  int (*c
8650: 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69  allback)(void*,i
8660: 6e 74 2c 63 68 61 72 2a 2a 2c 63 68 61 72 2a 2a  nt,char**,char**
8670: 29 2c 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20  ),  /* Callback 
8680: 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f  function */.  vo
8690: 69 64 20 2a 2c 20 20 20 20 20 20 20 20 20 20 20  id *,           
86a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
86b0: 20 20 20 20 20 20 20 20 20 2f 2a 20 31 73 74 20           /* 1st 
86c0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c  argument to call
86d0: 62 61 63 6b 20 2a 2f 0a 20 20 63 68 61 72 20 2a  back */.  char *
86e0: 2a 65 72 72 6d 73 67 20 20 20 20 20 20 20 20 20  *errmsg         
86f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
8700: 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73       /* Error ms
8710: 67 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a  g written here *
8720: 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.);../*.** CAPI
8730: 33 52 45 46 3a 20 52 65 73 75 6c 74 20 43 6f 64  3REF: Result Cod
8740: 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  es.** KEYWORDS: 
8750: 53 51 4c 49 54 45 5f 4f 4b 20 7b 65 72 72 6f 72  SQLITE_OK {error
8760: 20 63 6f 64 65 7d 20 7b 65 72 72 6f 72 20 63 6f   code} {error co
8770: 64 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  des}.** KEYWORDS
8780: 3a 20 7b 72 65 73 75 6c 74 20 63 6f 64 65 7d 20  : {result code} 
8790: 7b 72 65 73 75 6c 74 20 63 6f 64 65 73 7d 0a 2a  {result codes}.*
87a0: 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51 4c 69 74 65  *.** Many SQLite
87b0: 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72   functions retur
87c0: 6e 20 61 6e 20 69 6e 74 65 67 65 72 20 72 65 73  n an integer res
87d0: 75 6c 74 20 63 6f 64 65 20 66 72 6f 6d 20 74 68  ult code from th
87e0: 65 20 73 65 74 20 73 68 6f 77 6e 0a 2a 2a 20 68  e set shown.** h
87f0: 65 72 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ere in order to 
8800: 69 6e 64 69 63 61 74 65 73 20 73 75 63 63 65 73  indicates succes
8810: 73 20 6f 72 20 66 61 69 6c 75 72 65 2e 0a 2a 2a  s or failure..**
8820: 0a 2a 2a 20 4e 65 77 20 65 72 72 6f 72 20 63 6f  .** New error co
8830: 64 65 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  des may be added
8840: 20 69 6e 20 66 75 74 75 72 65 20 76 65 72 73 69   in future versi
8850: 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ons of SQLite..*
8860: 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
8870: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41  SQLITE_IOERR_REA
8880: 44 20 7c 20 65 78 74 65 6e 64 65 64 20 72 65 73  D | extended res
8890: 75 6c 74 20 63 6f 64 65 73 5d 0a 2a 2f 0a 23 64  ult codes].*/.#d
88a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 4b 20  efine SQLITE_OK 
88b0: 20 20 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a            0   /*
88c0: 20 53 75 63 63 65 73 73 66 75 6c 20 72 65 73 75   Successful resu
88d0: 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67 69 6e 6e 69  lt */./* beginni
88e0: 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65  ng-of-error-code
88f0: 73 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  s */.#define SQL
8900: 49 54 45 5f 45 52 52 4f 52 20 20 20 20 20 20 20  ITE_ERROR       
8910: 20 31 20 20 20 2f 2a 20 53 51 4c 20 65 72 72 6f   1   /* SQL erro
8920: 72 20 6f 72 20 6d 69 73 73 69 6e 67 20 64 61 74  r or missing dat
8930: 61 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65  abase */.#define
8940: 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 4e 41 4c   SQLITE_INTERNAL
8950: 20 20 20 20 20 32 20 20 20 2f 2a 20 49 6e 74 65       2   /* Inte
8960: 72 6e 61 6c 20 6c 6f 67 69 63 20 65 72 72 6f 72  rnal logic error
8970: 20 69 6e 20 53 51 4c 69 74 65 20 2a 2f 0a 23 64   in SQLite */.#d
8980: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 45 52  efine SQLITE_PER
8990: 4d 20 20 20 20 20 20 20 20 20 33 20 20 20 2f 2a  M         3   /*
89a0: 20 41 63 63 65 73 73 20 70 65 72 6d 69 73 73 69   Access permissi
89b0: 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65  on denied */.#de
89c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 42 4f 52  fine SQLITE_ABOR
89d0: 54 20 20 20 20 20 20 20 20 34 20 20 20 2f 2a 20  T        4   /* 
89e0: 43 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65  Callback routine
89f0: 20 72 65 71 75 65 73 74 65 64 20 61 6e 20 61 62   requested an ab
8a00: 6f 72 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ort */.#define S
8a10: 51 4c 49 54 45 5f 42 55 53 59 20 20 20 20 20 20  QLITE_BUSY      
8a20: 20 20 20 35 20 20 20 2f 2a 20 54 68 65 20 64 61     5   /* The da
8a30: 74 61 62 61 73 65 20 66 69 6c 65 20 69 73 20 6c  tabase file is l
8a40: 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  ocked */.#define
8a50: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 20   SQLITE_LOCKED  
8a60: 20 20 20 20 20 36 20 20 20 2f 2a 20 41 20 74 61       6   /* A ta
8a70: 62 6c 65 20 69 6e 20 74 68 65 20 64 61 74 61 62  ble in the datab
8a80: 61 73 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f  ase is locked */
8a90: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
8aa0: 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 37 20 20  NOMEM        7  
8ab0: 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63 28 29 20 66   /* A malloc() f
8ac0: 61 69 6c 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  ailed */.#define
8ad0: 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59   SQLITE_READONLY
8ae0: 20 20 20 20 20 38 20 20 20 2f 2a 20 41 74 74 65       8   /* Atte
8af0: 6d 70 74 20 74 6f 20 77 72 69 74 65 20 61 20 72  mpt to write a r
8b00: 65 61 64 6f 6e 6c 79 20 64 61 74 61 62 61 73 65  eadonly database
8b10: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
8b20: 54 45 5f 49 4e 54 45 52 52 55 50 54 20 20 20 20  TE_INTERRUPT    
8b30: 39 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e  9   /* Operation
8b40: 20 74 65 72 6d 69 6e 61 74 65 64 20 62 79 20 73   terminated by s
8b50: 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
8b60: 28 29 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ()*/.#define SQL
8b70: 49 54 45 5f 49 4f 45 52 52 20 20 20 20 20 20 20  ITE_IOERR       
8b80: 31 30 20 20 20 2f 2a 20 53 6f 6d 65 20 6b 69 6e  10   /* Some kin
8b90: 64 20 6f 66 20 64 69 73 6b 20 49 2f 4f 20 65 72  d of disk I/O er
8ba0: 72 6f 72 20 6f 63 63 75 72 72 65 64 20 2a 2f 0a  ror occurred */.
8bb0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
8bc0: 4f 52 52 55 50 54 20 20 20 20 20 31 31 20 20 20  ORRUPT     11   
8bd0: 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20  /* The database 
8be0: 64 69 73 6b 20 69 6d 61 67 65 20 69 73 20 6d 61  disk image is ma
8bf0: 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23 64 65 66 69  lformed */.#defi
8c00: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55  ne SQLITE_NOTFOU
8c10: 4e 44 20 20 20 20 31 32 20 20 20 2f 2a 20 55 6e  ND    12   /* Un
8c20: 6b 6e 6f 77 6e 20 6f 70 63 6f 64 65 20 69 6e 20  known opcode in 
8c30: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
8c40: 74 72 6f 6c 28 29 20 2a 2f 0a 23 64 65 66 69 6e  trol() */.#defin
8c50: 65 20 53 51 4c 49 54 45 5f 46 55 4c 4c 20 20 20  e SQLITE_FULL   
8c60: 20 20 20 20 20 31 33 20 20 20 2f 2a 20 49 6e 73       13   /* Ins
8c70: 65 72 74 69 6f 6e 20 66 61 69 6c 65 64 20 62 65  ertion failed be
8c80: 63 61 75 73 65 20 64 61 74 61 62 61 73 65 20 69  cause database i
8c90: 73 20 66 75 6c 6c 20 2a 2f 0a 23 64 65 66 69 6e  s full */.#defin
8ca0: 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45  e SQLITE_CANTOPE
8cb0: 4e 20 20 20 20 31 34 20 20 20 2f 2a 20 55 6e 61  N    14   /* Una
8cc0: 62 6c 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 20  ble to open the 
8cd0: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f  database file */
8ce0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
8cf0: 50 52 4f 54 4f 43 4f 4c 20 20 20 20 31 35 20 20  PROTOCOL    15  
8d00: 20 2f 2a 20 44 61 74 61 62 61 73 65 20 6c 6f 63   /* Database loc
8d10: 6b 20 70 72 6f 74 6f 63 6f 6c 20 65 72 72 6f 72  k protocol error
8d20: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
8d30: 54 45 5f 45 4d 50 54 59 20 20 20 20 20 20 20 31  TE_EMPTY       1
8d40: 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  6   /* Database 
8d50: 69 73 20 65 6d 70 74 79 20 2a 2f 0a 23 64 65 66  is empty */.#def
8d60: 69 6e 65 20 53 51 4c 49 54 45 5f 53 43 48 45 4d  ine SQLITE_SCHEM
8d70: 41 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20 54  A      17   /* T
8d80: 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65  he database sche
8d90: 6d 61 20 63 68 61 6e 67 65 64 20 2a 2f 0a 23 64  ma changed */.#d
8da0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 4f 4f  efine SQLITE_TOO
8db0: 42 49 47 20 20 20 20 20 20 31 38 20 20 20 2f 2a  BIG      18   /*
8dc0: 20 53 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20   String or BLOB 
8dd0: 65 78 63 65 65 64 73 20 73 69 7a 65 20 6c 69 6d  exceeds size lim
8de0: 69 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  it */.#define SQ
8df0: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
8e00: 20 31 39 20 20 20 2f 2a 20 41 62 6f 72 74 20 64   19   /* Abort d
8e10: 75 65 20 74 6f 20 63 6f 6e 73 74 72 61 69 6e 74  ue to constraint
8e20: 20 76 69 6f 6c 61 74 69 6f 6e 20 2a 2f 0a 23 64   violation */.#d
8e30: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53  efine SQLITE_MIS
8e40: 4d 41 54 43 48 20 20 20 20 32 30 20 20 20 2f 2a  MATCH    20   /*
8e50: 20 44 61 74 61 20 74 79 70 65 20 6d 69 73 6d 61   Data type misma
8e60: 74 63 68 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  tch */.#define S
8e70: 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 20 20 20  QLITE_MISUSE    
8e80: 20 20 32 31 20 20 20 2f 2a 20 4c 69 62 72 61 72    21   /* Librar
8e90: 79 20 75 73 65 64 20 69 6e 63 6f 72 72 65 63 74  y used incorrect
8ea0: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
8eb0: 4c 49 54 45 5f 4e 4f 4c 46 53 20 20 20 20 20 20  LITE_NOLFS      
8ec0: 20 32 32 20 20 20 2f 2a 20 55 73 65 73 20 4f 53   22   /* Uses OS
8ed0: 20 66 65 61 74 75 72 65 73 20 6e 6f 74 20 73 75   features not su
8ee0: 70 70 6f 72 74 65 64 20 6f 6e 20 68 6f 73 74 20  pported on host 
8ef0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
8f00: 45 5f 41 55 54 48 20 20 20 20 20 20 20 20 32 33  E_AUTH        23
8f10: 20 20 20 2f 2a 20 41 75 74 68 6f 72 69 7a 61 74     /* Authorizat
8f20: 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64  ion denied */.#d
8f30: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4f 52  efine SQLITE_FOR
8f40: 4d 41 54 20 20 20 20 20 20 32 34 20 20 20 2f 2a  MAT      24   /*
8f50: 20 41 75 78 69 6c 69 61 72 79 20 64 61 74 61 62   Auxiliary datab
8f60: 61 73 65 20 66 6f 72 6d 61 74 20 65 72 72 6f 72  ase format error
8f70: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
8f80: 54 45 5f 52 41 4e 47 45 20 20 20 20 20 20 20 32  TE_RANGE       2
8f90: 35 20 20 20 2f 2a 20 32 6e 64 20 70 61 72 61 6d  5   /* 2nd param
8fa0: 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
8fb0: 62 69 6e 64 20 6f 75 74 20 6f 66 20 72 61 6e 67  bind out of rang
8fc0: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
8fd0: 49 54 45 5f 4e 4f 54 41 44 42 20 20 20 20 20 20  ITE_NOTADB      
8fe0: 32 36 20 20 20 2f 2a 20 46 69 6c 65 20 6f 70 65  26   /* File ope
8ff0: 6e 65 64 20 74 68 61 74 20 69 73 20 6e 6f 74 20  ned that is not 
9000: 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  a database file 
9010: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
9020: 45 5f 52 4f 57 20 20 20 20 20 20 20 20 20 31 30  E_ROW         10
9030: 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74  0  /* sqlite3_st
9040: 65 70 28 29 20 68 61 73 20 61 6e 6f 74 68 65 72  ep() has another
9050: 20 72 6f 77 20 72 65 61 64 79 20 2a 2f 0a 23 64   row ready */.#d
9060: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 4f 4e  efine SQLITE_DON
9070: 45 20 20 20 20 20 20 20 20 31 30 31 20 20 2f 2a  E        101  /*
9080: 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
9090: 68 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 65  has finished exe
90a0: 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64  cuting */./* end
90b0: 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20  -of-error-codes 
90c0: 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
90d0: 45 46 3a 20 45 78 74 65 6e 64 65 64 20 52 65 73  EF: Extended Res
90e0: 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59  ult Codes.** KEY
90f0: 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64 65 64  WORDS: {extended
9100: 20 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65 78   error code} {ex
9110: 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64  tended error cod
9120: 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  es}.** KEYWORDS:
9130: 20 7b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   {extended resul
9140: 74 20 63 6f 64 65 7d 20 7b 65 78 74 65 6e 64 65  t code} {extende
9150: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 7d 0a  d result codes}.
9160: 2a 2a 0a 2a 2a 20 49 6e 20 69 74 73 20 64 65 66  **.** In its def
9170: 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69  ault configurati
9180: 6f 6e 2c 20 53 51 4c 69 74 65 20 41 50 49 20 72  on, SQLite API r
9190: 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 6f  outines return o
91a0: 6e 65 20 6f 66 20 32 36 20 69 6e 74 65 67 65 72  ne of 26 integer
91b0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 20 7c  .** [SQLITE_OK |
91c0: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 2e 20   result codes]. 
91d0: 20 48 6f 77 65 76 65 72 2c 20 65 78 70 65 72 69   However, experi
91e0: 65 6e 63 65 20 68 61 73 20 73 68 6f 77 6e 20 74  ence has shown t
91f0: 68 61 74 20 6d 61 6e 79 20 6f 66 0a 2a 2a 20 74  hat many of.** t
9200: 68 65 73 65 20 72 65 73 75 6c 74 20 63 6f 64 65  hese result code
9210: 73 20 61 72 65 20 74 6f 6f 20 63 6f 61 72 73 65  s are too coarse
9220: 2d 67 72 61 69 6e 65 64 2e 20 20 54 68 65 79 20  -grained.  They 
9230: 64 6f 20 6e 6f 74 20 70 72 6f 76 69 64 65 20 61  do not provide a
9240: 73 0a 2a 2a 20 6d 75 63 68 20 69 6e 66 6f 72 6d  s.** much inform
9250: 61 74 69 6f 6e 20 61 62 6f 75 74 20 70 72 6f 62  ation about prob
9260: 6c 65 6d 73 20 61 73 20 70 72 6f 67 72 61 6d 6d  lems as programm
9270: 65 72 73 20 6d 69 67 68 74 20 6c 69 6b 65 2e 20  ers might like. 
9280: 20 49 6e 20 61 6e 20 65 66 66 6f 72 74 20 74 6f   In an effort to
9290: 0a 2a 2a 20 61 64 64 72 65 73 73 20 74 68 69 73  .** address this
92a0: 2c 20 6e 65 77 65 72 20 76 65 72 73 69 6f 6e 73  , newer versions
92b0: 20 6f 66 20 53 51 4c 69 74 65 20 28 76 65 72 73   of SQLite (vers
92c0: 69 6f 6e 20 33 2e 33 2e 38 20 61 6e 64 20 6c 61  ion 3.3.8 and la
92d0: 74 65 72 29 20 69 6e 63 6c 75 64 65 0a 2a 2a 20  ter) include.** 
92e0: 73 75 70 70 6f 72 74 20 66 6f 72 20 61 64 64 69  support for addi
92f0: 74 69 6f 6e 61 6c 20 72 65 73 75 6c 74 20 63 6f  tional result co
9300: 64 65 73 20 74 68 61 74 20 70 72 6f 76 69 64 65  des that provide
9310: 20 6d 6f 72 65 20 64 65 74 61 69 6c 65 64 20 69   more detailed i
9320: 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62  nformation.** ab
9330: 6f 75 74 20 65 72 72 6f 72 73 2e 20 54 68 65 20  out errors. The 
9340: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
9350: 63 6f 64 65 73 20 61 72 65 20 65 6e 61 62 6c 65  codes are enable
9360: 64 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a  d or disabled.**
9370: 20 6f 6e 20 61 20 70 65 72 20 64 61 74 61 62 61   on a per databa
9380: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61  se connection ba
9390: 73 69 73 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a  sis using the.**
93a0: 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64   [sqlite3_extend
93b0: 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28  ed_result_codes(
93c0: 29 5d 20 41 50 49 2e 0a 2a 2a 0a 2a 2a 20 53 6f  )] API..**.** So
93d0: 6d 65 20 6f 66 20 74 68 65 20 61 76 61 69 6c 61  me of the availa
93e0: 62 6c 65 20 65 78 74 65 6e 64 65 64 20 72 65 73  ble extended res
93f0: 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 6c 69  ult codes are li
9400: 73 74 65 64 20 68 65 72 65 2e 0a 2a 2a 20 4f 6e  sted here..** On
9410: 65 20 6d 61 79 20 65 78 70 65 63 74 20 74 68 65  e may expect the
9420: 20 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 65 6e   number of exten
9430: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
9440: 20 77 69 6c 6c 20 62 65 20 65 78 70 61 6e 64 0a   will be expand.
9450: 2a 2a 20 6f 76 65 72 20 74 69 6d 65 2e 20 20 53  ** over time.  S
9460: 6f 66 74 77 61 72 65 20 74 68 61 74 20 75 73 65  oftware that use
9470: 73 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c  s extended resul
9480: 74 20 63 6f 64 65 73 20 73 68 6f 75 6c 64 20 65  t codes should e
9490: 78 70 65 63 74 0a 2a 2a 20 74 6f 20 73 65 65 20  xpect.** to see 
94a0: 6e 65 77 20 72 65 73 75 6c 74 20 63 6f 64 65 73  new result codes
94b0: 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
94c0: 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ses of SQLite..*
94d0: 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f  *.** The SQLITE_
94e0: 4f 4b 20 72 65 73 75 6c 74 20 63 6f 64 65 20 77  OK result code w
94f0: 69 6c 6c 20 6e 65 76 65 72 20 62 65 20 65 78 74  ill never be ext
9500: 65 6e 64 65 64 2e 20 20 49 74 20 77 69 6c 6c 20  ended.  It will 
9510: 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20 65 78 61  always.** be exa
9520: 63 74 6c 79 20 7a 65 72 6f 2e 0a 2a 2f 0a 23 64  ctly zero..*/.#d
9530: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
9540: 52 52 5f 52 45 41 44 20 20 20 20 20 20 20 20 20  RR_READ         
9550: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
9560: 52 52 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65  RR | (1<<8)).#de
9570: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
9580: 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 20 20 20  R_SHORT_READ    
9590: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
95a0: 52 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66  R | (2<<8)).#def
95b0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
95c0: 5f 57 52 49 54 45 20 20 20 20 20 20 20 20 20 20  _WRITE          
95d0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
95e0: 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69   | (3<<8)).#defi
95f0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
9600: 46 53 59 4e 43 20 20 20 20 20 20 20 20 20 20 20  FSYNC           
9610: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
9620: 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (4<<8)).#defin
9630: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44  e SQLITE_IOERR_D
9640: 49 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20  IR_FSYNC        
9650: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
9660: 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (5<<8)).#define
9670: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 54 52   SQLITE_IOERR_TR
9680: 55 4e 43 41 54 45 20 20 20 20 20 20 20 20 20 20  UNCATE          
9690: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
96a0: 28 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (6<<8)).#define 
96b0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 54  SQLITE_IOERR_FST
96c0: 41 54 20 20 20 20 20 20 20 20 20 20 20 20 20 28  AT             (
96d0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
96e0: 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  7<<8)).#define S
96f0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 55 4e 4c 4f  QLITE_IOERR_UNLO
9700: 43 4b 20 20 20 20 20 20 20 20 20 20 20 20 28 53  CK            (S
9710: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 38  QLITE_IOERR | (8
9720: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
9730: 4c 49 54 45 5f 49 4f 45 52 52 5f 52 44 4c 4f 43  LITE_IOERR_RDLOC
9740: 4b 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51  K            (SQ
9750: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 39 3c  LITE_IOERR | (9<
9760: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
9770: 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45  ITE_IOERR_DELETE
9780: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
9790: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 30 3c  ITE_IOERR | (10<
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 42 4c 4f 43 4b 45  ITE_IOERR_BLOCKE
97c0: 44 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  D           (SQL
97d0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 31 3c  ITE_IOERR | (11<
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 4e 4f 4d 45 4d 20  ITE_IOERR_NOMEM 
9800: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
9810: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 32 3c  ITE_IOERR | (12<
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 41 43 43 45 53 53  ITE_IOERR_ACCESS
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 33 3c  ITE_IOERR | (13<
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 43 48 45 43 4b 52  ITE_IOERR_CHECKR
9880: 45 53 45 52 56 45 44 4c 4f 43 4b 20 28 53 51 4c  ESERVEDLOCK (SQL
9890: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 34 3c  ITE_IOERR | (14<
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 4c 4f 43 4b 20 20  ITE_IOERR_LOCK  
98c0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
98d0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 35 3c  ITE_IOERR | (15<
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 43 4c 4f 53 45 20  ITE_IOERR_CLOSE 
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 36 3c  ITE_IOERR | (16<
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 44 49 52 5f 43 4c  ITE_IOERR_DIR_CL
9940: 4f 53 45 20 20 20 20 20 20 20 20 20 28 53 51 4c  OSE         (SQL
9950: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 37 3c  ITE_IOERR | (17<
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 53 48 4d 4f 50 45  ITE_IOERR_SHMOPE
9980: 4e 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  N           (SQL
9990: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 38 3c  ITE_IOERR | (18<
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 53 49 5a  ITE_IOERR_SHMSIZ
99c0: 45 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  E           (SQL
99d0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 39 3c  ITE_IOERR | (19<
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 4c 4f 43  ITE_IOERR_SHMLOC
9a00: 4b 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  K           (SQL
9a10: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 30 3c  ITE_IOERR | (20<
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 4c 4f 43 4b 45 44 5f 53 48 41 52 45  ITE_LOCKED_SHARE
9a40: 44 43 41 43 48 45 20 20 20 20 20 20 28 53 51 4c  DCACHE      (SQL
9a50: 49 54 45 5f 4c 4f 43 4b 45 44 20 7c 20 20 28 31  ITE_LOCKED |  (1
9a60: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
9a70: 4c 49 54 45 5f 42 55 53 59 5f 52 45 43 4f 56 45  LITE_BUSY_RECOVE
9a80: 52 59 20 20 20 20 20 20 20 20 20 20 20 28 53 51  RY           (SQ
9a90: 4c 49 54 45 5f 42 55 53 59 20 20 20 7c 20 20 28  LITE_BUSY   |  (
9aa0: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
9ab0: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 4e  QLITE_CANTOPEN_N
9ac0: 4f 54 45 4d 50 44 49 52 20 20 20 20 20 20 28 53  OTEMPDIR      (S
9ad0: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c  QLITE_CANTOPEN |
9ae0: 20 28 31 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20   (1<<8))../*.** 
9af0: 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20  CAPI3REF: Flags 
9b00: 46 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70  For File Open Op
9b10: 65 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54  erations.**.** T
9b20: 68 65 73 65 20 62 69 74 20 76 61 6c 75 65 73 20  hese bit values 
9b30: 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72  are intended for
9b40: 20 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33   use in the.** 3
9b50: 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
9b60: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  the [sqlite3_ope
9b70: 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63  n_v2()] interfac
9b80: 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20  e and.** in the 
9b90: 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  4th parameter to
9ba0: 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f   the xOpen metho
9bb0: 64 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  d of the.** [sql
9bc0: 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
9bd0: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
9be0: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
9bf0: 59 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30  Y         0x0000
9c00: 30 30 30 31 20 20 2f 2a 20 4f 6b 20 66 6f 72 20  0001  /* Ok for 
9c10: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
9c20: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
9c30: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
9c40: 54 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30  TE        0x0000
9c50: 30 30 30 32 20 20 2f 2a 20 4f 6b 20 66 6f 72 20  0002  /* Ok for 
9c60: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
9c70: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
9c80: 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20  ITE_OPEN_CREATE 
9c90: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
9ca0: 30 30 30 34 20 20 2f 2a 20 4f 6b 20 66 6f 72 20  0004  /* Ok for 
9cb0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
9cc0: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
9cd0: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
9ce0: 4e 43 4c 4f 53 45 20 20 20 20 30 78 30 30 30 30  NCLOSE    0x0000
9cf0: 30 30 30 38 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  0008  /* VFS onl
9d00: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
9d10: 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49  ITE_OPEN_EXCLUSI
9d20: 56 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30  VE        0x0000
9d30: 30 30 31 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  0010  /* VFS onl
9d40: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
9d50: 49 54 45 5f 4f 50 45 4e 5f 41 55 54 4f 50 52 4f  ITE_OPEN_AUTOPRO
9d60: 58 59 20 20 20 20 20 20 20 20 30 78 30 30 30 30  XY        0x0000
9d70: 30 30 32 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  0020  /* VFS onl
9d80: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
9d90: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42  ITE_OPEN_MAIN_DB
9da0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
9db0: 30 31 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  0100  /* VFS onl
9dc0: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
9dd0: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42  ITE_OPEN_TEMP_DB
9de0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
9df0: 30 32 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  0200  /* VFS onl
9e00: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
9e10: 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45  ITE_OPEN_TRANSIE
9e20: 4e 54 5f 44 42 20 20 20 20 20 30 78 30 30 30 30  NT_DB     0x0000
9e30: 30 34 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  0400  /* VFS onl
9e40: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
9e50: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f  ITE_OPEN_MAIN_JO
9e60: 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30  URNAL     0x0000
9e70: 30 38 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  0800  /* VFS onl
9e80: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
9e90: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f  ITE_OPEN_TEMP_JO
9ea0: 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30  URNAL     0x0000
9eb0: 31 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  1000  /* VFS onl
9ec0: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
9ed0: 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52  ITE_OPEN_SUBJOUR
9ee0: 4e 41 4c 20 20 20 20 20 20 20 30 78 30 30 30 30  NAL       0x0000
9ef0: 32 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  2000  /* VFS onl
9f00: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
9f10: 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f  ITE_OPEN_MASTER_
9f20: 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30 30 30 30  JOURNAL   0x0000
9f30: 34 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  4000  /* VFS onl
9f40: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
9f50: 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58  ITE_OPEN_NOMUTEX
9f60: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
9f70: 38 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20  8000  /* Ok for 
9f80: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
9f90: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
9fa0: 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54  ITE_OPEN_FULLMUT
9fb0: 45 58 20 20 20 20 20 20 20 20 30 78 30 30 30 31  EX        0x0001
9fc0: 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20  0000  /* Ok for 
9fd0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
9fe0: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
9ff0: 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43  ITE_OPEN_SHAREDC
a000: 41 43 48 45 20 20 20 20 20 20 30 78 30 30 30 32  ACHE      0x0002
a010: 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20  0000  /* Ok for 
a020: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
a030: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
a040: 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45  ITE_OPEN_PRIVATE
a050: 43 41 43 48 45 20 20 20 20 20 30 78 30 30 30 34  CACHE     0x0004
a060: 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20  0000  /* Ok for 
a070: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
a080: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
a090: 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 20 20 20 20  ITE_OPEN_WAL    
a0a0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 38            0x0008
a0b0: 30 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  0000  /* VFS onl
a0c0: 79 20 2a 2f 0a 0a 2f 2a 20 52 65 73 65 72 76 65  y */../* Reserve
a0d0: 64 3a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  d:              
a0e0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 46             0x00F
a0f0: 30 30 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  00000 */../*.** 
a100: 43 41 50 49 33 52 45 46 3a 20 44 65 76 69 63 65  CAPI3REF: Device
a110: 20 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73   Characteristics
a120: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76 69  .**.** The xDevi
a130: 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63  ceCharacteristic
a140: 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20  s method of the 
a150: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
a160: 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72  ods].** object r
a170: 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65  eturns an intege
a180: 72 20 77 68 69 63 68 20 69 73 20 61 20 76 65 63  r which is a vec
a190: 74 6f 72 20 6f 66 20 74 68 65 20 74 68 65 73 65  tor of the these
a1a0: 0a 2a 2a 20 62 69 74 20 76 61 6c 75 65 73 20 65  .** bit values e
a1b0: 78 70 72 65 73 73 69 6e 67 20 49 2f 4f 20 63 68  xpressing I/O ch
a1c0: 61 72 61 63 74 65 72 69 73 74 69 63 73 20 6f 66  aracteristics of
a1d0: 20 74 68 65 20 6d 61 73 73 20 73 74 6f 72 61 67   the mass storag
a1e0: 65 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74  e.** device that
a1f0: 20 68 6f 6c 64 73 20 74 68 65 20 66 69 6c 65 20   holds the file 
a200: 74 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65  that the [sqlite
a210: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a  3_io_methods].**
a220: 20 72 65 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a   refers to..**.*
a230: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43  * The SQLITE_IOC
a240: 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72  AP_ATOMIC proper
a250: 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c  ty means that al
a260: 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61  l writes of.** a
a270: 6e 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d  ny size are atom
a280: 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  ic.  The SQLITE_
a290: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20  IOCAP_ATOMICnnn 
a2a0: 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74  values.** mean t
a2b0: 68 61 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c  hat writes of bl
a2c0: 6f 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e  ocks that are nn
a2d0: 6e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20  n bytes in size 
a2e0: 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e  and.** are align
a2f0: 65 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73  ed to an address
a300: 20 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74   which is an int
a310: 65 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66  eger multiple of
a320: 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d  .** nnn are atom
a330: 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  ic.  The SQLITE_
a340: 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e  IOCAP_SAFE_APPEN
a350: 44 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a  D value means.**
a360: 20 74 68 61 74 20 77 68 65 6e 20 64 61 74 61 20   that when data 
a370: 69 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61  is appended to a
a380: 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20   file, the data 
a390: 69 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66  is appended.** f
a3a0: 69 72 73 74 20 74 68 65 6e 20 74 68 65 20 73 69  irst then the si
a3b0: 7a 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69  ze of the file i
a3c0: 73 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65  s extended, neve
a3d0: 72 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77  r the other.** w
a3e0: 61 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20  ay around.  The 
a3f0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51  SQLITE_IOCAP_SEQ
a400: 55 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79  UENTIAL property
a410: 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69   means that.** i
a420: 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72  nformation is wr
a430: 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e  itten to disk in
a440: 20 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20   the same order 
a450: 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78  as calls.** to x
a460: 57 72 69 74 65 28 29 2e 0a 2a 2f 0a 23 64 65 66  Write()..*/.#def
a470: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
a480: 5f 41 54 4f 4d 49 43 20 20 20 20 20 20 20 20 20  _ATOMIC         
a490: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
a4a0: 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  01.#define SQLIT
a4b0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31  E_IOCAP_ATOMIC51
a4c0: 32 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30  2              0
a4d0: 78 30 30 30 30 30 30 30 32 0a 23 64 65 66 69 6e  x00000002.#defin
a4e0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
a4f0: 54 4f 4d 49 43 31 4b 20 20 20 20 20 20 20 20 20  TOMIC1K         
a500: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34        0x00000004
a510: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
a520: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 20 20  IOCAP_ATOMIC2K  
a530: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
a540: 30 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20  0000008.#define 
a550: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
a560: 4d 49 43 34 4b 20 20 20 20 20 20 20 20 20 20 20  MIC4K           
a570: 20 20 20 20 30 78 30 30 30 30 30 30 31 30 0a 23      0x00000010.#
a580: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
a590: 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20 20 20 20  CAP_ATOMIC8K    
a5a0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
a5b0: 30 30 30 32 30 0a 23 64 65 66 69 6e 65 20 53 51  00020.#define SQ
a5c0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
a5d0: 43 31 36 4b 20 20 20 20 20 20 20 20 20 20 20 20  C16K            
a5e0: 20 20 30 78 30 30 30 30 30 30 34 30 0a 23 64 65    0x00000040.#de
a5f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
a600: 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20 20 20  P_ATOMIC32K     
a610: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
a620: 30 38 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  080.#define SQLI
a630: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36  TE_IOCAP_ATOMIC6
a640: 34 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  4K              
a650: 30 78 30 30 30 30 30 31 30 30 0a 23 64 65 66 69  0x00000100.#defi
a660: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
a670: 53 41 46 45 5f 41 50 50 45 4e 44 20 20 20 20 20  SAFE_APPEND     
a680: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30         0x0000020
a690: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
a6a0: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41  _IOCAP_SEQUENTIA
a6b0: 4c 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78  L             0x
a6c0: 30 30 30 30 30 34 30 30 0a 23 64 65 66 69 6e 65  00000400.#define
a6d0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e   SQLITE_IOCAP_UN
a6e0: 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f  DELETABLE_WHEN_O
a6f0: 50 45 4e 20 20 30 78 30 30 30 30 30 38 30 30 0a  PEN  0x00000800.
a700: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
a710: 20 46 69 6c 65 20 4c 6f 63 6b 69 6e 67 20 4c 65   File Locking Le
a720: 76 65 6c 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  vels.**.** SQLit
a730: 65 20 75 73 65 73 20 6f 6e 65 20 6f 66 20 74 68  e uses one of th
a740: 65 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75  ese integer valu
a750: 65 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  es as the second
a760: 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  .** argument to 
a770: 63 61 6c 6c 73 20 69 74 20 6d 61 6b 65 73 20 74  calls it makes t
a780: 6f 20 74 68 65 20 78 4c 6f 63 6b 28 29 20 61 6e  o the xLock() an
a790: 64 20 78 55 6e 6c 6f 63 6b 28 29 20 6d 65 74 68  d xUnlock() meth
a7a0: 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73 71  ods.** of an [sq
a7b0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
a7c0: 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65  ] object..*/.#de
a7d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
a7e0: 5f 4e 4f 4e 45 20 20 20 20 20 20 20 20 20 20 30  _NONE          0
a7f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
a800: 4c 4f 43 4b 5f 53 48 41 52 45 44 20 20 20 20 20  LOCK_SHARED     
a810: 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c     1.#define SQL
a820: 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45  ITE_LOCK_RESERVE
a830: 44 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65  D      2.#define
a840: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e   SQLITE_LOCK_PEN
a850: 44 49 4e 47 20 20 20 20 20 20 20 33 0a 23 64 65  DING       3.#de
a860: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
a870: 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 20 34  _EXCLUSIVE     4
a880: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
a890: 3a 20 53 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f  : Synchronizatio
a8a0: 6e 20 54 79 70 65 20 46 6c 61 67 73 0a 2a 2a 0a  n Type Flags.**.
a8b0: 2a 2a 20 57 68 65 6e 20 53 51 4c 69 74 65 20 69  ** When SQLite i
a8c0: 6e 76 6f 6b 65 73 20 74 68 65 20 78 53 79 6e 63  nvokes the xSync
a8d0: 28 29 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 0a  () method of an.
a8e0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  ** [sqlite3_io_m
a8f0: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 69  ethods] object i
a900: 74 20 75 73 65 73 20 61 20 63 6f 6d 62 69 6e 61  t uses a combina
a910: 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65 73 65  tion of.** these
a920: 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20   integer values 
a930: 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  as the second ar
a940: 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68  gument..**.** Wh
a950: 65 6e 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59  en the SQLITE_SY
a960: 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 66 6c 61 67  NC_DATAONLY flag
a970: 20 69 73 20 75 73 65 64 2c 20 69 74 20 6d 65 61   is used, it mea
a980: 6e 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 73  ns that the.** s
a990: 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 20 6f 6e  ync operation on
a9a0: 6c 79 20 6e 65 65 64 73 20 74 6f 20 66 6c 75 73  ly needs to flus
a9b0: 68 20 64 61 74 61 20 74 6f 20 6d 61 73 73 20 73  h data to mass s
a9c0: 74 6f 72 61 67 65 2e 20 20 49 6e 6f 64 65 0a 2a  torage.  Inode.*
a9d0: 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6e 65  * information ne
a9e0: 65 64 20 6e 6f 74 20 62 65 20 66 6c 75 73 68 65  ed not be flushe
a9f0: 64 2e 20 49 66 20 74 68 65 20 6c 6f 77 65 72 20  d. If the lower 
aa00: 66 6f 75 72 20 62 69 74 73 20 6f 66 20 74 68 65  four bits of the
aa10: 20 66 6c 61 67 0a 2a 2a 20 65 71 75 61 6c 20 53   flag.** equal S
aa20: 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41  QLITE_SYNC_NORMA
aa30: 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 6f  L, that means to
aa40: 20 75 73 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e   use normal fsyn
aa50: 63 28 29 20 73 65 6d 61 6e 74 69 63 73 2e 0a 2a  c() semantics..*
aa60: 2a 20 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66  * If the lower f
aa70: 6f 75 72 20 62 69 74 73 20 65 71 75 61 6c 20 53  our bits equal S
aa80: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c  QLITE_SYNC_FULL,
aa90: 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74   that means.** t
aaa0: 6f 20 75 73 65 20 4d 61 63 20 4f 53 20 58 20 73  o use Mac OS X s
aab0: 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 20 69 6e  tyle fullsync in
aac0: 73 74 65 61 64 20 6f 66 20 66 73 79 6e 63 28 29  stead of fsync()
aad0: 2e 0a 2a 2a 0a 2a 2a 20 44 6f 20 6e 6f 74 20 63  ..**.** Do not c
aae0: 6f 6e 66 75 73 65 20 74 68 65 20 53 51 4c 49 54  onfuse the SQLIT
aaf0: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e  E_SYNC_NORMAL an
ab00: 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55  d SQLITE_SYNC_FU
ab10: 4c 4c 20 66 6c 61 67 73 0a 2a 2a 20 77 69 74 68  LL flags.** with
ab20: 20 74 68 65 20 5b 50 52 41 47 4d 41 20 73 79 6e   the [PRAGMA syn
ab30: 63 68 72 6f 6e 6f 75 73 5d 3d 4e 4f 52 4d 41 4c  chronous]=NORMAL
ab40: 20 61 6e 64 20 5b 50 52 41 47 4d 41 20 73 79 6e   and [PRAGMA syn
ab50: 63 68 72 6f 6e 6f 75 73 5d 3d 46 55 4c 4c 0a 2a  chronous]=FULL.*
ab60: 2a 20 73 65 74 74 69 6e 67 73 2e 20 20 54 68 65  * settings.  The
ab70: 20 5b 73 79 6e 63 68 72 6f 6e 6f 75 73 20 70 72   [synchronous pr
ab80: 61 67 6d 61 5d 20 64 65 74 65 72 6d 69 6e 65 73  agma] determines
ab90: 20 77 68 65 6e 20 63 61 6c 6c 73 20 74 6f 20 74   when calls to t
aba0: 68 65 0a 2a 2a 20 78 53 79 6e 63 20 56 46 53 20  he.** xSync VFS 
abb0: 6d 65 74 68 6f 64 20 6f 63 63 75 72 20 61 6e 64  method occur and
abc0: 20 61 70 70 6c 69 65 73 20 75 6e 69 66 6f 72 6d   applies uniform
abd0: 6c 79 20 61 63 72 6f 73 73 20 61 6c 6c 20 70 6c  ly across all pl
abe0: 61 74 66 6f 72 6d 73 2e 0a 2a 2a 20 54 68 65 20  atforms..** The 
abf0: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d  SQLITE_SYNC_NORM
ac00: 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59  AL and SQLITE_SY
ac10: 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73 20 64 65  NC_FULL flags de
ac20: 74 65 72 6d 69 6e 65 20 68 6f 77 0a 2a 2a 20 65  termine how.** e
ac30: 6e 65 72 67 65 74 69 63 20 6f 72 20 72 69 67 6f  nergetic or rigo
ac40: 72 6f 75 73 20 6f 72 20 66 6f 72 63 65 66 75 6c  rous or forceful
ac50: 20 74 68 65 20 73 79 6e 63 20 6f 70 65 72 61 74   the sync operat
ac60: 69 6f 6e 73 20 61 72 65 20 61 6e 64 0a 2a 2a 20  ions are and.** 
ac70: 6f 6e 6c 79 20 6d 61 6b 65 20 61 20 64 69 66 66  only make a diff
ac80: 65 72 65 6e 63 65 20 6f 6e 20 4d 61 63 20 4f 53  erence on Mac OS
ac90: 58 20 66 6f 72 20 74 68 65 20 64 65 66 61 75 6c  X for the defaul
aca0: 74 20 53 51 4c 69 74 65 20 63 6f 64 65 2e 0a 2a  t SQLite code..*
acb0: 2a 20 28 54 68 69 72 64 2d 70 61 72 74 79 20 56  * (Third-party V
acc0: 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
acd0: 6e 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 6d 61  ns might also ma
ace0: 6b 65 20 74 68 65 20 64 69 73 74 69 6e 63 74 69  ke the distincti
acf0: 6f 6e 0a 2a 2a 20 62 65 74 77 65 65 6e 20 53 51  on.** between SQ
ad00: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
ad10: 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43   and SQLITE_SYNC
ad20: 5f 46 55 4c 4c 2c 20 62 75 74 20 61 6d 6f 6e 67  _FULL, but among
ad30: 20 74 68 65 0a 2a 2a 20 6f 70 65 72 61 74 69 6e   the.** operatin
ad40: 67 20 73 79 73 74 65 6d 73 20 6e 61 74 69 76 65  g systems native
ad50: 6c 79 20 73 75 70 70 6f 72 74 65 64 20 62 79 20  ly supported by 
ad60: 53 51 4c 69 74 65 2c 20 6f 6e 6c 79 20 4d 61 63  SQLite, only Mac
ad70: 20 4f 53 58 0a 2a 2a 20 63 61 72 65 73 20 61 62   OSX.** cares ab
ad80: 6f 75 74 20 74 68 65 20 64 69 66 66 65 72 65 6e  out the differen
ad90: 63 65 2e 29 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ce.).*/.#define 
ada0: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d  SQLITE_SYNC_NORM
adb0: 41 4c 20 20 20 20 20 20 20 20 30 78 30 30 30 30  AL        0x0000
adc0: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
add0: 5f 53 59 4e 43 5f 46 55 4c 4c 20 20 20 20 20 20  _SYNC_FULL      
ade0: 20 20 20 20 30 78 30 30 30 30 33 0a 23 64 65 66      0x00003.#def
adf0: 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  ine SQLITE_SYNC_
ae00: 44 41 54 41 4f 4e 4c 59 20 20 20 20 20 20 30 78  DATAONLY      0x
ae10: 30 30 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  00010../*.** CAP
ae20: 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66  I3REF: OS Interf
ae30: 61 63 65 20 4f 70 65 6e 20 46 69 6c 65 20 48 61  ace Open File Ha
ae40: 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73  ndle.**.** An [s
ae50: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
ae60: 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 61  ect represents a
ae70: 6e 20 6f 70 65 6e 20 66 69 6c 65 20 69 6e 20 74  n open file in t
ae80: 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  he .** [sqlite3_
ae90: 76 66 73 20 7c 20 4f 53 20 69 6e 74 65 72 66 61  vfs | OS interfa
aea0: 63 65 20 6c 61 79 65 72 5d 2e 20 20 49 6e 64 69  ce layer].  Indi
aeb0: 76 69 64 75 61 6c 20 4f 53 20 69 6e 74 65 72 66  vidual OS interf
aec0: 61 63 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  ace.** implement
aed0: 61 74 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77  ations will.** w
aee0: 61 6e 74 20 74 6f 20 73 75 62 63 6c 61 73 73 20  ant to subclass 
aef0: 74 68 69 73 20 6f 62 6a 65 63 74 20 62 79 20 61  this object by a
af00: 70 70 65 6e 64 69 6e 67 20 61 64 64 69 74 69 6f  ppending additio
af10: 6e 61 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 66 6f  nal fields.** fo
af20: 72 20 74 68 65 69 72 20 6f 77 6e 20 75 73 65 2e  r their own use.
af30: 20 20 54 68 65 20 70 4d 65 74 68 6f 64 73 20 65    The pMethods e
af40: 6e 74 72 79 20 69 73 20 61 20 70 6f 69 6e 74 65  ntry is a pointe
af50: 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69  r to an.** [sqli
af60: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
af70: 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 66 69  object that defi
af80: 6e 65 73 20 6d 65 74 68 6f 64 73 20 66 6f 72 20  nes methods for 
af90: 70 65 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f  performing.** I/
afa0: 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20  O operations on 
afb0: 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a  the open file..*
afc0: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
afd0: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 73 71   sqlite3_file sq
afe0: 6c 69 74 65 33 5f 66 69 6c 65 3b 0a 73 74 72 75  lite3_file;.stru
aff0: 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20  ct sqlite3_file 
b000: 7b 0a 20 20 63 6f 6e 73 74 20 73 74 72 75 63 74  {.  const struct
b010: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68   sqlite3_io_meth
b020: 6f 64 73 20 2a 70 4d 65 74 68 6f 64 73 3b 20 20  ods *pMethods;  
b030: 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 61  /* Methods for a
b040: 6e 20 6f 70 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d  n open file */.}
b050: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
b060: 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20  F: OS Interface 
b070: 46 69 6c 65 20 56 69 72 74 75 61 6c 20 4d 65 74  File Virtual Met
b080: 68 6f 64 73 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a  hods Object.**.*
b090: 2a 20 45 76 65 72 79 20 66 69 6c 65 20 6f 70 65  * Every file ope
b0a0: 6e 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69  ned by the [sqli
b0b0: 74 65 33 5f 76 66 73 5d 20 78 4f 70 65 6e 20 6d  te3_vfs] xOpen m
b0c0: 65 74 68 6f 64 20 70 6f 70 75 6c 61 74 65 73 20  ethod populates 
b0d0: 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  an.** [sqlite3_f
b0e0: 69 6c 65 5d 20 6f 62 6a 65 63 74 20 28 6f 72 2c  ile] object (or,
b0f0: 20 6d 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20   more commonly, 
b100: 61 20 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68  a subclass of th
b110: 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  e.** [sqlite3_fi
b120: 6c 65 5d 20 6f 62 6a 65 63 74 29 20 77 69 74 68  le] object) with
b130: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
b140: 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69   instance of thi
b150: 73 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 69  s object..** Thi
b160: 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73  s object defines
b170: 20 74 68 65 20 6d 65 74 68 6f 64 73 20 75 73 65   the methods use
b180: 64 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72  d to perform var
b190: 69 6f 75 73 20 6f 70 65 72 61 74 69 6f 6e 73 0a  ious operations.
b1a0: 2a 2a 20 61 67 61 69 6e 73 74 20 74 68 65 20 6f  ** against the o
b1b0: 70 65 6e 20 66 69 6c 65 20 72 65 70 72 65 73 65  pen file represe
b1c0: 6e 74 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c  nted by the [sql
b1d0: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63  ite3_file] objec
b1e0: 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  t..**.** If the 
b1f0: 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 73 65 74  xOpen method set
b200: 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69  s the sqlite3_fi
b210: 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d  le.pMethods elem
b220: 65 6e 74 20 0a 2a 2a 20 74 6f 20 61 20 6e 6f 6e  ent .** to a non
b230: 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74  -NULL pointer, t
b240: 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f  hen the sqlite3_
b250: 69 6f 5f 6d 65 74 68 6f 64 73 2e 78 43 6c 6f 73  io_methods.xClos
b260: 65 20 6d 65 74 68 6f 64 0a 2a 2a 20 6d 61 79 20  e method.** may 
b270: 62 65 20 69 6e 76 6f 6b 65 64 20 65 76 65 6e 20  be invoked even 
b280: 69 66 20 74 68 65 20 78 4f 70 65 6e 20 72 65 70  if the xOpen rep
b290: 6f 72 74 65 64 20 74 68 61 74 20 69 74 20 66 61  orted that it fa
b2a0: 69 6c 65 64 2e 20 20 54 68 65 0a 2a 2a 20 6f 6e  iled.  The.** on
b2b0: 6c 79 20 77 61 79 20 74 6f 20 70 72 65 76 65 6e  ly way to preven
b2c0: 74 20 61 20 63 61 6c 6c 20 74 6f 20 78 43 6c 6f  t a call to xClo
b2d0: 73 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66  se following a f
b2e0: 61 69 6c 65 64 20 78 4f 70 65 6e 0a 2a 2a 20 69  ailed xOpen.** i
b2f0: 73 20 66 6f 72 20 74 68 65 20 78 4f 70 65 6e 20  s for the xOpen 
b300: 74 6f 20 73 65 74 20 74 68 65 20 73 71 6c 69 74  to set the sqlit
b310: 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73  e3_file.pMethods
b320: 20 65 6c 65 6d 65 6e 74 20 74 6f 20 4e 55 4c 4c   element to NULL
b330: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67  ..**.** The flag
b340: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 53  s argument to xS
b350: 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f  ync may be one o
b360: 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  f [SQLITE_SYNC_N
b370: 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 51  ORMAL] or.** [SQ
b380: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d 2e  LITE_SYNC_FULL].
b390: 20 20 54 68 65 20 66 69 72 73 74 20 63 68 6f 69    The first choi
b3a0: 63 65 20 69 73 20 74 68 65 20 6e 6f 72 6d 61 6c  ce is the normal
b3b0: 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20 54 68 65   fsync()..** The
b3c0: 20 73 65 63 6f 6e 64 20 63 68 6f 69 63 65 20 69   second choice i
b3d0: 73 20 61 20 4d 61 63 20 4f 53 20 58 20 73 74 79  s a Mac OS X sty
b3e0: 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20 20 54 68  le fullsync.  Th
b3f0: 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44  e [SQLITE_SYNC_D
b400: 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c 61 67  ATAONLY].** flag
b410: 20 6d 61 79 20 62 65 20 4f 52 65 64 20 69 6e 20   may be ORed in 
b420: 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74  to indicate that
b430: 20 6f 6e 6c 79 20 74 68 65 20 64 61 74 61 20 6f   only the data o
b440: 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20 61 6e  f the file.** an
b450: 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f 64 65 20  d not its inode 
b460: 6e 65 65 64 73 20 74 6f 20 62 65 20 73 79 6e 63  needs to be sync
b470: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e  ed..**.** The in
b480: 74 65 67 65 72 20 76 61 6c 75 65 73 20 74 6f 20  teger values to 
b490: 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c  xLock() and xUnl
b4a0: 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65 20 6f 66  ock() are one of
b4b0: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
b4c0: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f   [SQLITE_LOCK_NO
b4d0: 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  NE],.** <li> [SQ
b4e0: 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44  LITE_LOCK_SHARED
b4f0: 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  ],.** <li> [SQLI
b500: 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44  TE_LOCK_RESERVED
b510: 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  ],.** <li> [SQLI
b520: 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d  TE_LOCK_PENDING]
b530: 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  , or.** <li> [SQ
b540: 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53  LITE_LOCK_EXCLUS
b550: 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  IVE]..** </ul>.*
b560: 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63 72 65 61  * xLock() increa
b570: 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20 78 55  ses the lock. xU
b580: 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65 61 73 65  nlock() decrease
b590: 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 54  s the lock..** T
b5a0: 68 65 20 78 43 68 65 63 6b 52 65 73 65 72 76 65  he xCheckReserve
b5b0: 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 20 63  dLock() method c
b5c0: 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 61 6e  hecks whether an
b5d0: 79 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  y database conne
b5e0: 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68 65 72  ction,.** either
b5f0: 20 69 6e 20 74 68 69 73 20 70 72 6f 63 65 73 73   in this process
b600: 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f 74 68 65   or in some othe
b610: 72 20 70 72 6f 63 65 73 73 2c 20 69 73 20 68 6f  r process, is ho
b620: 6c 64 69 6e 67 20 61 20 52 45 53 45 52 56 45 44  lding a RESERVED
b630: 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20 6f 72  ,.** PENDING, or
b640: 20 45 58 43 4c 55 53 49 56 45 20 6c 6f 63 6b 20   EXCLUSIVE lock 
b650: 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 49 74  on the file.  It
b660: 20 72 65 74 75 72 6e 73 20 74 72 75 65 0a 2a 2a   returns true.**
b670: 20 69 66 20 73 75 63 68 20 61 20 6c 6f 63 6b 20   if such a lock 
b680: 65 78 69 73 74 73 20 61 6e 64 20 66 61 6c 73 65  exists and false
b690: 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a   otherwise..**.*
b6a0: 2a 20 54 68 65 20 78 46 69 6c 65 43 6f 6e 74 72  * The xFileContr
b6b0: 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69 73 20 61  ol() method is a
b6c0: 20 67 65 6e 65 72 69 63 20 69 6e 74 65 72 66 61   generic interfa
b6d0: 63 65 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 63  ce that allows c
b6e0: 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d 70  ustom.** VFS imp
b6f0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74 6f 20  lementations to 
b700: 64 69 72 65 63 74 6c 79 20 63 6f 6e 74 72 6f 6c  directly control
b710: 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 75 73   an open file us
b720: 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  ing the.** [sqli
b730: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
b740: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20  ()] interface.  
b750: 54 68 65 20 73 65 63 6f 6e 64 20 22 6f 70 22 20  The second "op" 
b760: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 0a 2a  argument is an.*
b770: 2a 20 69 6e 74 65 67 65 72 20 6f 70 63 6f 64 65  * integer opcode
b780: 2e 20 20 54 68 65 20 74 68 69 72 64 20 61 72 67  .  The third arg
b790: 75 6d 65 6e 74 20 69 73 20 61 20 67 65 6e 65 72  ument is a gener
b7a0: 69 63 20 70 6f 69 6e 74 65 72 20 69 6e 74 65 6e  ic pointer inten
b7b0: 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e 74 20  ded to.** point 
b7c0: 74 6f 20 61 20 73 74 72 75 63 74 75 72 65 20 74  to a structure t
b7d0: 68 61 74 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20  hat may contain 
b7e0: 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 73 70 61  arguments or spa
b7f0: 63 65 20 69 6e 20 77 68 69 63 68 20 74 6f 0a 2a  ce in which to.*
b800: 2a 20 77 72 69 74 65 20 72 65 74 75 72 6e 20 76  * write return v
b810: 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74 69 61  alues.  Potentia
b820: 6c 20 75 73 65 73 20 66 6f 72 20 78 46 69 6c 65  l uses for xFile
b830: 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68 74 20  Control() might 
b840: 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20  be.** functions 
b850: 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63 6b 69  to enable blocki
b860: 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68 20 74 69  ng locks with ti
b870: 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68 61 6e 67  meouts, to chang
b880: 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e 67  e the.** locking
b890: 20 73 74 72 61 74 65 67 79 20 28 66 6f 72 20 65   strategy (for e
b8a0: 78 61 6d 70 6c 65 20 74 6f 20 75 73 65 20 64 6f  xample to use do
b8b0: 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c 20 74  t-file locks), t
b8c0: 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61 62 6f  o inquire.** abo
b8d0: 75 74 20 74 68 65 20 73 74 61 74 75 73 20 6f 66  ut the status of
b8e0: 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20 62   a lock, or to b
b8f0: 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63 6b 73  reak stale locks
b900: 2e 20 20 54 68 65 20 53 51 4c 69 74 65 0a 2a 2a  .  The SQLite.**
b910: 20 63 6f 72 65 20 72 65 73 65 72 76 65 73 20 61   core reserves a
b920: 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65 73 73 20  ll opcodes less 
b930: 74 68 61 6e 20 31 30 30 20 66 6f 72 20 69 74 73  than 100 for its
b940: 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20 41 20 5b   own use..** A [
b950: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43  SQLITE_FCNTL_LOC
b960: 4b 53 54 41 54 45 20 7c 20 6c 69 73 74 20 6f 66  KSTATE | list of
b970: 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73 20 74   opcodes] less t
b980: 68 61 6e 20 31 30 30 20 69 73 20 61 76 61 69 6c  han 100 is avail
b990: 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61  able..** Applica
b9a0: 74 69 6f 6e 73 20 74 68 61 74 20 64 65 66 69 6e  tions that defin
b9b0: 65 20 61 20 63 75 73 74 6f 6d 20 78 46 69 6c 65  e a custom xFile
b9c0: 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 73  Control method s
b9d0: 68 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f 64 65  hould use opcode
b9e0: 73 0a 2a 2a 20 67 72 65 61 74 65 72 20 74 68 61  s.** greater tha
b9f0: 6e 20 31 30 30 20 74 6f 20 61 76 6f 69 64 20 63  n 100 to avoid c
ba00: 6f 6e 66 6c 69 63 74 73 2e 20 20 56 46 53 20 69  onflicts.  VFS i
ba10: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73  mplementations s
ba20: 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20  hould.** return 
ba30: 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44  [SQLITE_NOTFOUND
ba40: 5d 20 66 6f 72 20 66 69 6c 65 20 63 6f 6e 74 72  ] for file contr
ba50: 6f 6c 20 6f 70 63 6f 64 65 73 20 74 68 61 74 20  ol opcodes that 
ba60: 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 72  they do not.** r
ba70: 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a 2a 20  ecognize..**.** 
ba80: 54 68 65 20 78 53 65 63 74 6f 72 53 69 7a 65 28  The xSectorSize(
ba90: 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  ) method returns
baa0: 20 74 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65   the sector size
bab0: 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76 69 63   of the.** devic
bac0: 65 20 74 68 61 74 20 75 6e 64 65 72 6c 69 65 73  e that underlies
bad0: 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20   the file.  The 
bae0: 73 65 63 74 6f 72 20 73 69 7a 65 20 69 73 20 74  sector size is t
baf0: 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 72  he.** minimum wr
bb00: 69 74 65 20 74 68 61 74 20 63 61 6e 20 62 65 20  ite that can be 
bb10: 70 65 72 66 6f 72 6d 65 64 20 77 69 74 68 6f 75  performed withou
bb20: 74 20 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a 20  t disturbing.** 
bb30: 6f 74 68 65 72 20 62 79 74 65 73 20 69 6e 20 74  other bytes in t
bb40: 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 78 44  he file.  The xD
bb50: 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73  eviceCharacteris
bb60: 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f 64  tics().** method
bb70: 20 72 65 74 75 72 6e 73 20 61 20 62 69 74 20 76   returns a bit v
bb80: 65 63 74 6f 72 20 64 65 73 63 72 69 62 69 6e 67  ector describing
bb90: 20 62 65 68 61 76 69 6f 72 73 20 6f 66 20 74 68   behaviors of th
bba0: 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20  e.** underlying 
bbb0: 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75  device:.**.** <u
bbc0: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  l>.** <li> [SQLI
bbd0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 5d  TE_IOCAP_ATOMIC]
bbe0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
bbf0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32  _IOCAP_ATOMIC512
bc00: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
bc10: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b  E_IOCAP_ATOMIC1K
bc20: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
bc30: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b  E_IOCAP_ATOMIC2K
bc40: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
bc50: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b  E_IOCAP_ATOMIC4K
bc60: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
bc70: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b  E_IOCAP_ATOMIC8K
bc80: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
bc90: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36  E_IOCAP_ATOMIC16
bca0: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
bcb0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33  TE_IOCAP_ATOMIC3
bcc0: 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  2K].** <li> [SQL
bcd0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
bce0: 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  64K].** <li> [SQ
bcf0: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f  LITE_IOCAP_SAFE_
bd00: 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20  APPEND].** <li> 
bd10: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45  [SQLITE_IOCAP_SE
bd20: 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 2f 75  QUENTIAL].** </u
bd30: 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c  l>.**.** The SQL
bd40: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
bd50: 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20   property means 
bd60: 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20  that all writes 
bd70: 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61  of.** any size a
bd80: 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20  re atomic.  The 
bd90: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
bda0: 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a  MICnnn values.**
bdb0: 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 65   mean that write
bdc0: 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74  s of blocks that
bdd0: 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69   are nnn bytes i
bde0: 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72  n size and.** ar
bdf0: 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20  e aligned to an 
be00: 61 64 64 72 65 73 73 20 77 68 69 63 68 20 69 73  address which is
be10: 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74   an integer mult
be20: 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61  iple of.** nnn a
be30: 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20  re atomic.  The 
be40: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46  SQLITE_IOCAP_SAF
be50: 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d  E_APPEND value m
be60: 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65  eans.** that whe
be70: 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64  n data is append
be80: 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68  ed to a file, th
be90: 65 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64  e data is append
bea0: 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e  ed.** first then
beb0: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
bec0: 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65   file is extende
bed0: 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68  d, never the oth
bee0: 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64  er.** way around
bef0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
bf00: 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70  CAP_SEQUENTIAL p
bf10: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68  roperty means th
bf20: 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  at.** informatio
bf30: 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20  n is written to 
bf40: 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65  disk in the same
bf50: 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a   order as calls.
bf60: 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a  ** to xWrite()..
bf70: 2a 2a 0a 2a 2a 20 49 66 20 78 52 65 61 64 28 29  **.** If xRead()
bf80: 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f   returns SQLITE_
bf90: 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44  IOERR_SHORT_READ
bfa0: 20 69 74 20 6d 75 73 74 20 61 6c 73 6f 20 66 69   it must also fi
bfb0: 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65 20 75 6e 72  ll.** in the unr
bfc0: 65 61 64 20 70 6f 72 74 69 6f 6e 73 20 6f 66 20  ead portions of 
bfd0: 74 68 65 20 62 75 66 66 65 72 20 77 69 74 68 20  the buffer with 
bfe0: 7a 65 72 6f 73 2e 20 20 41 20 56 46 53 20 74 68  zeros.  A VFS th
bff0: 61 74 0a 2a 2a 20 66 61 69 6c 73 20 74 6f 20 7a  at.** fails to z
c000: 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72  ero-fill short r
c010: 65 61 64 73 20 6d 69 67 68 74 20 73 65 65 6d 20  eads might seem 
c020: 74 6f 20 77 6f 72 6b 2e 20 20 48 6f 77 65 76 65  to work.  Howeve
c030: 72 2c 0a 2a 2a 20 66 61 69 6c 75 72 65 20 74 6f  r,.** failure to
c040: 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74   zero-fill short
c050: 20 72 65 61 64 73 20 77 69 6c 6c 20 65 76 65 6e   reads will even
c060: 74 75 61 6c 6c 79 20 6c 65 61 64 20 74 6f 0a 2a  tually lead to.*
c070: 2a 20 64 61 74 61 62 61 73 65 20 63 6f 72 72 75  * database corru
c080: 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65  ption..*/.typede
c090: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
c0a0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69  _io_methods sqli
c0b0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a  te3_io_methods;.
c0c0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69  struct sqlite3_i
c0d0: 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e  o_methods {.  in
c0e0: 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e  t iVersion;.  in
c0f0: 74 20 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69  t (*xClose)(sqli
c100: 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e  te3_file*);.  in
c110: 74 20 28 2a 78 52 65 61 64 29 28 73 71 6c 69 74  t (*xRead)(sqlit
c120: 65 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c  e3_file*, void*,
c130: 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74   int iAmt, sqlit
c140: 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b  e3_int64 iOfst);
c150: 0a 20 20 69 6e 74 20 28 2a 78 57 72 69 74 65 29  .  int (*xWrite)
c160: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
c170: 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
c180: 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69   iAmt, sqlite3_i
c190: 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69  nt64 iOfst);.  i
c1a0: 6e 74 20 28 2a 78 54 72 75 6e 63 61 74 65 29 28  nt (*xTruncate)(
c1b0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73  sqlite3_file*, s
c1c0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 69 7a  qlite3_int64 siz
c1d0: 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e  e);.  int (*xSyn
c1e0: 63 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  c)(sqlite3_file*
c1f0: 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20  , int flags);.  
c200: 69 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a 65 29  int (*xFileSize)
c210: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
c220: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70  sqlite3_int64 *p
c230: 53 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78  Size);.  int (*x
c240: 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69  Lock)(sqlite3_fi
c250: 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74  le*, int);.  int
c260: 20 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c 69   (*xUnlock)(sqli
c270: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b  te3_file*, int);
c280: 0a 20 20 69 6e 74 20 28 2a 78 43 68 65 63 6b 52  .  int (*xCheckR
c290: 65 73 65 72 76 65 64 4c 6f 63 6b 29 28 73 71 6c  eservedLock)(sql
c2a0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20  ite3_file*, int 
c2b0: 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74  *pResOut);.  int
c2c0: 20 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 29   (*xFileControl)
c2d0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
c2e0: 69 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70 41  int op, void *pA
c2f0: 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 65  rg);.  int (*xSe
c300: 63 74 6f 72 53 69 7a 65 29 28 73 71 6c 69 74 65  ctorSize)(sqlite
c310: 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20  3_file*);.  int 
c320: 28 2a 78 44 65 76 69 63 65 43 68 61 72 61 63 74  (*xDeviceCharact
c330: 65 72 69 73 74 69 63 73 29 28 73 71 6c 69 74 65  eristics)(sqlite
c340: 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 4d  3_file*);.  /* M
c350: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65  ethods above are
c360: 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69   valid for versi
c370: 6f 6e 20 31 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  on 1 */.  int (*
c380: 78 53 68 6d 4d 61 70 29 28 73 71 6c 69 74 65 33  xShmMap)(sqlite3
c390: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 69 50 67 2c  _file*, int iPg,
c3a0: 20 69 6e 74 20 70 67 73 7a 2c 20 69 6e 74 2c 20   int pgsz, int, 
c3b0: 76 6f 69 64 20 76 6f 6c 61 74 69 6c 65 2a 2a 29  void volatile**)
c3c0: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 4c 6f  ;.  int (*xShmLo
c3d0: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
c3e0: 2a 2c 20 69 6e 74 20 6f 66 66 73 65 74 2c 20 69  *, int offset, i
c3f0: 6e 74 20 6e 2c 20 69 6e 74 20 66 6c 61 67 73 29  nt n, int flags)
c400: 3b 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 6d 42  ;.  void (*xShmB
c410: 61 72 72 69 65 72 29 28 73 71 6c 69 74 65 33 5f  arrier)(sqlite3_
c420: 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  file*);.  int (*
c430: 78 53 68 6d 55 6e 6d 61 70 29 28 73 71 6c 69 74  xShmUnmap)(sqlit
c440: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 64 65  e3_file*, int de
c450: 6c 65 74 65 46 6c 61 67 29 3b 0a 20 20 2f 2a 20  leteFlag);.  /* 
c460: 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72  Methods above ar
c470: 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73  e valid for vers
c480: 69 6f 6e 20 32 20 2a 2f 0a 20 20 2f 2a 20 41 64  ion 2 */.  /* Ad
c490: 64 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f 64 73  ditional methods
c4a0: 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
c4b0: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
c4c0: 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.};../*.** CA
c4d0: 50 49 33 52 45 46 3a 20 53 74 61 6e 64 61 72 64  PI3REF: Standard
c4e0: 20 46 69 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f 70   File Control Op
c4f0: 63 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  codes.**.** Thes
c500: 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61  e integer consta
c510: 6e 74 73 20 61 72 65 20 6f 70 63 6f 64 65 73 20  nts are opcodes 
c520: 66 6f 72 20 74 68 65 20 78 46 69 6c 65 43 6f 6e  for the xFileCon
c530: 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f  trol method.** o
c540: 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69  f the [sqlite3_i
c550: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  o_methods] objec
c560: 74 20 61 6e 64 20 66 6f 72 20 74 68 65 20 5b 73  t and for the [s
c570: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
c580: 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66  rol()].** interf
c590: 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  ace..**.** The [
c5a0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43  SQLITE_FCNTL_LOC
c5b0: 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64 65 20 69  KSTATE] opcode i
c5c0: 73 20 75 73 65 64 20 66 6f 72 20 64 65 62 75 67  s used for debug
c5d0: 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f  ging.  This.** o
c5e0: 70 63 6f 64 65 20 63 61 75 73 65 73 20 74 68 65  pcode causes the
c5f0: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65   xFileControl me
c600: 74 68 6f 64 20 74 6f 20 77 72 69 74 65 20 74 68  thod to write th
c610: 65 20 63 75 72 72 65 6e 74 20 73 74 61 74 65 20  e current state 
c620: 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63 6b 20 28  of.** the lock (
c630: 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4c  one of [SQLITE_L
c640: 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53 51 4c 49  OCK_NONE], [SQLI
c650: 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c  TE_LOCK_SHARED],
c660: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  .** [SQLITE_LOCK
c670: 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b 53 51 4c  _RESERVED], [SQL
c680: 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47  ITE_LOCK_PENDING
c690: 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4c 4f  ], or [SQLITE_LO
c6a0: 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 29 0a 2a  CK_EXCLUSIVE]).*
c6b0: 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74 65 67 65  * into an intege
c6c0: 72 20 74 68 61 74 20 74 68 65 20 70 41 72 67 20  r that the pArg 
c6d0: 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20  argument points 
c6e0: 74 6f 2e 20 54 68 69 73 20 63 61 70 61 62 69 6c  to. This capabil
c6f0: 69 74 79 0a 2a 2a 20 69 73 20 75 73 65 64 20 64  ity.** is used d
c700: 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20 61 6e  uring testing an
c710: 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20  d only needs to 
c720: 62 65 20 73 75 70 70 6f 72 74 65 64 20 77 68 65  be supported whe
c730: 6e 20 53 51 4c 49 54 45 5f 54 45 53 54 0a 2a 2a  n SQLITE_TEST.**
c740: 20 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a   is defined..**.
c750: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
c760: 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 20  CNTL_SIZE_HINT] 
c770: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 62  opcode is used b
c780: 79 20 53 51 4c 69 74 65 20 74 6f 20 67 69 76 65  y SQLite to give
c790: 20 74 68 65 20 56 46 53 0a 2a 2a 20 6c 61 79 65   the VFS.** laye
c7a0: 72 20 61 20 68 69 6e 74 20 6f 66 20 68 6f 77 20  r a hint of how 
c7b0: 6c 61 72 67 65 20 74 68 65 20 64 61 74 61 62 61  large the databa
c7c0: 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 67 72 6f  se file will gro
c7d0: 77 20 74 6f 20 62 65 20 64 75 72 69 6e 67 20 74  w to be during t
c7e0: 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 74 72  he.** current tr
c7f0: 61 6e 73 61 63 74 69 6f 6e 2e 20 20 54 68 69 73  ansaction.  This
c800: 20 68 69 6e 74 20 69 73 20 6e 6f 74 20 67 75 61   hint is not gua
c810: 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20 61 63  ranteed to be ac
c820: 63 75 72 61 74 65 20 62 75 74 20 69 74 0a 2a 2a  curate but it.**
c830: 20 69 73 20 6f 66 74 65 6e 20 63 6c 6f 73 65 2e   is often close.
c840: 20 20 54 68 65 20 75 6e 64 65 72 6c 79 69 6e 67    The underlying
c850: 20 56 46 53 20 6d 69 67 68 74 20 63 68 6f 6f 73   VFS might choos
c860: 65 20 74 6f 20 70 72 65 61 6c 6c 6f 63 61 74 65  e to preallocate
c870: 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c   database.** fil
c880: 65 20 73 70 61 63 65 20 62 61 73 65 64 20 6f 6e  e space based on
c890: 20 74 68 69 73 20 68 69 6e 74 20 69 6e 20 6f 72   this hint in or
c8a0: 64 65 72 20 74 6f 20 68 65 6c 70 20 77 72 69 74  der to help writ
c8b0: 65 73 20 74 6f 20 74 68 65 20 64 61 74 61 62 61  es to the databa
c8c0: 73 65 0a 2a 2a 20 66 69 6c 65 20 72 75 6e 20 66  se.** file run f
c8d0: 61 73 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  aster..**.** The
c8e0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43   [SQLITE_FCNTL_C
c8f0: 48 55 4e 4b 5f 53 49 5a 45 5d 20 6f 70 63 6f 64  HUNK_SIZE] opcod
c900: 65 20 69 73 20 75 73 65 64 20 74 6f 20 72 65 71  e is used to req
c910: 75 65 73 74 20 74 68 61 74 20 74 68 65 20 56 46  uest that the VF
c920: 53 0a 2a 2a 20 65 78 74 65 6e 64 73 20 61 6e 64  S.** extends and
c930: 20 74 72 75 6e 63 61 74 65 73 20 74 68 65 20 64   truncates the d
c940: 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 6e 20  atabase file in 
c950: 63 68 75 6e 6b 73 20 6f 66 20 61 20 73 69 7a 65  chunks of a size
c960: 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79   specified.** by
c970: 20 74 68 65 20 75 73 65 72 2e 20 54 68 65 20 66   the user. The f
c980: 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74  ourth argument t
c990: 6f 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  o [sqlite3_file_
c9a0: 63 6f 6e 74 72 6f 6c 28 29 5d 20 73 68 6f 75 6c  control()] shoul
c9b0: 64 20 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61  d .** point to a
c9c0: 6e 20 69 6e 74 65 67 65 72 20 28 74 79 70 65 20  n integer (type 
c9d0: 69 6e 74 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20  int) containing 
c9e0: 74 68 65 20 6e 65 77 20 63 68 75 6e 6b 2d 73 69  the new chunk-si
c9f0: 7a 65 20 74 6f 20 75 73 65 0a 2a 2a 20 66 6f 72  ze to use.** for
ca00: 20 74 68 65 20 6e 6f 6d 69 6e 61 74 65 64 20 64   the nominated d
ca10: 61 74 61 62 61 73 65 2e 20 41 6c 6c 6f 63 61 74  atabase. Allocat
ca20: 69 6e 67 20 64 61 74 61 62 61 73 65 20 66 69 6c  ing database fil
ca30: 65 20 73 70 61 63 65 20 69 6e 20 6c 61 72 67 65  e space in large
ca40: 0a 2a 2a 20 63 68 75 6e 6b 73 20 28 73 61 79 20  .** chunks (say 
ca50: 31 4d 42 20 61 74 20 61 20 74 69 6d 65 29 2c 20  1MB at a time), 
ca60: 6d 61 79 20 72 65 64 75 63 65 20 66 69 6c 65 2d  may reduce file-
ca70: 73 79 73 74 65 6d 20 66 72 61 67 6d 65 6e 74 61  system fragmenta
ca80: 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 69 6d 70 72  tion and.** impr
ca90: 6f 76 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20  ove performance 
caa0: 6f 6e 20 73 6f 6d 65 20 73 79 73 74 65 6d 73 2e  on some systems.
cab0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  .**.** The [SQLI
cac0: 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f  TE_FCNTL_FILE_PO
cad0: 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20 69 73  INTER] opcode is
cae0: 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20   used to obtain 
caf0: 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20  a pointer.** to 
cb00: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  the [sqlite3_fil
cb10: 65 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f 63 69  e] object associ
cb20: 61 74 65 64 20 77 69 74 68 20 61 20 70 61 72 74  ated with a part
cb30: 69 63 75 6c 61 72 20 64 61 74 61 62 61 73 65 0a  icular database.
cb40: 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20  ** connection.  
cb50: 53 65 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33  See the [sqlite3
cb60: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _file_control()]
cb70: 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66   documentation f
cb80: 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c  or.** additional
cb90: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a   information..**
cba0: 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c 49 54  .** ^(The [SQLIT
cbb0: 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49  E_FCNTL_SYNC_OMI
cbc0: 54 54 45 44 5d 20 6f 70 63 6f 64 65 20 69 73 20  TTED] opcode is 
cbd0: 67 65 6e 65 72 61 74 65 64 20 69 6e 74 65 72 6e  generated intern
cbe0: 61 6c 6c 79 20 62 79 0a 2a 2a 20 53 51 4c 69 74  ally by.** SQLit
cbf0: 65 20 61 6e 64 20 73 65 6e 74 20 74 6f 20 61 6c  e and sent to al
cc00: 6c 20 56 46 53 65 73 20 69 6e 20 70 6c 61 63 65  l VFSes in place
cc10: 20 6f 66 20 61 20 63 61 6c 6c 20 74 6f 20 74 68   of a call to th
cc20: 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 0a 2a  e xSync method.*
cc30: 2a 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 62  * when the datab
cc40: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 68  ase connection h
cc50: 61 73 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68  as [PRAGMA synch
cc60: 72 6f 6e 6f 75 73 5d 20 73 65 74 20 74 6f 20 4f  ronous] set to O
cc70: 46 46 2e 29 5e 0a 2a 2a 20 53 6f 6d 65 20 73 70  FF.)^.** Some sp
cc80: 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65 73 20  ecialized VFSes 
cc90: 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e 61 6c  need this signal
cca0: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 6f 70 65   in order to ope
ccb0: 72 61 74 65 20 63 6f 72 72 65 63 74 6c 79 0a 2a  rate correctly.*
ccc0: 2a 20 77 68 65 6e 20 5b 50 52 41 47 4d 41 20 73  * when [PRAGMA s
ccd0: 79 6e 63 68 72 6f 6e 6f 75 73 20 7c 20 50 52 41  ynchronous | PRA
cce0: 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 3d  GMA synchronous=
ccf0: 4f 46 46 5d 20 69 73 20 73 65 74 2c 20 62 75 74  OFF] is set, but
cd00: 20 6d 6f 73 74 20 0a 2a 2a 20 56 46 53 65 73 20   most .** VFSes 
cd10: 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 68 69 73  do not need this
cd20: 20 73 69 67 6e 61 6c 20 61 6e 64 20 73 68 6f 75   signal and shou
cd30: 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f  ld silently igno
cd40: 72 65 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 0a  re this opcode..
cd50: 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** Applications 
cd60: 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c 20  should not call 
cd70: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
cd80: 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 20 74 68  ntrol()] with th
cd90: 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 61 73 20  is.** opcode as 
cda0: 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20 64 69 73  doing so may dis
cdb0: 72 75 70 74 20 74 68 65 20 6f 70 65 72 61 74 69  rupt the operati
cdc0: 6f 6e 20 6f 66 20 74 68 65 20 73 70 65 63 69 61  on of the specia
cdd0: 6c 69 7a 65 64 20 56 46 53 65 73 0a 2a 2a 20 74  lized VFSes.** t
cde0: 68 61 74 20 64 6f 20 72 65 71 75 69 72 65 20 69  hat do require i
cdf0: 74 2e 20 20 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  t.  .*/.#define 
ce00: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43  SQLITE_FCNTL_LOC
ce10: 4b 53 54 41 54 45 20 20 20 20 20 20 20 20 31 0a  KSTATE        1.
ce20: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 47  #define SQLITE_G
ce30: 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45  ET_LOCKPROXYFILE
ce40: 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20        2.#define 
ce50: 53 51 4c 49 54 45 5f 53 45 54 5f 4c 4f 43 4b 50  SQLITE_SET_LOCKP
ce60: 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 33 0a  ROXYFILE      3.
ce70: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
ce80: 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 20 20 20  AST_ERRNO       
ce90: 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20        4.#define 
cea0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a  SQLITE_FCNTL_SIZ
ceb0: 45 5f 48 49 4e 54 20 20 20 20 20 20 20 20 35 0a  E_HINT        5.
cec0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
ced0: 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 20  CNTL_CHUNK_SIZE 
cee0: 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20        6.#define 
cef0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c  SQLITE_FCNTL_FIL
cf00: 45 5f 50 4f 49 4e 54 45 52 20 20 20 20 20 37 0a  E_POINTER     7.
cf10: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
cf20: 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45  CNTL_SYNC_OMITTE
cf30: 44 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20  D     8.../*.** 
cf40: 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20  CAPI3REF: Mutex 
cf50: 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65  Handle.**.** The
cf60: 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20 77 69   mutex module wi
cf70: 74 68 69 6e 20 53 51 4c 69 74 65 20 64 65 66 69  thin SQLite defi
cf80: 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  nes [sqlite3_mut
cf90: 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20  ex] to be an.** 
cfa0: 61 62 73 74 72 61 63 74 20 74 79 70 65 20 66 6f  abstract type fo
cfb0: 72 20 61 20 6d 75 74 65 78 20 6f 62 6a 65 63 74  r a mutex object
cfc0: 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f  .  The SQLite co
cfd0: 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a  re never looks.*
cfe0: 2a 20 61 74 20 74 68 65 20 69 6e 74 65 72 6e 61  * at the interna
cff0: 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e  l representation
d000: 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   of an [sqlite3_
d010: 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79  mutex].  It only
d020: 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74 68 20 70  .** deals with p
d030: 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65 20 5b  ointers to the [
d040: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f  sqlite3_mutex] o
d050: 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74  bject..**.** Mut
d060: 65 78 65 73 20 61 72 65 20 63 72 65 61 74 65 64  exes are created
d070: 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
d080: 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a  mutex_alloc()]..
d090: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
d0a0: 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20  t sqlite3_mutex 
d0b0: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a  sqlite3_mutex;..
d0c0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
d0d0: 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 62 6a  OS Interface Obj
d0e0: 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73  ect.**.** An ins
d0f0: 74 61 6e 63 65 20 6f 66 20 74 68 65 20 73 71 6c  tance of the sql
d100: 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20  ite3_vfs object 
d110: 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65  defines the inte
d120: 72 66 61 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a  rface between.**
d130: 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   the SQLite core
d140: 20 61 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79   and the underly
d150: 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79  ing operating sy
d160: 73 74 65 6d 2e 20 20 54 68 65 20 22 76 66 73 22  stem.  The "vfs"
d170: 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65 20  .** in the name 
d180: 6f 66 20 74 68 65 20 6f 62 6a 65 63 74 20 73 74  of the object st
d190: 61 6e 64 73 20 66 6f 72 20 22 76 69 72 74 75 61  ands for "virtua
d1a0: 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 22 2e 0a  l file system"..
d1b0: 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20  **.** The value 
d1c0: 6f 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20  of the iVersion 
d1d0: 66 69 65 6c 64 20 69 73 20 69 6e 69 74 69 61 6c  field is initial
d1e0: 6c 79 20 31 20 62 75 74 20 6d 61 79 20 62 65 20  ly 1 but may be 
d1f0: 6c 61 72 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74  larger in.** fut
d200: 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
d210: 53 51 4c 69 74 65 2e 20 20 41 64 64 69 74 69 6f  SQLite.  Additio
d220: 6e 61 6c 20 66 69 65 6c 64 73 20 6d 61 79 20 62  nal fields may b
d230: 65 20 61 70 70 65 6e 64 65 64 20 74 6f 20 74 68  e appended to th
d240: 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65  is.** object whe
d250: 6e 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 76  n the iVersion v
d260: 61 6c 75 65 20 69 73 20 69 6e 63 72 65 61 73 65  alue is increase
d270: 64 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68  d.  Note that th
d280: 65 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f  e structure.** o
d290: 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66  f the sqlite3_vf
d2a0: 73 20 6f 62 6a 65 63 74 20 63 68 61 6e 67 65 73  s object changes
d2b0: 20 69 6e 20 74 68 65 20 74 72 61 6e 73 61 63 74   in the transact
d2c0: 69 6f 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53  ion between.** S
d2d0: 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
d2e0: 35 2e 39 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e  5.9 and 3.6.0 an
d2f0: 64 20 79 65 74 20 74 68 65 20 69 56 65 72 73 69  d yet the iVersi
d300: 6f 6e 20 66 69 65 6c 64 20 77 61 73 20 6e 6f 74  on field was not
d310: 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a  .** modified..**
d320: 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c 65  .** The szOsFile
d330: 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 73 69   field is the si
d340: 7a 65 20 6f 66 20 74 68 65 20 73 75 62 63 6c 61  ze of the subcla
d350: 73 73 65 64 20 5b 73 71 6c 69 74 65 33 5f 66 69  ssed [sqlite3_fi
d360: 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  le].** structure
d370: 20 75 73 65 64 20 62 79 20 74 68 69 73 20 56 46   used by this VF
d380: 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65 20 69  S.  mxPathname i
d390: 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65  s the maximum le
d3a0: 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74  ngth of.** a pat
d3b0: 68 6e 61 6d 65 20 69 6e 20 74 68 69 73 20 56 46  hname in this VF
d3c0: 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65  S..**.** Registe
d3d0: 72 65 64 20 73 71 6c 69 74 65 33 5f 76 66 73 20  red sqlite3_vfs 
d3e0: 6f 62 6a 65 63 74 73 20 61 72 65 20 6b 65 70 74  objects are kept
d3f0: 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73   on a linked lis
d400: 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74  t formed by.** t
d410: 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72  he pNext pointer
d420: 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  .  The [sqlite3_
d430: 76 66 73 5f 72 65 67 69 73 74 65 72 28 29 5d 0a  vfs_register()].
d440: 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
d450: 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29  vfs_unregister()
d460: 5d 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6e  ] interfaces man
d470: 61 67 65 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a  age this list.**
d480: 20 69 6e 20 61 20 74 68 72 65 61 64 2d 73 61 66   in a thread-saf
d490: 65 20 77 61 79 2e 20 20 54 68 65 20 5b 73 71 6c  e way.  The [sql
d4a0: 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d  ite3_vfs_find()]
d4b0: 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 65   interface.** se
d4c0: 61 72 63 68 65 73 20 74 68 65 20 6c 69 73 74 2e  arches the list.
d4d0: 20 20 4e 65 69 74 68 65 72 20 74 68 65 20 61 70    Neither the ap
d4e0: 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e  plication code n
d4f0: 6f 72 20 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d  or the VFS.** im
d500: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f  plementation sho
d510: 75 6c 64 20 75 73 65 20 74 68 65 20 70 4e 65 78  uld use the pNex
d520: 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  t pointer..**.**
d530: 20 54 68 65 20 70 4e 65 78 74 20 66 69 65 6c 64   The pNext field
d540: 20 69 73 20 74 68 65 20 6f 6e 6c 79 20 66 69 65   is the only fie
d550: 6c 64 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65  ld in the sqlite
d560: 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63 74 75  3_vfs.** structu
d570: 72 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 77  re that SQLite w
d580: 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66 79 2e  ill ever modify.
d590: 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e    SQLite will on
d5a0: 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20  ly access.** or 
d5b0: 6d 6f 64 69 66 79 20 74 68 69 73 20 66 69 65 6c  modify this fiel
d5c0: 64 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20  d while holding 
d5d0: 61 20 70 61 72 74 69 63 75 6c 61 72 20 73 74 61  a particular sta
d5e0: 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68  tic mutex..** Th
d5f0: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
d600: 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69 66  ould never modif
d610: 79 20 61 6e 79 74 68 69 6e 67 20 77 69 74 68 69  y anything withi
d620: 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66  n the sqlite3_vf
d630: 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65  s.** object once
d640: 20 74 68 65 20 6f 62 6a 65 63 74 20 68 61 73 20   the object has 
d650: 62 65 65 6e 20 72 65 67 69 73 74 65 72 65 64 2e  been registered.
d660: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65  .**.** The zName
d670: 20 66 69 65 6c 64 20 68 6f 6c 64 73 20 74 68 65   field holds the
d680: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 56 46 53   name of the VFS
d690: 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e 61   module.  The na
d6a0: 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e  me must.** be un
d6b0: 69 71 75 65 20 61 63 72 6f 73 73 20 61 6c 6c 20  ique across all 
d6c0: 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a  VFS modules..**.
d6d0: 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61  ** ^SQLite guara
d6e0: 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20 7a  ntees that the z
d6f0: 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74  Filename paramet
d700: 65 72 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69  er to xOpen.** i
d710: 73 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20  s either a NULL 
d720: 70 6f 69 6e 74 65 72 20 6f 72 20 73 74 72 69 6e  pointer or strin
d730: 67 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72  g obtained.** fr
d740: 6f 6d 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65  om xFullPathname
d750: 28 29 20 77 69 74 68 20 61 6e 20 6f 70 74 69 6f  () with an optio
d760: 6e 61 6c 20 73 75 66 66 69 78 20 61 64 64 65 64  nal suffix added
d770: 2e 0a 2a 2a 20 5e 49 66 20 61 20 73 75 66 66 69  ..** ^If a suffi
d780: 78 20 69 73 20 61 64 64 65 64 20 74 6f 20 74 68  x is added to th
d790: 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61  e zFilename para
d7a0: 6d 65 74 65 72 2c 20 69 74 20 77 69 6c 6c 0a 2a  meter, it will.*
d7b0: 2a 20 63 6f 6e 73 69 73 74 20 6f 66 20 61 20 73  * consist of a s
d7c0: 69 6e 67 6c 65 20 22 2d 22 20 63 68 61 72 61 63  ingle "-" charac
d7d0: 74 65 72 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  ter followed by 
d7e0: 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 0a 2a 2a 20  no more than.** 
d7f0: 31 30 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20  10 alphanumeric 
d800: 61 6e 64 2f 6f 72 20 22 2d 22 20 63 68 61 72 61  and/or "-" chara
d810: 63 74 65 72 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74  cters..** ^SQLit
d820: 65 20 66 75 72 74 68 65 72 20 67 75 61 72 61 6e  e further guaran
d830: 74 65 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65  tees that.** the
d840: 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 20   string will be 
d850: 76 61 6c 69 64 20 61 6e 64 20 75 6e 63 68 61 6e  valid and unchan
d860: 67 65 64 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65  ged until xClose
d870: 28 29 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e  () is.** called.
d880: 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20   Because of the 
d890: 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63  previous sentenc
d8a0: 65 2c 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74  e,.** the [sqlit
d8b0: 65 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73 61 66  e3_file] can saf
d8c0: 65 6c 79 20 73 74 6f 72 65 20 61 20 70 6f 69 6e  ely store a poin
d8d0: 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69  ter to the.** fi
d8e0: 6c 65 6e 61 6d 65 20 69 66 20 69 74 20 6e 65 65  lename if it nee
d8f0: 64 73 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 74  ds to remember t
d900: 68 65 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20  he filename for 
d910: 73 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20  some reason..** 
d920: 49 66 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65  If the zFilename
d930: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f   parameter to xO
d940: 70 65 6e 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  pen is a NULL po
d950: 69 6e 74 65 72 20 74 68 65 6e 20 78 4f 70 65 6e  inter then xOpen
d960: 0a 2a 2a 20 6d 75 73 74 20 69 6e 76 65 6e 74 20  .** must invent 
d970: 69 74 73 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72  its own temporar
d980: 79 20 6e 61 6d 65 20 66 6f 72 20 74 68 65 20 66  y name for the f
d990: 69 6c 65 2e 20 20 5e 57 68 65 6e 65 76 65 72 20  ile.  ^Whenever 
d9a0: 74 68 65 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d  the .** xFilenam
d9b0: 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 4e  e parameter is N
d9c0: 55 4c 4c 20 69 74 20 77 69 6c 6c 20 61 6c 73 6f  ULL it will also
d9d0: 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61   be the case tha
d9e0: 74 20 74 68 65 0a 2a 2a 20 66 6c 61 67 73 20 70  t the.** flags p
d9f0: 61 72 61 6d 65 74 65 72 20 77 69 6c 6c 20 69 6e  arameter will in
da00: 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50  clude [SQLITE_OP
da10: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45  EN_DELETEONCLOSE
da20: 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61  ]..**.** The fla
da30: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78  gs argument to x
da40: 4f 70 65 6e 28 29 20 69 6e 63 6c 75 64 65 73 20  Open() includes 
da50: 61 6c 6c 20 62 69 74 73 20 73 65 74 20 69 6e 0a  all bits set in.
da60: 2a 2a 20 74 68 65 20 66 6c 61 67 73 20 61 72 67  ** the flags arg
da70: 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65  ument to [sqlite
da80: 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20 4f  3_open_v2()].  O
da90: 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70  r if [sqlite3_op
daa0: 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c  en()].** or [sql
dab0: 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69  ite3_open16()] i
dac0: 73 20 75 73 65 64 2c 20 74 68 65 6e 20 66 6c 61  s used, then fla
dad0: 67 73 20 69 6e 63 6c 75 64 65 73 20 61 74 20 6c  gs includes at l
dae0: 65 61 73 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  east.** [SQLITE_
daf0: 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20  OPEN_READWRITE] 
db00: 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  | [SQLITE_OPEN_C
db10: 52 45 41 54 45 5d 2e 20 0a 2a 2a 20 49 66 20 78  REATE]. .** If x
db20: 4f 70 65 6e 28 29 20 6f 70 65 6e 73 20 61 20 66  Open() opens a f
db30: 69 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68  ile read-only th
db40: 65 6e 20 69 74 20 73 65 74 73 20 2a 70 4f 75 74  en it sets *pOut
db50: 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c  Flags to.** incl
db60: 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  ude [SQLITE_OPEN
db70: 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68  _READONLY].  Oth
db80: 65 72 20 62 69 74 73 20 69 6e 20 2a 70 4f 75 74  er bits in *pOut
db90: 46 6c 61 67 73 20 6d 61 79 20 62 65 20 73 65 74  Flags may be set
dba0: 2e 0a 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74 65  ..**.** ^(SQLite
dbb0: 20 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f   will also add o
dbc0: 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77  ne of the follow
dbd0: 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65  ing flags to the
dbe0: 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c   xOpen().** call
dbf0: 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  , depending on t
dc00: 68 65 20 6f 62 6a 65 63 74 20 62 65 69 6e 67 20  he object being 
dc10: 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75  opened:.**.** <u
dc20: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  l>.** <li>  [SQL
dc30: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42  ITE_OPEN_MAIN_DB
dc40: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
dc50: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55  TE_OPEN_MAIN_JOU
dc60: 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  RNAL].** <li>  [
dc70: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50  SQLITE_OPEN_TEMP
dc80: 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  _DB].** <li>  [S
dc90: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
dca0: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e  JOURNAL].** <li>
dcb0: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54    [SQLITE_OPEN_T
dcc0: 52 41 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20  RANSIENT_DB].** 
dcd0: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
dce0: 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a  EN_SUBJOURNAL].*
dcf0: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
dd00: 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52  OPEN_MASTER_JOUR
dd10: 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  NAL].** <li>  [S
dd20: 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 5d 0a  QLITE_OPEN_WAL].
dd30: 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a  ** </ul>)^.**.**
dd40: 20 54 68 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d   The file I/O im
dd50: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e  plementation can
dd60: 20 75 73 65 20 74 68 65 20 6f 62 6a 65 63 74 20   use the object 
dd70: 74 79 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a  type flags to.**
dd80: 20 63 68 61 6e 67 65 20 74 68 65 20 77 61 79 20   change the way 
dd90: 69 74 20 64 65 61 6c 73 20 77 69 74 68 20 66 69  it deals with fi
dda0: 6c 65 73 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c  les.  For exampl
ddb0: 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  e, an applicatio
ddc0: 6e 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73 20 6e  n.** that does n
ddd0: 6f 74 20 63 61 72 65 20 61 62 6f 75 74 20 63 72  ot care about cr
dde0: 61 73 68 20 72 65 63 6f 76 65 72 79 20 6f 72 20  ash recovery or 
ddf0: 72 6f 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d  rollback might m
de00: 61 6b 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20  ake.** the open 
de10: 6f 66 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c  of a journal fil
de20: 65 20 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74  e a no-op.  Writ
de30: 65 73 20 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e  es to this journ
de40: 61 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f  al would.** also
de50: 20 62 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20   be no-ops, and 
de60: 61 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 72  any attempt to r
de70: 65 61 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20  ead the journal 
de80: 77 6f 75 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20  would return.** 
de90: 53 51 4c 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f  SQLITE_IOERR.  O
dea0: 72 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  r the implementa
deb0: 74 69 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f 67  tion might recog
dec0: 6e 69 7a 65 20 74 68 61 74 20 61 20 64 61 74 61  nize that a data
ded0: 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c  base.** file wil
dee0: 6c 20 62 65 20 64 6f 69 6e 67 20 70 61 67 65 2d  l be doing page-
def0: 61 6c 69 67 6e 65 64 20 73 65 63 74 6f 72 20 72  aligned sector r
df00: 65 61 64 73 20 61 6e 64 20 77 72 69 74 65 73 20  eads and writes 
df10: 69 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f  in a random.** o
df20: 72 64 65 72 20 61 6e 64 20 73 65 74 20 75 70 20  rder and set up 
df30: 69 74 73 20 49 2f 4f 20 73 75 62 73 79 73 74 65  its I/O subsyste
df40: 6d 20 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a  m accordingly..*
df50: 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 69 67 68  *.** SQLite migh
df60: 74 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f  t also add one o
df70: 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  f the following 
df80: 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70  flags to the xOp
df90: 65 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a  en method:.**.**
dfa0: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53   <ul>.** <li> [S
dfb0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
dfc0: 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69  EONCLOSE].** <li
dfd0: 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45  > [SQLITE_OPEN_E
dfe0: 58 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75  XCLUSIVE].** </u
dff0: 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51  l>.**.** The [SQ
e000: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
e010: 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65  ONCLOSE] flag me
e020: 61 6e 73 20 74 68 65 20 66 69 6c 65 20 73 68 6f  ans the file sho
e030: 75 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65  uld be.** delete
e040: 64 20 77 68 65 6e 20 69 74 20 69 73 20 63 6c 6f  d when it is clo
e050: 73 65 64 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49  sed.  ^The [SQLI
e060: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
e070: 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62  CLOSE].** will b
e080: 65 20 73 65 74 20 66 6f 72 20 54 45 4d 50 20 64  e set for TEMP d
e090: 61 74 61 62 61 73 65 73 20 61 6e 64 20 74 68 65  atabases and the
e0a0: 69 72 20 6a 6f 75 72 6e 61 6c 73 2c 20 74 72 61  ir journals, tra
e0b0: 6e 73 69 65 6e 74 0a 2a 2a 20 64 61 74 61 62 61  nsient.** databa
e0c0: 73 65 73 2c 20 61 6e 64 20 73 75 62 6a 6f 75 72  ses, and subjour
e0d0: 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  nals..**.** ^The
e0e0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58   [SQLITE_OPEN_EX
e0f0: 43 4c 55 53 49 56 45 5d 20 66 6c 61 67 20 69 73  CLUSIVE] flag is
e100: 20 61 6c 77 61 79 73 20 75 73 65 64 20 69 6e 20   always used in 
e110: 63 6f 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77  conjunction.** w
e120: 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ith the [SQLITE_
e130: 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20 66 6c 61  OPEN_CREATE] fla
e140: 67 2c 20 77 68 69 63 68 20 61 72 65 20 62 6f 74  g, which are bot
e150: 68 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 61 6e  h directly.** an
e160: 61 6c 6f 67 6f 75 73 20 74 6f 20 74 68 65 20 4f  alogous to the O
e170: 5f 45 58 43 4c 20 61 6e 64 20 4f 5f 43 52 45 41  _EXCL and O_CREA
e180: 54 20 66 6c 61 67 73 20 6f 66 20 74 68 65 20 50  T flags of the P
e190: 4f 53 49 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 41  OSIX open().** A
e1a0: 50 49 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  PI.  The SQLITE_
e1b0: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 66  OPEN_EXCLUSIVE f
e1c0: 6c 61 67 2c 20 77 68 65 6e 20 70 61 69 72 65 64  lag, when paired
e1d0: 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 53 51   with the .** SQ
e1e0: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
e1f0: 2c 20 69 73 20 75 73 65 64 20 74 6f 20 69 6e 64  , is used to ind
e200: 69 63 61 74 65 20 74 68 61 74 20 66 69 6c 65 20  icate that file 
e210: 73 68 6f 75 6c 64 20 61 6c 77 61 79 73 0a 2a 2a  should always.**
e220: 20 62 65 20 63 72 65 61 74 65 64 2c 20 61 6e 64   be created, and
e230: 20 74 68 61 74 20 69 74 20 69 73 20 61 6e 20 65   that it is an e
e240: 72 72 6f 72 20 69 66 20 69 74 20 61 6c 72 65 61  rror if it alrea
e250: 64 79 20 65 78 69 73 74 73 2e 0a 2a 2a 20 49 74  dy exists..** It
e260: 20 69 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75   is <i>not</i> u
e270: 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20  sed to indicate 
e280: 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20  the file should 
e290: 62 65 20 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 6f  be opened .** fo
e2a0: 72 20 65 78 63 6c 75 73 69 76 65 20 61 63 63 65  r exclusive acce
e2b0: 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74 20 6c 65  ss..**.** ^At le
e2c0: 61 73 74 20 73 7a 4f 73 46 69 6c 65 20 62 79 74  ast szOsFile byt
e2d0: 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65  es of memory are
e2e0: 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51   allocated by SQ
e2f0: 4c 69 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20  Lite.** to hold 
e300: 74 68 65 20 20 5b 73 71 6c 69 74 65 33 5f 66 69  the  [sqlite3_fi
e310: 6c 65 5d 20 73 74 72 75 63 74 75 72 65 20 70 61  le] structure pa
e320: 73 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72  ssed as the thir
e330: 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f  d.** argument to
e340: 20 78 4f 70 65 6e 2e 20 20 54 68 65 20 78 4f 70   xOpen.  The xOp
e350: 65 6e 20 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e  en method does n
e360: 6f 74 20 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c  ot have to.** al
e370: 6c 6f 63 61 74 65 20 74 68 65 20 73 74 72 75 63  locate the struc
e380: 74 75 72 65 3b 20 69 74 20 73 68 6f 75 6c 64 20  ture; it should 
e390: 6a 75 73 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e  just fill it in.
e3a0: 20 20 4e 6f 74 65 20 74 68 61 74 0a 2a 2a 20 74    Note that.** t
e3b0: 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20  he xOpen method 
e3c0: 6d 75 73 74 20 73 65 74 20 74 68 65 20 73 71 6c  must set the sql
e3d0: 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f  ite3_file.pMetho
e3e0: 64 73 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20  ds to either.** 
e3f0: 61 20 76 61 6c 69 64 20 5b 73 71 6c 69 74 65 33  a valid [sqlite3
e400: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
e410: 65 63 74 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20  ect or to NULL. 
e420: 20 78 4f 70 65 6e 20 6d 75 73 74 20 64 6f 0a 2a   xOpen must do.*
e430: 2a 20 74 68 69 73 20 65 76 65 6e 20 69 66 20 74  * this even if t
e440: 68 65 20 6f 70 65 6e 20 66 61 69 6c 73 2e 20 20  he open fails.  
e450: 53 51 4c 69 74 65 20 65 78 70 65 63 74 73 20 74  SQLite expects t
e460: 68 61 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f  hat the sqlite3_
e470: 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a  file.pMethods.**
e480: 20 65 6c 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65   element will be
e490: 20 76 61 6c 69 64 20 61 66 74 65 72 20 78 4f 70   valid after xOp
e4a0: 65 6e 20 72 65 74 75 72 6e 73 20 72 65 67 61 72  en returns regar
e4b0: 64 6c 65 73 73 20 6f 66 20 74 68 65 20 73 75 63  dless of the suc
e4c0: 63 65 73 73 0a 2a 2a 20 6f 72 20 66 61 69 6c 75  cess.** or failu
e4d0: 72 65 20 6f 66 20 74 68 65 20 78 4f 70 65 6e 20  re of the xOpen 
e4e0: 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  call..**.** ^The
e4f0: 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20   flags argument 
e500: 74 6f 20 78 41 63 63 65 73 73 28 29 20 6d 61 79  to xAccess() may
e510: 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 43 43 45   be [SQLITE_ACCE
e520: 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a 20 74 6f  SS_EXISTS].** to
e530: 20 74 65 73 74 20 66 6f 72 20 74 68 65 20 65 78   test for the ex
e540: 69 73 74 65 6e 63 65 20 6f 66 20 61 20 66 69 6c  istence of a fil
e550: 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43  e, or [SQLITE_AC
e560: 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 5d 20  CESS_READWRITE] 
e570: 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68 65 74 68  to.** test wheth
e580: 65 72 20 61 20 66 69 6c 65 20 69 73 20 72 65 61  er a file is rea
e590: 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62  dable and writab
e5a0: 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41  le, or [SQLITE_A
e5b0: 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a 2a 20 74  CCESS_READ].** t
e5c0: 6f 20 74 65 73 74 20 77 68 65 74 68 65 72 20 61  o test whether a
e5d0: 20 66 69 6c 65 20 69 73 20 61 74 20 6c 65 61 73   file is at leas
e5e0: 74 20 72 65 61 64 61 62 6c 65 2e 20 20 20 54 68  t readable.   Th
e5f0: 65 20 66 69 6c 65 20 63 61 6e 20 62 65 20 61 0a  e file can be a.
e600: 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a  ** directory..**
e610: 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c  .** ^SQLite will
e620: 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63 61 74 65   always allocate
e630: 20 61 74 20 6c 65 61 73 74 20 6d 78 50 61 74 68   at least mxPath
e640: 6e 61 6d 65 2b 31 20 62 79 74 65 73 20 66 6f 72  name+1 bytes for
e650: 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75 74 20 62   the.** output b
e660: 75 66 66 65 72 20 78 46 75 6c 6c 50 61 74 68 6e  uffer xFullPathn
e670: 61 6d 65 2e 20 20 54 68 65 20 65 78 61 63 74 20  ame.  The exact 
e680: 73 69 7a 65 20 6f 66 20 74 68 65 20 6f 75 74 70  size of the outp
e690: 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20  ut buffer.** is 
e6a0: 61 6c 73 6f 20 70 61 73 73 65 64 20 61 73 20 61  also passed as a
e6b0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 6f   parameter to bo
e6c0: 74 68 20 20 6d 65 74 68 6f 64 73 2e 20 49 66 20  th  methods. If 
e6d0: 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66 65  the output buffe
e6e0: 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c 61 72 67  r.** is not larg
e6f0: 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51 4c 49 54  e enough, [SQLIT
e700: 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73 68 6f 75  E_CANTOPEN] shou
e710: 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20  ld be returned. 
e720: 53 69 6e 63 65 20 74 68 69 73 20 69 73 0a 2a 2a  Since this is.**
e730: 20 68 61 6e 64 6c 65 64 20 61 73 20 61 20 66 61   handled as a fa
e740: 74 61 6c 20 65 72 72 6f 72 20 62 79 20 53 51 4c  tal error by SQL
e750: 69 74 65 2c 20 76 66 73 20 69 6d 70 6c 65 6d 65  ite, vfs impleme
e760: 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20  ntations should 
e770: 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74 6f 20 70  endeavor.** to p
e780: 72 65 76 65 6e 74 20 74 68 69 73 20 62 79 20 73  revent this by s
e790: 65 74 74 69 6e 67 20 6d 78 50 61 74 68 6e 61 6d  etting mxPathnam
e7a0: 65 20 74 6f 20 61 20 73 75 66 66 69 63 69 65 6e  e to a sufficien
e7b0: 74 6c 79 20 6c 61 72 67 65 20 76 61 6c 75 65 2e  tly large value.
e7c0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64  .**.** The xRand
e7d0: 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c 65 65 70  omness(), xSleep
e7e0: 28 29 2c 20 78 43 75 72 72 65 6e 74 54 69 6d 65  (), xCurrentTime
e7f0: 28 29 2c 20 61 6e 64 20 78 43 75 72 72 65 6e 74  (), and xCurrent
e800: 54 69 6d 65 49 6e 74 36 34 28 29 0a 2a 2a 20 69  TimeInt64().** i
e810: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 6e 6f  nterfaces are no
e820: 74 20 73 74 72 69 63 74 6c 79 20 61 20 70 61 72  t strictly a par
e830: 74 20 6f 66 20 74 68 65 20 66 69 6c 65 73 79 73  t of the filesys
e840: 74 65 6d 2c 20 62 75 74 20 74 68 65 79 20 61 72  tem, but they ar
e850: 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64 20 69 6e  e.** included in
e860: 20 74 68 65 20 56 46 53 20 73 74 72 75 63 74 75   the VFS structu
e870: 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65 74 65 6e  re for completen
e880: 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78 52 61 6e  ess..** The xRan
e890: 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e 63 74 69  domness() functi
e8a0: 6f 6e 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72  on attempts to r
e8b0: 65 74 75 72 6e 20 6e 42 79 74 65 73 20 62 79 74  eturn nBytes byt
e8c0: 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71 75  es.** of good-qu
e8d0: 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e 65 73 73  ality randomness
e8e0: 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20 54 68 65   into zOut.  The
e8f0: 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 69 73   return value is
e900: 0a 2a 2a 20 74 68 65 20 61 63 74 75 61 6c 20 6e  .** the actual n
e910: 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 6f  umber of bytes o
e920: 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74  f randomness obt
e930: 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 78 53  ained..** The xS
e940: 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 20 63 61  leep() method ca
e950: 75 73 65 73 20 74 68 65 20 63 61 6c 6c 69 6e 67  uses the calling
e960: 20 74 68 72 65 61 64 20 74 6f 20 73 6c 65 65 70   thread to sleep
e970: 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65 61 73 74   for at.** least
e980: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d   the number of m
e990: 69 63 72 6f 73 65 63 6f 6e 64 73 20 67 69 76 65  icroseconds give
e9a0: 6e 2e 20 20 5e 54 68 65 20 78 43 75 72 72 65 6e  n.  ^The xCurren
e9b0: 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65 74 68 6f  tTime().** metho
e9c0: 64 20 72 65 74 75 72 6e 73 20 61 20 4a 75 6c 69  d returns a Juli
e9d0: 61 6e 20 44 61 79 20 4e 75 6d 62 65 72 20 66 6f  an Day Number fo
e9e0: 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 61  r the current da
e9f0: 74 65 20 61 6e 64 20 74 69 6d 65 20 61 73 0a 2a  te and time as.*
ea00: 2a 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  * a floating poi
ea10: 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a 20 5e 54 68  nt value..** ^Th
ea20: 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e  e xCurrentTimeIn
ea30: 74 36 34 28 29 20 6d 65 74 68 6f 64 20 72 65 74  t64() method ret
ea40: 75 72 6e 73 2c 20 61 73 20 61 6e 20 69 6e 74 65  urns, as an inte
ea50: 67 65 72 2c 20 74 68 65 20 4a 75 6c 69 61 6e 0a  ger, the Julian.
ea60: 2a 2a 20 44 61 79 20 4e 75 6d 62 65 72 20 6d 75  ** Day Number mu
ea70: 6c 74 69 70 6c 65 64 20 62 79 20 38 36 34 30 30  ltipled by 86400
ea80: 30 30 30 20 28 74 68 65 20 6e 75 6d 62 65 72 20  000 (the number 
ea90: 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  of milliseconds 
eaa0: 69 6e 20 0a 2a 2a 20 61 20 32 34 2d 68 6f 75 72  in .** a 24-hour
eab0: 20 64 61 79 29 2e 20 20 0a 2a 2a 20 5e 53 51 4c   day).  .** ^SQL
eac0: 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74 68 65  ite will use the
ead0: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74   xCurrentTimeInt
eae0: 36 34 28 29 20 6d 65 74 68 6f 64 20 74 6f 20 67  64() method to g
eaf0: 65 74 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a  et the current.*
eb00: 2a 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20  * date and time 
eb10: 69 66 20 74 68 61 74 20 6d 65 74 68 6f 64 20 69  if that method i
eb20: 73 20 61 76 61 69 6c 61 62 6c 65 20 28 69 66 20  s available (if 
eb30: 69 56 65 72 73 69 6f 6e 20 69 73 20 32 20 6f 72  iVersion is 2 or
eb40: 20 0a 2a 2a 20 67 72 65 61 74 65 72 20 61 6e 64   .** greater and
eb50: 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f   the function po
eb60: 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c  inter is not NUL
eb70: 4c 29 20 61 6e 64 20 77 69 6c 6c 20 66 61 6c 6c  L) and will fall
eb80: 20 62 61 63 6b 0a 2a 2a 20 74 6f 20 78 43 75 72   back.** to xCur
eb90: 72 65 6e 74 54 69 6d 65 28 29 20 69 66 20 78 43  rentTime() if xC
eba0: 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28  urrentTimeInt64(
ebb0: 29 20 69 73 20 75 6e 61 76 61 69 6c 61 62 6c 65  ) is unavailable
ebc0: 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 53 65  ..**.** ^The xSe
ebd0: 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 2c 20 78  tSystemCall(), x
ebe0: 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 2c  GetSystemCall(),
ebf0: 20 61 6e 64 20 78 4e 65 73 74 53 79 73 74 65 6d   and xNestSystem
ec00: 43 61 6c 6c 28 29 20 69 6e 74 65 72 66 61 63 65  Call() interface
ec10: 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 75 73 65  s.** are not use
ec20: 64 20 62 79 20 74 68 65 20 53 51 4c 69 74 65 20  d by the SQLite 
ec30: 63 6f 72 65 2e 20 20 54 68 65 73 65 20 6f 70 74  core.  These opt
ec40: 69 6f 6e 61 6c 20 69 6e 74 65 72 66 61 63 65 73  ional interfaces
ec50: 20 61 72 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a   are provided.**
ec60: 20 62 79 20 73 6f 6d 65 20 56 46 53 65 73 20 74   by some VFSes t
ec70: 6f 20 66 61 63 69 6c 69 74 61 74 65 20 74 65 73  o facilitate tes
ec80: 74 69 6e 67 20 6f 66 20 74 68 65 20 56 46 53 20  ting of the VFS 
ec90: 63 6f 64 65 2e 20 42 79 20 6f 76 65 72 72 69 64  code. By overrid
eca0: 69 6e 67 20 0a 2a 2a 20 73 79 73 74 65 6d 20 63  ing .** system c
ecb0: 61 6c 6c 73 20 77 69 74 68 20 66 75 6e 63 74 69  alls with functi
ecc0: 6f 6e 73 20 75 6e 64 65 72 20 69 74 73 20 63 6f  ons under its co
ecd0: 6e 74 72 6f 6c 2c 20 61 20 74 65 73 74 20 70 72  ntrol, a test pr
ece0: 6f 67 72 61 6d 20 63 61 6e 0a 2a 2a 20 73 69 6d  ogram can.** sim
ecf0: 75 6c 61 74 65 20 66 61 75 6c 74 73 20 61 6e 64  ulate faults and
ed00: 20 65 72 72 6f 72 20 63 6f 6e 64 69 74 69 6f 6e   error condition
ed10: 73 20 74 68 61 74 20 77 6f 75 6c 64 20 6f 74 68  s that would oth
ed20: 65 72 77 69 73 65 20 62 65 20 64 69 66 66 69 63  erwise be diffic
ed30: 75 6c 74 0a 2a 2a 20 6f 72 20 69 6d 70 6f 73 73  ult.** or imposs
ed40: 69 62 6c 65 20 74 6f 20 69 6e 64 75 63 65 2e 20  ible to induce. 
ed50: 20 54 68 65 20 73 65 74 20 6f 66 20 73 79 73 74   The set of syst
ed60: 65 6d 20 63 61 6c 6c 73 20 74 68 61 74 20 63 61  em calls that ca
ed70: 6e 20 62 65 20 6f 76 65 72 72 69 64 64 65 6e 0a  n be overridden.
ed80: 2a 2a 20 76 61 72 69 65 73 20 66 72 6f 6d 20 6f  ** varies from o
ed90: 6e 65 20 56 46 53 20 74 6f 20 61 6e 6f 74 68 65  ne VFS to anothe
eda0: 72 2c 20 61 6e 64 20 66 72 6f 6d 20 6f 6e 65 20  r, and from one 
edb0: 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 73  version of the s
edc0: 61 6d 65 20 56 46 53 20 74 6f 20 74 68 65 0a 2a  ame VFS to the.*
edd0: 2a 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 61  * next.  Applica
ede0: 74 69 6f 6e 73 20 74 68 61 74 20 75 73 65 20 74  tions that use t
edf0: 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20  hese interfaces 
ee00: 6d 75 73 74 20 62 65 20 70 72 65 70 61 72 65 64  must be prepared
ee10: 20 66 6f 72 20 61 6e 79 0a 2a 2a 20 6f 72 20 61   for any.** or a
ee20: 6c 6c 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65  ll of these inte
ee30: 72 66 61 63 65 73 20 74 6f 20 62 65 20 4e 55 4c  rfaces to be NUL
ee40: 4c 20 6f 72 20 66 6f 72 20 74 68 65 69 72 20 62  L or for their b
ee50: 65 68 61 76 69 6f 72 20 74 6f 20 63 68 61 6e 67  ehavior to chang
ee60: 65 0a 2a 2a 20 66 72 6f 6d 20 6f 6e 65 20 72 65  e.** from one re
ee70: 6c 65 61 73 65 20 74 6f 20 74 68 65 20 6e 65 78  lease to the nex
ee80: 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  t.  Applications
ee90: 20 6d 75 73 74 20 6e 6f 74 20 61 74 74 65 6d 70   must not attemp
eea0: 74 20 74 6f 20 61 63 63 65 73 73 0a 2a 2a 20 61  t to access.** a
eeb0: 6e 79 20 6f 66 20 74 68 65 73 65 20 6d 65 74 68  ny of these meth
eec0: 6f 64 73 20 69 66 20 74 68 65 20 69 56 65 72 73  ods if the iVers
eed0: 69 6f 6e 20 6f 66 20 74 68 65 20 56 46 53 20 69  ion of the VFS i
eee0: 73 20 6c 65 73 73 20 74 68 61 6e 20 33 2e 0a 2a  s less than 3..*
eef0: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
ef00: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 73 71 6c   sqlite3_vfs sql
ef10: 69 74 65 33 5f 76 66 73 3b 0a 74 79 70 65 64 65  ite3_vfs;.typede
ef20: 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65 33  f void (*sqlite3
ef30: 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 28 76 6f  _syscall_ptr)(vo
ef40: 69 64 29 3b 0a 73 74 72 75 63 74 20 73 71 6c 69  id);.struct sqli
ef50: 74 65 33 5f 76 66 73 20 7b 0a 20 20 69 6e 74 20  te3_vfs {.  int 
ef60: 69 56 65 72 73 69 6f 6e 3b 20 20 20 20 20 20 20  iVersion;       
ef70: 20 20 20 20 20 2f 2a 20 53 74 72 75 63 74 75 72       /* Structur
ef80: 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72  e version number
ef90: 20 28 63 75 72 72 65 6e 74 6c 79 20 33 29 20 2a   (currently 3) *
efa0: 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 46 69 6c 65  /.  int szOsFile
efb0: 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ;            /* 
efc0: 53 69 7a 65 20 6f 66 20 73 75 62 63 6c 61 73 73  Size of subclass
efd0: 65 64 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20  ed sqlite3_file 
efe0: 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 61 74 68 6e  */.  int mxPathn
eff0: 61 6d 65 3b 20 20 20 20 20 20 20 20 20 20 2f 2a  ame;          /*
f000: 20 4d 61 78 69 6d 75 6d 20 66 69 6c 65 20 70 61   Maximum file pa
f010: 74 68 6e 61 6d 65 20 6c 65 6e 67 74 68 20 2a 2f  thname length */
f020: 0a 20 20 73 71 6c 69 74 65 33 5f 76 66 73 20 2a  .  sqlite3_vfs *
f030: 70 4e 65 78 74 3b 20 20 20 20 20 20 2f 2a 20 4e  pNext;      /* N
f040: 65 78 74 20 72 65 67 69 73 74 65 72 65 64 20 56  ext registered V
f050: 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  FS */.  const ch
f060: 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 20 20 20 20  ar *zName;      
f070: 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 69 73   /* Name of this
f080: 20 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79   virtual file sy
f090: 73 74 65 6d 20 2a 2f 0a 20 20 76 6f 69 64 20 2a  stem */.  void *
f0a0: 70 41 70 70 44 61 74 61 3b 20 20 20 20 20 20 20  pAppData;       
f0b0: 20 20 20 2f 2a 20 50 6f 69 6e 74 65 72 20 74 6f     /* Pointer to
f0c0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 70 65   application-spe
f0d0: 63 69 66 69 63 20 64 61 74 61 20 2a 2f 0a 20 20  cific data */.  
f0e0: 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c  int (*xOpen)(sql
f0f0: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
f100: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71   char *zName, sq
f110: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 0a 20 20 20  lite3_file*,.   
f120: 20 20 20 20 20 20 20 20 20 20 20 20 69 6e 74 20              int 
f130: 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 4f 75 74  flags, int *pOut
f140: 46 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a  Flags);.  int (*
f150: 78 44 65 6c 65 74 65 29 28 73 71 6c 69 74 65 33  xDelete)(sqlite3
f160: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
f170: 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 73 79  r *zName, int sy
f180: 6e 63 44 69 72 29 3b 0a 20 20 69 6e 74 20 28 2a  ncDir);.  int (*
f190: 78 41 63 63 65 73 73 29 28 73 71 6c 69 74 65 33  xAccess)(sqlite3
f1a0: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
f1b0: 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 66 6c  r *zName, int fl
f1c0: 61 67 73 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75  ags, int *pResOu
f1d0: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 75 6c  t);.  int (*xFul
f1e0: 6c 50 61 74 68 6e 61 6d 65 29 28 73 71 6c 69 74  lPathname)(sqlit
f1f0: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
f200: 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20  har *zName, int 
f210: 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a 4f 75 74  nOut, char *zOut
f220: 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 44 6c  );.  void *(*xDl
f230: 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66  Open)(sqlite3_vf
f240: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
f250: 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a 20 20 76 6f  zFilename);.  vo
f260: 69 64 20 28 2a 78 44 6c 45 72 72 6f 72 29 28 73  id (*xDlError)(s
f270: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74  qlite3_vfs*, int
f280: 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 45   nByte, char *zE
f290: 72 72 4d 73 67 29 3b 0a 20 20 76 6f 69 64 20 28  rrMsg);.  void (
f2a0: 2a 28 2a 78 44 6c 53 79 6d 29 28 73 71 6c 69 74  *(*xDlSym)(sqlit
f2b0: 65 33 5f 76 66 73 2a 2c 76 6f 69 64 2a 2c 20 63  e3_vfs*,void*, c
f2c0: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 79 6d 62  onst char *zSymb
f2d0: 6f 6c 29 29 28 76 6f 69 64 29 3b 0a 20 20 76 6f  ol))(void);.  vo
f2e0: 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65 29 28 73  id (*xDlClose)(s
f2f0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 76 6f 69  qlite3_vfs*, voi
f300: 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 61  d*);.  int (*xRa
f310: 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c 69 74 65  ndomness)(sqlite
f320: 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74  3_vfs*, int nByt
f330: 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a  e, char *zOut);.
f340: 20 20 69 6e 74 20 28 2a 78 53 6c 65 65 70 29 28    int (*xSleep)(
f350: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e  sqlite3_vfs*, in
f360: 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 29 3b  t microseconds);
f370: 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72 65 6e  .  int (*xCurren
f380: 74 54 69 6d 65 29 28 73 71 6c 69 74 65 33 5f 76  tTime)(sqlite3_v
f390: 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b 0a 20  fs*, double*);. 
f3a0: 20 69 6e 74 20 28 2a 78 47 65 74 4c 61 73 74 45   int (*xGetLastE
f3b0: 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66  rror)(sqlite3_vf
f3c0: 73 2a 2c 20 69 6e 74 2c 20 63 68 61 72 20 2a 29  s*, int, char *)
f3d0: 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20  ;.  /*.  ** The 
f3e0: 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72  methods above ar
f3f0: 65 20 69 6e 20 76 65 72 73 69 6f 6e 20 31 20 6f  e in version 1 o
f400: 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73  f the sqlite_vfs
f410: 20 6f 62 6a 65 63 74 0a 20 20 2a 2a 20 64 65 66   object.  ** def
f420: 69 6e 69 74 69 6f 6e 2e 20 20 54 68 6f 73 65 20  inition.  Those 
f430: 74 68 61 74 20 66 6f 6c 6c 6f 77 20 61 72 65 20  that follow are 
f440: 61 64 64 65 64 20 69 6e 20 76 65 72 73 69 6f 6e  added in version
f450: 20 32 20 6f 72 20 6c 61 74 65 72 0a 20 20 2a 2f   2 or later.  */
f460: 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72 65 6e  .  int (*xCurren
f470: 74 54 69 6d 65 49 6e 74 36 34 29 28 73 71 6c 69  tTimeInt64)(sqli
f480: 74 65 33 5f 76 66 73 2a 2c 20 73 71 6c 69 74 65  te3_vfs*, sqlite
f490: 33 5f 69 6e 74 36 34 2a 29 3b 0a 20 20 2f 2a 0a  3_int64*);.  /*.
f4a0: 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73    ** The methods
f4b0: 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65   above are in ve
f4c0: 72 73 69 6f 6e 73 20 31 20 61 6e 64 20 32 20 6f  rsions 1 and 2 o
f4d0: 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73  f the sqlite_vfs
f4e0: 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 54 68   object..  ** Th
f4f0: 6f 73 65 20 62 65 6c 6f 77 20 61 72 65 20 66 6f  ose below are fo
f500: 72 20 76 65 72 73 69 6f 6e 20 33 20 61 6e 64 20  r version 3 and 
f510: 67 72 65 61 74 65 72 2e 0a 20 20 2a 2f 0a 20 20  greater..  */.  
f520: 69 6e 74 20 28 2a 78 53 65 74 53 79 73 74 65 6d  int (*xSetSystem
f530: 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66  Call)(sqlite3_vf
f540: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
f550: 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f 73  zName, sqlite3_s
f560: 79 73 63 61 6c 6c 5f 70 74 72 29 3b 0a 20 20 73  yscall_ptr);.  s
f570: 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70  qlite3_syscall_p
f580: 74 72 20 28 2a 78 47 65 74 53 79 73 74 65 6d 43  tr (*xGetSystemC
f590: 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73  all)(sqlite3_vfs
f5a0: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
f5b0: 4e 61 6d 65 29 3b 0a 20 20 63 6f 6e 73 74 20 63  Name);.  const c
f5c0: 68 61 72 20 2a 28 2a 78 4e 65 78 74 53 79 73 74  har *(*xNextSyst
f5d0: 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f  emCall)(sqlite3_
f5e0: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
f5f0: 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 2f 2a 0a 20   *zName);.  /*. 
f600: 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20   ** The methods 
f610: 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72  above are in ver
f620: 73 69 6f 6e 73 20 31 20 74 68 72 6f 75 67 68 20  sions 1 through 
f630: 33 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f  3 of the sqlite_
f640: 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a  vfs object..  **
f650: 20 4e 65 77 20 66 69 65 6c 64 73 20 6d 61 79 20   New fields may 
f660: 62 65 20 61 70 70 65 6e 64 65 64 20 69 6e 20 66  be appended in f
f670: 69 67 75 72 65 20 76 65 72 73 69 6f 6e 73 2e 20  igure versions. 
f680: 20 54 68 65 20 69 56 65 72 73 69 6f 6e 0a 20 20   The iVersion.  
f690: 2a 2a 20 76 61 6c 75 65 20 77 69 6c 6c 20 69 6e  ** value will in
f6a0: 63 72 65 6d 65 6e 74 20 77 68 65 6e 65 76 65 72  crement whenever
f6b0: 20 74 68 69 73 20 68 61 70 70 65 6e 73 2e 20 0a   this happens. .
f6c0: 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43    */.};../*.** C
f6d0: 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66  API3REF: Flags f
f6e0: 6f 72 20 74 68 65 20 78 41 63 63 65 73 73 20 56  or the xAccess V
f6f0: 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20  FS method.**.** 
f700: 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f  These integer co
f710: 6e 73 74 61 6e 74 73 20 63 61 6e 20 62 65 20 75  nstants can be u
f720: 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64  sed as the third
f730: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
f740: 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74   the xAccess met
f750: 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74  hod of an [sqlit
f760: 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 20  e3_vfs] object. 
f770: 20 54 68 65 79 20 64 65 74 65 72 6d 69 6e 65 0a   They determine.
f780: 2a 2a 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20  ** what kind of 
f790: 70 65 72 6d 69 73 73 69 6f 6e 73 20 74 68 65 20  permissions the 
f7a0: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20 69  xAccess method i
f7b0: 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e 0a 2a  s looking for..*
f7c0: 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43  * With SQLITE_AC
f7d0: 43 45 53 53 5f 45 58 49 53 54 53 2c 20 74 68 65  CESS_EXISTS, the
f7e0: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a   xAccess method.
f7f0: 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65 63 6b 73  ** simply checks
f800: 20 77 68 65 74 68 65 72 20 74 68 65 20 66 69 6c   whether the fil
f810: 65 20 65 78 69 73 74 73 2e 0a 2a 2a 20 57 69 74  e exists..** Wit
f820: 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  h SQLITE_ACCESS_
f830: 52 45 41 44 57 52 49 54 45 2c 20 74 68 65 20 78  READWRITE, the x
f840: 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a  Access method.**
f850: 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20   checks whether 
f860: 74 68 65 20 6e 61 6d 65 64 20 64 69 72 65 63 74  the named direct
f870: 6f 72 79 20 69 73 20 62 6f 74 68 20 72 65 61 64  ory is both read
f880: 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62 6c  able and writabl
f890: 65 0a 2a 2a 20 28 69 6e 20 6f 74 68 65 72 20 77  e.** (in other w
f8a0: 6f 72 64 73 2c 20 69 66 20 66 69 6c 65 73 20 63  ords, if files c
f8b0: 61 6e 20 62 65 20 61 64 64 65 64 2c 20 72 65 6d  an be added, rem
f8c0: 6f 76 65 64 2c 20 61 6e 64 20 72 65 6e 61 6d 65  oved, and rename
f8d0: 64 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20  d within.** the 
f8e0: 64 69 72 65 63 74 6f 72 79 29 2e 0a 2a 2a 20 54  directory)..** T
f8f0: 68 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  he SQLITE_ACCESS
f900: 5f 52 45 41 44 57 52 49 54 45 20 63 6f 6e 73 74  _READWRITE const
f910: 61 6e 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79  ant is currently
f920: 20 75 73 65 64 20 6f 6e 6c 79 20 62 79 20 74 68   used only by th
f930: 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73 74 6f 72 65  e.** [temp_store
f940: 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d  _directory pragm
f950: 61 5d 2c 20 74 68 6f 75 67 68 20 74 68 69 73 20  a], though this 
f960: 63 6f 75 6c 64 20 63 68 61 6e 67 65 20 69 6e 20  could change in 
f970: 61 20 66 75 74 75 72 65 0a 2a 2a 20 72 65 6c 65  a future.** rele
f980: 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ase of SQLite..*
f990: 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43  * With SQLITE_AC
f9a0: 43 45 53 53 5f 52 45 41 44 2c 20 74 68 65 20 78  CESS_READ, the x
f9b0: 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a  Access method.**
f9c0: 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20   checks whether 
f9d0: 74 68 65 20 66 69 6c 65 20 69 73 20 72 65 61 64  the file is read
f9e0: 61 62 6c 65 2e 20 20 54 68 65 20 53 51 4c 49 54  able.  The SQLIT
f9f0: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20 63 6f  E_ACCESS_READ co
fa00: 6e 73 74 61 6e 74 20 69 73 0a 2a 2a 20 63 75 72  nstant is.** cur
fa10: 72 65 6e 74 6c 79 20 75 6e 75 73 65 64 2c 20 74  rently unused, t
fa20: 68 6f 75 67 68 20 69 74 20 6d 69 67 68 74 20 62  hough it might b
fa30: 65 20 75 73 65 64 20 69 6e 20 61 20 66 75 74 75  e used in a futu
fa40: 72 65 20 72 65 6c 65 61 73 65 20 6f 66 0a 2a 2a  re release of.**
fa50: 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66   SQLite..*/.#def
fa60: 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ine SQLITE_ACCES
fa70: 53 5f 45 58 49 53 54 53 20 20 20 20 30 0a 23 64  S_EXISTS    0.#d
fa80: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43  efine SQLITE_ACC
fa90: 45 53 53 5f 52 45 41 44 57 52 49 54 45 20 31 20  ESS_READWRITE 1 
faa0: 20 20 2f 2a 20 55 73 65 64 20 62 79 20 50 52 41    /* Used by PRA
fab0: 47 4d 41 20 74 65 6d 70 5f 73 74 6f 72 65 5f 64  GMA temp_store_d
fac0: 69 72 65 63 74 6f 72 79 20 2a 2f 0a 23 64 65 66  irectory */.#def
fad0: 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ine SQLITE_ACCES
fae0: 53 5f 52 45 41 44 20 20 20 20 20 20 32 20 20 20  S_READ      2   
faf0: 2f 2a 20 55 6e 75 73 65 64 20 2a 2f 0a 0a 2f 2a  /* Unused */../*
fb00: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c  .** CAPI3REF: Fl
fb10: 61 67 73 20 66 6f 72 20 74 68 65 20 78 53 68 6d  ags for the xShm
fb20: 4c 6f 63 6b 20 56 46 53 20 6d 65 74 68 6f 64 0a  Lock VFS method.
fb30: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65  **.** These inte
fb40: 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 64 65  ger constants de
fb50: 66 69 6e 65 20 74 68 65 20 76 61 72 69 6f 75 73  fine the various
fb60: 20 6c 6f 63 6b 69 6e 67 20 6f 70 65 72 61 74 69   locking operati
fb70: 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20 62  ons.** allowed b
fb80: 79 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d  y the xShmLock m
fb90: 65 74 68 6f 64 20 6f 66 20 5b 73 71 6c 69 74 65  ethod of [sqlite
fba0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 2e 20 20  3_io_methods].  
fbb0: 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67  The.** following
fbc0: 20 61 72 65 20 74 68 65 20 6f 6e 6c 79 20 6c 65   are the only le
fbd0: 67 61 6c 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73  gal combinations
fbe0: 20 6f 66 20 66 6c 61 67 73 20 74 6f 20 74 68 65   of flags to the
fbf0: 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74  .** xShmLock met
fc00: 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  hod:.**.** <ul>.
fc10: 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f  ** <li>  SQLITE_
fc20: 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54  SHM_LOCK | SQLIT
fc30: 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a 20  E_SHM_SHARED.** 
fc40: 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d  <li>  SQLITE_SHM
fc50: 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53  _LOCK | SQLITE_S
fc60: 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20  HM_EXCLUSIVE.** 
fc70: 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d  <li>  SQLITE_SHM
fc80: 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45  _UNLOCK | SQLITE
fc90: 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c  _SHM_SHARED.** <
fca0: 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f  li>  SQLITE_SHM_
fcb0: 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f  UNLOCK | SQLITE_
fcc0: 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a 2a  SHM_EXCLUSIVE.**
fcd0: 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 57 68 65   </ul>.**.** Whe
fce0: 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c 20 74 68 65  n unlocking, the
fcf0: 20 73 61 6d 65 20 53 48 41 52 45 44 20 6f 72 20   same SHARED or 
fd00: 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67 20 6d  EXCLUSIVE flag m
fd10: 75 73 74 20 62 65 20 73 75 70 70 6c 69 65 64 20  ust be supplied 
fd20: 61 73 0a 2a 2a 20 77 61 73 20 67 69 76 65 6e 20  as.** was given 
fd30: 6e 6f 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  no the correspon
fd40: 64 69 6e 67 20 6c 6f 63 6b 2e 20 20 0a 2a 2a 0a  ding lock.  .**.
fd50: 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20  ** The xShmLock 
fd60: 6d 65 74 68 6f 64 20 63 61 6e 20 74 72 61 6e 73  method can trans
fd70: 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 75 6e  ition between un
fd80: 6c 6f 63 6b 65 64 20 61 6e 64 20 53 48 41 52 45  locked and SHARE
fd90: 44 20 6f 72 0a 2a 2a 20 62 65 74 77 65 65 6e 20  D or.** between 
fda0: 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 45 58 43  unlocked and EXC
fdb0: 4c 55 53 49 56 45 2e 20 20 49 74 20 63 61 6e 6e  LUSIVE.  It cann
fdc0: 6f 74 20 74 72 61 6e 73 69 74 69 6f 6e 20 62 65  ot transition be
fdd0: 74 77 65 65 6e 20 53 48 41 52 45 44 0a 2a 2a 20  tween SHARED.** 
fde0: 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e 0a 2a  and EXCLUSIVE..*
fdf0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
fe00: 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 20 20 20 20  _SHM_UNLOCK     
fe10: 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
fe20: 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 20 20 20 20  TE_SHM_LOCK     
fe30: 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
fe40: 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 20  LITE_SHM_SHARED 
fe50: 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20        4.#define 
fe60: 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55  SQLITE_SHM_EXCLU
fe70: 53 49 56 45 20 20 20 20 38 0a 0a 2f 2a 0a 2a 2a  SIVE    8../*.**
fe80: 20 43 41 50 49 33 52 45 46 3a 20 4d 61 78 69 6d   CAPI3REF: Maxim
fe90: 75 6d 20 78 53 68 6d 4c 6f 63 6b 20 69 6e 64 65  um xShmLock inde
fea0: 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d  x.**.** The xShm
feb0: 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 6e 20 5b  Lock method on [
fec0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
fed0: 64 73 5d 20 6d 61 79 20 75 73 65 20 76 61 6c 75  ds] may use valu
fee0: 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 20  es.** between 0 
fef0: 61 6e 64 20 74 68 69 73 20 75 70 70 65 72 20 62  and this upper b
ff00: 6f 75 6e 64 20 61 73 20 69 74 73 20 22 6f 66 66  ound as its "off
ff10: 73 65 74 22 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  set" argument..*
ff20: 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72  * The SQLite cor
ff30: 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 61 74 74  e will never att
ff40: 65 6d 70 74 20 74 6f 20 61 63 71 75 69 72 65 20  empt to acquire 
ff50: 6f 72 20 72 65 6c 65 61 73 65 20 61 0a 2a 2a 20  or release a.** 
ff60: 6c 6f 63 6b 20 6f 75 74 73 69 64 65 20 6f 66 20  lock outside of 
ff70: 74 68 69 73 20 72 61 6e 67 65 0a 2a 2f 0a 23 64  this range.*/.#d
ff80: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d  efine SQLITE_SHM
ff90: 5f 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20 38 0a  _NLOCK        8.
ffa0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
ffb0: 3a 20 49 6e 69 74 69 61 6c 69 7a 65 20 54 68 65  : Initialize The
ffc0: 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79 0a   SQLite Library.
ffd0: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
ffe0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
fff0: 72 6f 75 74 69 6e 65 20 69 6e 69 74 69 61 6c 69  routine initiali
10000 7a 65 73 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74  zes the.** SQLit
10010 65 20 6c 69 62 72 61 72 79 2e 20 20 5e 54 68 65  e library.  ^The
10020 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
10030 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 64  n() routine.** d
10040 65 61 6c 6c 6f 63 61 74 65 73 20 61 6e 79 20 72  eallocates any r
10050 65 73 6f 75 72 63 65 73 20 74 68 61 74 20 77 65  esources that we
10060 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20  re allocated by 
10070 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
10080 7a 65 28 29 2e 0a 2a 2a 20 54 68 65 73 65 20 72  ze()..** These r
10090 6f 75 74 69 6e 65 73 20 61 72 65 20 64 65 73 69  outines are desi
100a0 67 6e 65 64 20 74 6f 20 61 69 64 20 69 6e 20 70  gned to aid in p
100b0 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69 7a  rocess initializ
100c0 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 73 68 75  ation and.** shu
100d0 74 64 6f 77 6e 20 6f 6e 20 65 6d 62 65 64 64 65  tdown on embedde
100e0 64 20 73 79 73 74 65 6d 73 2e 20 20 57 6f 72 6b  d systems.  Work
100f0 73 74 61 74 69 6f 6e 20 61 70 70 6c 69 63 61 74  station applicat
10100 69 6f 6e 73 20 75 73 69 6e 67 0a 2a 2a 20 53 51  ions using.** SQ
10110 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c 79 20 64 6f  Lite normally do
10120 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 69 6e 76   not need to inv
10130 6f 6b 65 20 65 69 74 68 65 72 20 6f 66 20 74 68  oke either of th
10140 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  ese routines..**
10150 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71  .** A call to sq
10160 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
10170 28 29 20 69 73 20 61 6e 20 22 65 66 66 65 63 74  () is an "effect
10180 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20  ive" call if it 
10190 69 73 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20  is.** the first 
101a0 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69  time sqlite3_ini
101b0 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76  tialize() is inv
101c0 6f 6b 65 64 20 64 75 72 69 6e 67 20 74 68 65 20  oked during the 
101d0 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a 2a 20 74  lifetime of.** t
101e0 68 65 20 70 72 6f 63 65 73 73 2c 20 6f 72 20 69  he process, or i
101f0 66 20 69 74 20 69 73 20 74 68 65 20 66 69 72 73  f it is the firs
10200 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69  t time sqlite3_i
10210 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69  nitialize() is i
10220 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77  nvoked.** follow
10230 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 73 71  ing a call to sq
10240 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
10250 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e 20 65 66 66  .  ^(Only an eff
10260 65 63 74 69 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f  ective call.** o
10270 66 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  f sqlite3_initia
10280 6c 69 7a 65 28 29 20 64 6f 65 73 20 61 6e 79 20  lize() does any 
10290 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 20  initialization. 
102a0 20 41 6c 6c 20 6f 74 68 65 72 20 63 61 6c 6c 73   All other calls
102b0 0a 2a 2a 20 61 72 65 20 68 61 72 6d 6c 65 73 73  .** are harmless
102c0 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a   no-ops.)^.**.**
102d0 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74   A call to sqlit
102e0 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 73  e3_shutdown() is
102f0 20 61 6e 20 22 65 66 66 65 63 74 69 76 65 22 20   an "effective" 
10300 63 61 6c 6c 20 69 66 20 69 74 20 69 73 20 74 68  call if it is th
10310 65 20 66 69 72 73 74 0a 2a 2a 20 63 61 6c 6c 20  e first.** call 
10320 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  to sqlite3_shutd
10330 6f 77 6e 28 29 20 73 69 6e 63 65 20 74 68 65 20  own() since the 
10340 6c 61 73 74 20 73 71 6c 69 74 65 33 5f 69 6e 69  last sqlite3_ini
10350 74 69 61 6c 69 7a 65 28 29 2e 20 20 5e 28 4f 6e  tialize().  ^(On
10360 6c 79 0a 2a 2a 20 61 6e 20 65 66 66 65 63 74 69  ly.** an effecti
10370 76 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  ve call to sqlit
10380 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 64 6f  e3_shutdown() do
10390 65 73 20 61 6e 79 20 64 65 69 6e 69 74 69 61 6c  es any deinitial
103a0 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20  ization..** All 
103b0 6f 74 68 65 72 20 76 61 6c 69 64 20 63 61 6c 6c  other valid call
103c0 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75  s to sqlite3_shu
103d0 74 64 6f 77 6e 28 29 20 61 72 65 20 68 61 72 6d  tdown() are harm
103e0 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a  less no-ops.)^.*
103f0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
10400 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 6e  _initialize() in
10410 74 65 72 66 61 63 65 20 69 73 20 74 68 72 65 61  terface is threa
10420 64 73 61 66 65 2c 20 62 75 74 20 73 71 6c 69 74  dsafe, but sqlit
10430 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a  e3_shutdown().**
10440 20 69 73 20 6e 6f 74 2e 20 20 54 68 65 20 73 71   is not.  The sq
10450 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
10460 20 69 6e 74 65 72 66 61 63 65 20 6d 75 73 74 20   interface must 
10470 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 66  only be called f
10480 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e 67 6c 65 20  rom a.** single 
10490 74 68 72 65 61 64 2e 20 20 41 6c 6c 20 6f 70 65  thread.  All ope
104a0 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  n [database conn
104b0 65 63 74 69 6f 6e 73 5d 20 6d 75 73 74 20 62 65  ections] must be
104c0 20 63 6c 6f 73 65 64 20 61 6e 64 20 61 6c 6c 0a   closed and all.
104d0 2a 2a 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  ** other SQLite 
104e0 72 65 73 6f 75 72 63 65 73 20 6d 75 73 74 20 62  resources must b
104f0 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 70 72  e deallocated pr
10500 69 6f 72 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 0a  ior to invoking.
10510 2a 2a 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  ** sqlite3_shutd
10520 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f  own()..**.** Amo
10530 6e 67 20 6f 74 68 65 72 20 74 68 69 6e 67 73 2c  ng other things,
10540 20 5e 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61   ^sqlite3_initia
10550 6c 69 7a 65 28 29 20 77 69 6c 6c 20 69 6e 76 6f  lize() will invo
10560 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73  ke.** sqlite3_os
10570 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d 69 6c 61  _init().  Simila
10580 72 6c 79 2c 20 5e 73 71 6c 69 74 65 33 5f 73 68  rly, ^sqlite3_sh
10590 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 77 69 6c 6c  utdown().** will
105a0 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f   invoke sqlite3_
105b0 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20  os_end()..**.** 
105c0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69  ^The sqlite3_ini
105d0 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e  tialize() routin
105e0 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  e returns [SQLIT
105f0 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73  E_OK] on success
10600 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72 20 73 6f 6d  ..** ^If for som
10610 65 20 72 65 61 73 6f 6e 2c 20 73 71 6c 69 74 65  e reason, sqlite
10620 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
10630 73 20 75 6e 61 62 6c 65 20 74 6f 20 69 6e 69 74  s unable to init
10640 69 61 6c 69 7a 65 0a 2a 2a 20 74 68 65 20 6c 69  ialize.** the li
10650 62 72 61 72 79 20 28 70 65 72 68 61 70 73 20 69  brary (perhaps i
10660 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61  t is unable to a
10670 6c 6c 6f 63 61 74 65 20 61 20 6e 65 65 64 65 64  llocate a needed
10680 20 72 65 73 6f 75 72 63 65 20 73 75 63 68 0a 2a   resource such.*
10690 2a 20 61 73 20 61 20 6d 75 74 65 78 29 20 69 74  * as a mutex) it
106a0 20 72 65 74 75 72 6e 73 20 61 6e 20 5b 65 72 72   returns an [err
106b0 6f 72 20 63 6f 64 65 5d 20 6f 74 68 65 72 20 74  or code] other t
106c0 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e  han [SQLITE_OK].
106d0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
106e0 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
106f0 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c   routine is call
10700 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79  ed internally by
10710 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 53   many other.** S
10720 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73  QLite interfaces
10730 20 73 6f 20 74 68 61 74 20 61 6e 20 61 70 70 6c   so that an appl
10740 69 63 61 74 69 6f 6e 20 75 73 75 61 6c 6c 79 20  ication usually 
10750 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f  does not need to
10760 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74  .** invoke sqlit
10770 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
10780 64 69 72 65 63 74 6c 79 2e 20 20 46 6f 72 20 65  directly.  For e
10790 78 61 6d 70 6c 65 2c 20 5b 73 71 6c 69 74 65 33  xample, [sqlite3
107a0 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c  _open()].** call
107b0 73 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  s sqlite3_initia
107c0 6c 69 7a 65 28 29 20 73 6f 20 74 68 65 20 53 51  lize() so the SQ
107d0 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c  Lite library wil
107e0 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c  l be automatical
107f0 6c 79 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 65  ly.** initialize
10800 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f  d when [sqlite3_
10810 6f 70 65 6e 28 29 5d 20 69 73 20 63 61 6c 6c 65  open()] is calle
10820 64 20 69 66 20 69 74 20 68 61 73 20 6e 6f 74 20  d if it has not 
10830 62 65 20 69 6e 69 74 69 61 6c 69 7a 65 64 0a 2a  be initialized.*
10840 2a 20 61 6c 72 65 61 64 79 2e 20 20 5e 48 6f 77  * already.  ^How
10850 65 76 65 72 2c 20 69 66 20 53 51 4c 69 74 65 20  ever, if SQLite 
10860 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
10870 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49   the [SQLITE_OMI
10880 54 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a 2a 20 63  T_AUTOINIT].** c
10890 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
108a0 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 61 75 74  on, then the aut
108b0 6f 6d 61 74 69 63 20 63 61 6c 6c 73 20 74 6f 20  omatic calls to 
108c0 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
108d0 7a 65 28 29 0a 2a 2a 20 61 72 65 20 6f 6d 69 74  ze().** are omit
108e0 74 65 64 20 61 6e 64 20 74 68 65 20 61 70 70 6c  ted and the appl
108f0 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 63 61 6c  ication must cal
10900 6c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  l sqlite3_initia
10910 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79 0a  lize() directly.
10920 2a 2a 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e  ** prior to usin
10930 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69  g any other SQLi
10940 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46  te interface.  F
10950 6f 72 20 6d 61 78 69 6d 75 6d 20 70 6f 72 74 61  or maximum porta
10960 62 69 6c 69 74 79 2c 0a 2a 2a 20 69 74 20 69 73  bility,.** it is
10970 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61   recommended tha
10980 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61  t applications a
10990 6c 77 61 79 73 20 69 6e 76 6f 6b 65 20 73 71 6c  lways invoke sql
109a0 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
109b0 29 0a 2a 2a 20 64 69 72 65 63 74 6c 79 20 70 72  ).** directly pr
109c0 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79  ior to using any
109d0 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e   other SQLite in
109e0 74 65 72 66 61 63 65 2e 20 20 46 75 74 75 72 65  terface.  Future
109f0 20 72 65 6c 65 61 73 65 73 0a 2a 2a 20 6f 66 20   releases.** of 
10a00 53 51 4c 69 74 65 20 6d 61 79 20 72 65 71 75 69  SQLite may requi
10a10 72 65 20 74 68 69 73 2e 20 20 49 6e 20 6f 74 68  re this.  In oth
10a20 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 62 65  er words, the be
10a30 68 61 76 69 6f 72 20 65 78 68 69 62 69 74 65 64  havior exhibited
10a40 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20  .** when SQLite 
10a50 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
10a60 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55   [SQLITE_OMIT_AU
10a70 54 4f 49 4e 49 54 5d 20 6d 69 67 68 74 20 62 65  TOINIT] might be
10a80 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 64 65 66 61  come the.** defa
10a90 75 6c 74 20 62 65 68 61 76 69 6f 72 20 69 6e 20  ult behavior in 
10aa0 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65 6c 65  some future rele
10ab0 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ase of SQLite..*
10ac0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
10ad0 5f 6f 73 5f 69 6e 69 74 28 29 20 72 6f 75 74 69  _os_init() routi
10ae0 6e 65 20 64 6f 65 73 20 6f 70 65 72 61 74 69 6e  ne does operatin
10af0 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 69  g-system specifi
10b00 63 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 61 74  c.** initializat
10b10 69 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c 69 74  ion of the SQLit
10b20 65 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20  e library.  The 
10b30 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
10b40 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e 64 6f  .** routine undo
10b50 65 73 20 74 68 65 20 65 66 66 65 63 74 20 6f 66  es the effect of
10b60 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
10b70 28 29 2e 20 20 54 79 70 69 63 61 6c 20 74 61 73  ().  Typical tas
10b80 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20  ks.** performed 
10b90 62 79 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  by these routine
10ba0 73 20 69 6e 63 6c 75 64 65 20 61 6c 6c 6f 63 61  s include alloca
10bb0 74 69 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61  tion or dealloca
10bc0 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61 74 69  tion.** of stati
10bd0 63 20 72 65 73 6f 75 72 63 65 73 2c 20 69 6e 69  c resources, ini
10be0 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 67  tialization of g
10bf0 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 73 2c  lobal variables,
10c00 0a 2a 2a 20 73 65 74 74 69 6e 67 20 75 70 20 61  .** setting up a
10c10 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65   default [sqlite
10c20 33 5f 76 66 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f  3_vfs] module, o
10c30 72 20 73 65 74 74 69 6e 67 20 75 70 0a 2a 2a 20  r setting up.** 
10c40 61 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67  a default config
10c50 75 72 61 74 69 6f 6e 20 75 73 69 6e 67 20 5b 73  uration using [s
10c60 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
10c70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c  ..**.** The appl
10c80 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e  ication should n
10c90 65 76 65 72 20 69 6e 76 6f 6b 65 20 65 69 74 68  ever invoke eith
10ca0 65 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  er sqlite3_os_in
10cb0 69 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74  it().** or sqlit
10cc0 65 33 5f 6f 73 5f 65 6e 64 28 29 20 64 69 72 65  e3_os_end() dire
10cd0 63 74 6c 79 2e 20 20 54 68 65 20 61 70 70 6c 69  ctly.  The appli
10ce0 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e  cation should on
10cf0 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c  ly invoke.** sql
10d00 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
10d10 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 73 68  ) and sqlite3_sh
10d20 75 74 64 6f 77 6e 28 29 2e 20 20 54 68 65 20 73  utdown().  The s
10d30 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
10d40 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73  .** interface is
10d50 20 63 61 6c 6c 65 64 20 61 75 74 6f 6d 61 74 69   called automati
10d60 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33  cally by sqlite3
10d70 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e  _initialize() an
10d80 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f  d.** sqlite3_os_
10d90 65 6e 64 28 29 20 69 73 20 63 61 6c 6c 65 64 20  end() is called 
10da0 62 79 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  by sqlite3_shutd
10db0 6f 77 6e 28 29 2e 20 20 41 70 70 72 6f 70 72 69  own().  Appropri
10dc0 61 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  ate.** implement
10dd0 61 74 69 6f 6e 73 20 66 6f 72 20 73 71 6c 69 74  ations for sqlit
10de0 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64  e3_os_init() and
10df0 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
10e00 29 0a 2a 2a 20 61 72 65 20 62 75 69 6c 74 20 69  ).** are built i
10e10 6e 74 6f 20 53 51 4c 69 74 65 20 77 68 65 6e 20  nto SQLite when 
10e20 69 74 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 66  it is compiled f
10e30 6f 72 20 55 6e 69 78 2c 20 57 69 6e 64 6f 77 73  or Unix, Windows
10e40 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a 2a 20 57 68  , or OS/2..** Wh
10e50 65 6e 20 5b 63 75 73 74 6f 6d 20 62 75 69 6c 64  en [custom build
10e60 73 20 7c 20 62 75 69 6c 74 20 66 6f 72 20 6f 74  s | built for ot
10e70 68 65 72 20 70 6c 61 74 66 6f 72 6d 73 5d 0a 2a  her platforms].*
10e80 2a 20 28 75 73 69 6e 67 20 74 68 65 20 5b 53 51  * (using the [SQ
10e90 4c 49 54 45 5f 4f 53 5f 4f 54 48 45 52 3d 31 5d  LITE_OS_OTHER=1]
10ea0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a   compile-time.**
10eb0 20 6f 70 74 69 6f 6e 29 20 74 68 65 20 61 70 70   option) the app
10ec0 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 73 75  lication must su
10ed0 70 70 6c 79 20 61 20 73 75 69 74 61 62 6c 65 20  pply a suitable 
10ee0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 66  implementation f
10ef0 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73  or.** sqlite3_os
10f00 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69  _init() and sqli
10f10 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 20 20 41  te3_os_end().  A
10f20 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75  n application-su
10f30 70 70 6c 69 65 64 0a 2a 2a 20 69 6d 70 6c 65 6d  pplied.** implem
10f40 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69  entation of sqli
10f50 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 6f 72  te3_os_init() or
10f60 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
10f70 29 0a 2a 2a 20 6d 75 73 74 20 72 65 74 75 72 6e  ).** must return
10f80 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20   [SQLITE_OK] on 
10f90 73 75 63 63 65 73 73 20 61 6e 64 20 73 6f 6d 65  success and some
10fa0 20 6f 74 68 65 72 20 5b 65 72 72 6f 72 20 63 6f   other [error co
10fb0 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66 61 69 6c  de] upon.** fail
10fc0 75 72 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ure..*/.SQLITE_A
10fd0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 69  PI int sqlite3_i
10fe0 6e 69 74 69 61 6c 69 7a 65 28 76 6f 69 64 29 3b  nitialize(void);
10ff0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
11000 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
11010 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41  (void);.SQLITE_A
11020 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  PI int sqlite3_o
11030 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b 0a 53 51  s_init(void);.SQ
11040 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
11050 69 74 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69 64  ite3_os_end(void
11060 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
11070 45 46 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67 20  EF: Configuring 
11080 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61  The SQLite Libra
11090 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  ry.**.** The sql
110a0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e  ite3_config() in
110b0 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20  terface is used 
110c0 74 6f 20 6d 61 6b 65 20 67 6c 6f 62 61 6c 20 63  to make global c
110d0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20  onfiguration.** 
110e0 63 68 61 6e 67 65 73 20 74 6f 20 53 51 4c 69 74  changes to SQLit
110f0 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 74 75  e in order to tu
11100 6e 65 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65  ne SQLite to the
11110 20 73 70 65 63 69 66 69 63 20 6e 65 65 64 73 20   specific needs 
11120 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  of.** the applic
11130 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 66 61  ation.  The defa
11140 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ult configuratio
11150 6e 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  n is recommended
11160 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 70 70   for most.** app
11170 6c 69 63 61 74 69 6f 6e 73 20 61 6e 64 20 73 6f  lications and so
11180 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73   this routine is
11190 20 75 73 75 61 6c 6c 79 20 6e 6f 74 20 6e 65 63   usually not nec
111a0 65 73 73 61 72 79 2e 20 20 49 74 20 69 73 0a 2a  essary.  It is.*
111b0 2a 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73 75  * provided to su
111c0 70 70 6f 72 74 20 72 61 72 65 20 61 70 70 6c 69  pport rare appli
111d0 63 61 74 69 6f 6e 73 20 77 69 74 68 20 75 6e 75  cations with unu
111e0 73 75 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a  sual needs..**.*
111f0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  * The sqlite3_co
11200 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65  nfig() interface
11210 20 69 73 20 6e 6f 74 20 74 68 72 65 61 64 73 61   is not threadsa
11220 66 65 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61  fe.  The applica
11230 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 73  tion.** must ins
11240 75 72 65 20 74 68 61 74 20 6e 6f 20 6f 74 68 65  ure that no othe
11250 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  r SQLite interfa
11260 63 65 73 20 61 72 65 20 69 6e 76 6f 6b 65 64 20  ces are invoked 
11270 62 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68 72 65  by other.** thre
11280 61 64 73 20 77 68 69 6c 65 20 73 71 6c 69 74 65  ads while sqlite
11290 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 72 75  3_config() is ru
112a0 6e 6e 69 6e 67 2e 20 20 46 75 72 74 68 65 72 6d  nning.  Furtherm
112b0 6f 72 65 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e  ore, sqlite3_con
112c0 66 69 67 28 29 0a 2a 2a 20 6d 61 79 20 6f 6e 6c  fig().** may onl
112d0 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 72 69  y be invoked pri
112e0 6f 72 20 74 6f 20 6c 69 62 72 61 72 79 20 69 6e  or to library in
112f0 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 75 73 69  itialization usi
11300 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69  ng.** [sqlite3_i
11310 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 6f 72 20  nitialize()] or 
11320 61 66 74 65 72 20 73 68 75 74 64 6f 77 6e 20 62  after shutdown b
11330 79 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64  y [sqlite3_shutd
11340 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49 66 20 73  own()]..** ^If s
11350 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
11360 69 73 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20  is called after 
11370 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c  [sqlite3_initial
11380 69 7a 65 28 29 5d 20 61 6e 64 20 62 65 66 6f 72  ize()] and befor
11390 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68  e.** [sqlite3_sh
113a0 75 74 64 6f 77 6e 28 29 5d 20 74 68 65 6e 20 69  utdown()] then i
113b0 74 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 53 51  t will return SQ
113c0 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a 20  LITE_MISUSE..** 
113d0 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c 20 74  Note, however, t
113e0 68 61 74 20 5e 73 71 6c 69 74 65 33 5f 63 6f 6e  hat ^sqlite3_con
113f0 66 69 67 28 29 20 63 61 6e 20 62 65 20 63 61 6c  fig() can be cal
11400 6c 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74  led as part of t
11410 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  he.** implementa
11420 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c 69  tion of an appli
11430 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 5b  cation-defined [
11440 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
11450 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  )]..**.** The fi
11460 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
11470 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
11480 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a   is an integer.*
11490 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  * [SQLITE_CONFIG
114a0 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20 7c 20  _SINGLETHREAD | 
114b0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
114c0 74 69 6f 6e 5d 20 74 68 61 74 20 64 65 74 65 72  tion] that deter
114d0 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20 70 72  mines.** what pr
114e0 6f 70 65 72 74 79 20 6f 66 20 53 51 4c 69 74 65  operty of SQLite
114f0 20 69 73 20 74 6f 20 62 65 20 63 6f 6e 66 69 67   is to be config
11500 75 72 65 64 2e 20 20 53 75 62 73 65 71 75 65 6e  ured.  Subsequen
11510 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 76  t arguments.** v
11520 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  ary depending on
11530 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e   the [SQLITE_CON
11540 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
11550 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e   | configuration
11560 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74   option].** in t
11570 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
11580 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 61  t..**.** ^When a
11590 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
115a0 70 74 69 6f 6e 20 69 73 20 73 65 74 2c 20 73 71  ption is set, sq
115b0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 72  lite3_config() r
115c0 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
115d0 4b 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6f  K]..** ^If the o
115e0 70 74 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e  ption is unknown
115f0 20 6f 72 20 53 51 4c 69 74 65 20 69 73 20 75 6e   or SQLite is un
11600 61 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20  able to set the 
11610 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74  option.** then t
11620 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75  his routine retu
11630 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b  rns a non-zero [
11640 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a  error code]..*/.
11650 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
11660 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 69 6e  qlite3_config(in
11670 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20  t, ...);../*.** 
11680 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67  CAPI3REF: Config
11690 75 72 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ure database con
116a0 6e 65 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54  nections.**.** T
116b0 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  he sqlite3_db_co
116c0 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65  nfig() interface
116d0 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65   is used to make
116e0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a   configuration.*
116f0 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 61 20 5b  * changes to a [
11700 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
11710 69 6f 6e 5d 2e 20 20 54 68 65 20 69 6e 74 65 72  ion].  The inter
11720 66 61 63 65 20 69 73 20 73 69 6d 69 6c 61 72 20  face is similar 
11730 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  to.** [sqlite3_c
11740 6f 6e 66 69 67 28 29 5d 20 65 78 63 65 70 74 20  onfig()] except 
11750 74 68 61 74 20 74 68 65 20 63 68 61 6e 67 65 73  that the changes
11760 20 61 70 70 6c 79 20 74 6f 20 61 20 73 69 6e 67   apply to a sing
11770 6c 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  le.** [database 
11780 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 70 65  connection] (spe
11790 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 66 69  cified in the fi
117a0 72 73 74 20 61 72 67 75 6d 65 6e 74 29 2e 0a 2a  rst argument)..*
117b0 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  *.** The second 
117c0 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
117d0 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 44 2c  te3_db_config(D,
117e0 56 2c 2e 2e 2e 29 20 20 69 73 20 74 68 65 0a 2a  V,...)  is the.*
117f0 2a 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  * [SQLITE_DBCONF
11800 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 7c 20 63  IG_LOOKASIDE | c
11810 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72  onfiguration ver
11820 62 5d 20 2d 20 61 6e 20 69 6e 74 65 67 65 72 20  b] - an integer 
11830 63 6f 64 65 20 0a 2a 2a 20 74 68 61 74 20 69 6e  code .** that in
11840 64 69 63 61 74 65 73 20 77 68 61 74 20 61 73 70  dicates what asp
11850 65 63 74 20 6f 66 20 74 68 65 20 5b 64 61 74 61  ect of the [data
11860 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
11870 20 69 73 20 62 65 69 6e 67 20 63 6f 6e 66 69 67   is being config
11880 75 72 65 64 2e 0a 2a 2a 20 53 75 62 73 65 71 75  ured..** Subsequ
11890 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 20 76 61  ent arguments va
118a0 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  ry depending on 
118b0 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  the configuratio
118c0 6e 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e 43  n verb..**.** ^C
118d0 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
118e0 64 62 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75  db_config() retu
118f0 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66 20  rn SQLITE_OK if 
11900 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 74  and only if.** t
11910 68 65 20 63 61 6c 6c 20 69 73 20 63 6f 6e 73 69  he call is consi
11920 64 65 72 65 64 20 73 75 63 63 65 73 73 66 75 6c  dered successful
11930 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
11940 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 62 5f 63  int sqlite3_db_c
11950 6f 6e 66 69 67 28 73 71 6c 69 74 65 33 2a 2c 20  onfig(sqlite3*, 
11960 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f  int op, ...);../
11970 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
11980 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e  emory Allocation
11990 20 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a 20   Routines.**.** 
119a0 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  An instance of t
119b0 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e  his object defin
119c0 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
119d0 20 62 65 74 77 65 65 6e 20 53 51 4c 69 74 65 0a   between SQLite.
119e0 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c  ** and low-level
119f0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
11a00 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a  on routines..**.
11a10 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69  ** This object i
11a20 73 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f  s used in only o
11a30 6e 65 20 70 6c 61 63 65 20 69 6e 20 74 68 65 20  ne place in the 
11a40 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
11a50 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74  ..** A pointer t
11a60 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  o an instance of
11a70 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20   this object is 
11a80 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  the argument to.
11a90 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
11aa0 69 67 28 29 5d 20 77 68 65 6e 20 74 68 65 20 63  ig()] when the c
11ab0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
11ac0 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54  ion is.** [SQLIT
11ad0 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d  E_CONFIG_MALLOC]
11ae0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   or [SQLITE_CONF
11af0 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20  IG_GETMALLOC].  
11b00 0a 2a 2a 20 42 79 20 63 72 65 61 74 69 6e 67 20  .** By creating 
11b10 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
11b20 68 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e  his object.** an
11b30 64 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20  d passing it to 
11b40 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d  [sqlite3_config]
11b50 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  ([SQLITE_CONFIG_
11b60 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72 69  MALLOC]).** duri
11b70 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ng configuration
11b80 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  , an application
11b90 20 63 61 6e 20 73 70 65 63 69 66 79 20 61 6e 20   can specify an 
11ba0 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d  alternative.** m
11bb0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
11bc0 20 73 75 62 73 79 73 74 65 6d 20 66 6f 72 20 53   subsystem for S
11bd0 51 4c 69 74 65 20 74 6f 20 75 73 65 20 66 6f 72  QLite to use for
11be0 20 61 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a 20 64   all of its.** d
11bf0 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65  ynamic memory ne
11c00 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  eds..**.** Note 
11c10 74 68 61 74 20 53 51 4c 69 74 65 20 63 6f 6d 65  that SQLite come
11c20 73 20 77 69 74 68 20 73 65 76 65 72 61 6c 20 5b  s with several [
11c30 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20  built-in memory 
11c40 61 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20 74  allocators].** t
11c50 68 61 74 20 61 72 65 20 70 65 72 66 65 63 74 6c  hat are perfectl
11c60 79 20 61 64 65 71 75 61 74 65 20 66 6f 72 20 74  y adequate for t
11c70 68 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67 20  he overwhelming 
11c80 6d 61 6a 6f 72 69 74 79 20 6f 66 20 61 70 70 6c  majority of appl
11c90 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20  ications.** and 
11ca0 74 68 61 74 20 74 68 69 73 20 6f 62 6a 65 63 74  that this object
11cb0 20 69 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20   is only useful 
11cc0 74 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72 69  to a tiny minori
11cd0 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f  ty of applicatio
11ce0 6e 73 0a 2a 2a 20 77 69 74 68 20 73 70 65 63 69  ns.** with speci
11cf0 61 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61 6c  alized memory al
11d00 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 69 72 65  location require
11d10 6d 65 6e 74 73 2e 20 20 54 68 69 73 20 6f 62 6a  ments.  This obj
11d20 65 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 75  ect is.** also u
11d30 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69  sed during testi
11d40 6e 67 20 6f 66 20 53 51 4c 69 74 65 20 69 6e 20  ng of SQLite in 
11d50 6f 72 64 65 72 20 74 6f 20 73 70 65 63 69 66 79  order to specify
11d60 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a   an alternative.
11d70 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ** memory alloca
11d80 74 6f 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74  tor that simulat
11d90 65 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f 66  es memory out-of
11da0 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f  -memory conditio
11db0 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 74  ns in.** order t
11dc0 6f 20 76 65 72 69 66 79 20 74 68 61 74 20 53 51  o verify that SQ
11dd0 4c 69 74 65 20 72 65 63 6f 76 65 72 73 20 67 72  Lite recovers gr
11de0 61 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73 75  acefully from su
11df0 63 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 73  ch.** conditions
11e00 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 6c  ..**.** The xMal
11e10 6c 6f 63 20 61 6e 64 20 78 46 72 65 65 20 6d 65  loc and xFree me
11e20 74 68 6f 64 73 20 6d 75 73 74 20 77 6f 72 6b 20  thods must work 
11e30 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c  like the.** mall
11e40 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20  oc() and free() 
11e50 66 75 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74  functions from t
11e60 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  he standard C li
11e70 62 72 61 72 79 2e 0a 2a 2a 20 54 68 65 20 78 52  brary..** The xR
11e80 65 61 6c 6c 6f 63 20 6d 65 74 68 6f 64 20 6d 75  ealloc method mu
11e90 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20 72 65 61  st work like rea
11ea0 6c 6c 6f 63 28 29 20 66 72 6f 6d 20 74 68 65 20  lloc() from the 
11eb0 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61  standard C libra
11ec0 72 79 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 65  ry.** with the e
11ed0 78 63 65 70 74 69 6f 6e 20 74 68 61 74 20 69 66  xception that if
11ee0 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
11ef0 6d 65 6e 74 20 74 6f 20 78 52 65 61 6c 6c 6f 63  ment to xRealloc
11f00 20 69 73 20 7a 65 72 6f 2c 0a 2a 2a 20 78 52 65   is zero,.** xRe
11f10 61 6c 6c 6f 63 20 6d 75 73 74 20 62 65 20 61 20  alloc must be a 
11f20 6e 6f 2d 6f 70 20 2d 20 69 74 20 6d 75 73 74 20  no-op - it must 
11f30 6e 6f 74 20 70 65 72 66 6f 72 6d 20 61 6e 79 20  not perform any 
11f40 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 0a 2a 2a  allocation or.**
11f50 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 2e 20 20   deallocation.  
11f60 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65  ^SQLite guarante
11f70 65 73 20 74 68 61 74 20 74 68 65 20 73 65 63 6f  es that the seco
11f80 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a  nd argument to.*
11f90 2a 20 78 52 65 61 6c 6c 6f 63 20 69 73 20 61 6c  * xRealloc is al
11fa0 77 61 79 73 20 61 20 76 61 6c 75 65 20 72 65 74  ways a value ret
11fb0 75 72 6e 65 64 20 62 79 20 61 20 70 72 69 6f 72  urned by a prior
11fc0 20 63 61 6c 6c 20 74 6f 20 78 52 6f 75 6e 64 75   call to xRoundu
11fd0 70 2e 0a 2a 2a 20 41 6e 64 20 73 6f 20 69 6e 20  p..** And so in 
11fe0 63 61 73 65 73 20 77 68 65 72 65 20 78 52 6f 75  cases where xRou
11ff0 6e 64 75 70 20 61 6c 77 61 79 73 20 72 65 74 75  ndup always retu
12000 72 6e 73 20 61 20 70 6f 73 69 74 69 76 65 20 6e  rns a positive n
12010 75 6d 62 65 72 2c 0a 2a 2a 20 78 52 65 61 6c 6c  umber,.** xReall
12020 6f 63 20 63 61 6e 20 70 65 72 66 6f 72 6d 20 65  oc can perform e
12030 78 61 63 74 6c 79 20 61 73 20 74 68 65 20 73 74  xactly as the st
12040 61 6e 64 61 72 64 20 6c 69 62 72 61 72 79 20 72  andard library r
12050 65 61 6c 6c 6f 63 28 29 20 61 6e 64 0a 2a 2a 20  ealloc() and.** 
12060 73 74 69 6c 6c 20 62 65 20 69 6e 20 63 6f 6d 70  still be in comp
12070 6c 69 61 6e 63 65 20 77 69 74 68 20 74 68 69 73  liance with this
12080 20 73 70 65 63 69 66 69 63 61 74 69 6f 6e 2e 0a   specification..
12090 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75  **.** xSize shou
120a0 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 61 6c  ld return the al
120b0 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66 20  located size of 
120c0 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
120d0 69 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c  ion.** previousl
120e0 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
120f0 78 4d 61 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c  xMalloc or xReal
12100 6c 6f 63 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61  loc.  The alloca
12110 74 65 64 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61  ted size.** is a
12120 6c 77 61 79 73 20 61 74 20 6c 65 61 73 74 20 61  lways at least a
12130 73 20 62 69 67 20 61 73 20 74 68 65 20 72 65 71  s big as the req
12140 75 65 73 74 65 64 20 73 69 7a 65 20 62 75 74 20  uested size but 
12150 6d 61 79 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a  may be larger..*
12160 2a 0a 2a 2a 20 54 68 65 20 78 52 6f 75 6e 64 75  *.** The xRoundu
12170 70 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  p method returns
12180 20 77 68 61 74 20 77 6f 75 6c 64 20 62 65 20 74   what would be t
12190 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a  he allocated siz
121a0 65 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79  e of.** a memory
121b0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65   allocation give
121c0 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72  n a particular r
121d0 65 71 75 65 73 74 65 64 20 73 69 7a 65 2e 20 20  equested size.  
121e0 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61  Most memory.** a
121f0 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20  llocators round 
12200 75 70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  up memory alloca
12210 74 69 6f 6e 73 20 61 74 20 6c 65 61 73 74 20 74  tions at least t
12220 6f 20 74 68 65 20 6e 65 78 74 20 6d 75 6c 74 69  o the next multi
12230 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f  ple.** of 8.  So
12240 6d 65 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f  me allocators ro
12250 75 6e 64 20 75 70 20 74 6f 20 61 20 6c 61 72 67  und up to a larg
12260 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74  er multiple or t
12270 6f 20 61 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a  o a power of 2..
12280 2a 2a 20 45 76 65 72 79 20 6d 65 6d 6f 72 79 20  ** Every memory 
12290 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 65  allocation reque
122a0 73 74 20 63 6f 6d 69 6e 67 20 69 6e 20 74 68 72  st coming in thr
122b0 6f 75 67 68 20 5b 73 71 6c 69 74 65 33 5f 6d 61  ough [sqlite3_ma
122c0 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73  lloc()].** or [s
122d0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
122e0 5d 20 66 69 72 73 74 20 63 61 6c 6c 73 20 78 52  ] first calls xR
122f0 6f 75 6e 64 75 70 2e 20 20 49 66 20 78 52 6f 75  oundup.  If xRou
12300 6e 64 75 70 20 72 65 74 75 72 6e 73 20 30 2c 20  ndup returns 0, 
12310 0a 2a 2a 20 74 68 61 74 20 63 61 75 73 65 73 20  .** that causes 
12320 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
12330 67 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  g memory allocat
12340 69 6f 6e 20 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a  ion to fail..**.
12350 2a 2a 20 54 68 65 20 78 49 6e 69 74 20 6d 65 74  ** The xInit met
12360 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65 73 20  hod initializes 
12370 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
12380 61 74 6f 72 2e 20 20 28 46 6f 72 20 65 78 61 6d  ator.  (For exam
12390 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68 74  ple,.** it might
123a0 20 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65   allocate any re
123b0 71 75 69 72 65 20 6d 75 74 65 78 65 73 20 6f 72  quire mutexes or
123c0 20 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74 65   initialize inte
123d0 72 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74 72  rnal data.** str
123e0 75 63 74 75 72 65 73 2e 20 20 54 68 65 20 78 53  uctures.  The xS
123f0 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69  hutdown method i
12400 73 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69 72  s invoked (indir
12410 65 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73 71  ectly) by.** [sq
12420 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
12430 5d 20 61 6e 64 20 73 68 6f 75 6c 64 20 64 65 61  ] and should dea
12440 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 73 6f  llocate any reso
12450 75 72 63 65 73 20 61 63 71 75 69 72 65 64 0a 2a  urces acquired.*
12460 2a 20 62 79 20 78 49 6e 69 74 2e 20 20 54 68 65  * by xInit.  The
12470 20 70 41 70 70 44 61 74 61 20 70 6f 69 6e 74 65   pAppData pointe
12480 72 20 69 73 20 75 73 65 64 20 61 73 20 74 68 65  r is used as the
12490 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20   only parameter 
124a0 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64 20  to.** xInit and 
124b0 78 53 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a  xShutdown..**.**
124c0 20 53 51 4c 69 74 65 20 68 6f 6c 64 73 20 74 68   SQLite holds th
124d0 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  e [SQLITE_MUTEX_
124e0 53 54 41 54 49 43 5f 4d 41 53 54 45 52 5d 20 6d  STATIC_MASTER] m
124f0 75 74 65 78 20 77 68 65 6e 20 69 74 20 69 6e 76  utex when it inv
12500 6f 6b 65 73 0a 2a 2a 20 74 68 65 20 78 49 6e 69  okes.** the xIni
12510 74 20 6d 65 74 68 6f 64 2c 20 73 6f 20 74 68 65  t method, so the
12520 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 6e 65   xInit method ne
12530 65 64 20 6e 6f 74 20 62 65 20 74 68 72 65 61 64  ed not be thread
12540 73 61 66 65 2e 20 20 54 68 65 0a 2a 2a 20 78 53  safe.  The.** xS
12550 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69  hutdown method i
12560 73 20 6f 6e 6c 79 20 63 61 6c 6c 65 64 20 66 72  s only called fr
12570 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74  om [sqlite3_shut
12580 64 6f 77 6e 28 29 5d 20 73 6f 20 69 74 20 64 6f  down()] so it do
12590 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64 20 74  es.** not need t
125a0 6f 20 62 65 20 74 68 72 65 61 64 73 61 66 65 20  o be threadsafe 
125b0 65 69 74 68 65 72 2e 20 20 46 6f 72 20 61 6c 6c  either.  For all
125c0 20 6f 74 68 65 72 20 6d 65 74 68 6f 64 73 2c 20   other methods, 
125d0 53 51 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64 73 20  SQLite.** holds 
125e0 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45  the [SQLITE_MUTE
125f0 58 5f 53 54 41 54 49 43 5f 4d 45 4d 5d 20 6d 75  X_STATIC_MEM] mu
12600 74 65 78 20 61 73 20 6c 6f 6e 67 20 61 73 20 74  tex as long as t
12610 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f  he.** [SQLITE_CO
12620 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20  NFIG_MEMSTATUS] 
12630 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
12640 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f  tion is turned o
12650 6e 20 28 77 68 69 63 68 0a 2a 2a 20 69 74 20 69  n (which.** it i
12660 73 20 62 79 20 64 65 66 61 75 6c 74 29 20 61 6e  s by default) an
12670 64 20 73 6f 20 74 68 65 20 6d 65 74 68 6f 64 73  d so the methods
12680 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c   are automatical
12690 6c 79 20 73 65 72 69 61 6c 69 7a 65 64 2e 0a 2a  ly serialized..*
126a0 2a 20 48 6f 77 65 76 65 72 2c 20 69 66 20 5b 53  * However, if [S
126b0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
126c0 53 54 41 54 55 53 5d 20 69 73 20 64 69 73 61 62  STATUS] is disab
126d0 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 20 6f 74  led, then the ot
126e0 68 65 72 0a 2a 2a 20 6d 65 74 68 6f 64 73 20 6d  her.** methods m
126f0 75 73 74 20 62 65 20 74 68 72 65 61 64 73 61 66  ust be threadsaf
12700 65 20 6f 72 20 65 6c 73 65 20 6d 61 6b 65 20 74  e or else make t
12710 68 65 69 72 20 6f 77 6e 20 61 72 72 61 6e 67 65  heir own arrange
12720 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a 20 73 65 72  ments for.** ser
12730 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  ialization..**.*
12740 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65  * SQLite will ne
12750 76 65 72 20 69 6e 76 6f 6b 65 20 78 49 6e 69 74  ver invoke xInit
12760 28 29 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63  () more than onc
12770 65 20 77 69 74 68 6f 75 74 20 61 6e 20 69 6e 74  e without an int
12780 65 72 76 65 6e 69 6e 67 0a 2a 2a 20 63 61 6c 6c  ervening.** call
12790 20 74 6f 20 78 53 68 75 74 64 6f 77 6e 28 29 2e   to xShutdown().
127a0 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
127b0 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  ct sqlite3_mem_m
127c0 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 6d  ethods sqlite3_m
127d0 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75  em_methods;.stru
127e0 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  ct sqlite3_mem_m
127f0 65 74 68 6f 64 73 20 7b 0a 20 20 76 6f 69 64 20  ethods {.  void 
12800 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e 74 29  *(*xMalloc)(int)
12810 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 65 6d  ;         /* Mem
12820 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
12830 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69  unction */.  voi
12840 64 20 28 2a 78 46 72 65 65 29 28 76 6f 69 64 2a  d (*xFree)(void*
12850 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46  );          /* F
12860 72 65 65 20 61 20 70 72 69 6f 72 20 61 6c 6c 6f  ree a prior allo
12870 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64  cation */.  void
12880 20 2a 28 2a 78 52 65 61 6c 6c 6f 63 29 28 76 6f   *(*xRealloc)(vo
12890 69 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20 52 65  id*,int);  /* Re
128a0 73 69 7a 65 20 61 6e 20 61 6c 6c 6f 63 61 74 69  size an allocati
128b0 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53  on */.  int (*xS
128c0 69 7a 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20  ize)(void*);    
128d0 20 20 20 20 20 20 20 2f 2a 20 52 65 74 75 72 6e         /* Return
128e0 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61 6e 20   the size of an 
128f0 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20  allocation */.  
12900 69 6e 74 20 28 2a 78 52 6f 75 6e 64 75 70 29 28  int (*xRoundup)(
12910 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 20 2f  int);          /
12920 2a 20 52 6f 75 6e 64 20 75 70 20 72 65 71 75 65  * Round up reque
12930 73 74 20 73 69 7a 65 20 74 6f 20 61 6c 6c 6f 63  st size to alloc
12940 61 74 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20 20  ation size */.  
12950 69 6e 74 20 28 2a 78 49 6e 69 74 29 28 76 6f 69  int (*xInit)(voi
12960 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f  d*);           /
12970 2a 20 49 6e 69 74 69 61 6c 69 7a 65 20 74 68 65  * Initialize the
12980 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
12990 72 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 53  r */.  void (*xS
129a0 68 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a 29 3b  hutdown)(void*);
129b0 20 20 20 20 20 20 2f 2a 20 44 65 69 6e 69 74 69        /* Deiniti
129c0 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79  alize the memory
129d0 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20   allocator */.  
129e0 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20  void *pAppData; 
129f0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
12a00 2a 20 41 72 67 75 6d 65 6e 74 20 74 6f 20 78 49  * Argument to xI
12a10 6e 69 74 28 29 20 61 6e 64 20 78 53 68 75 74 64  nit() and xShutd
12a20 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a  own() */.};../*.
12a30 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
12a40 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f  figuration Optio
12a50 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  ns.**.** These c
12a60 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65  onstants are the
12a70 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67   available integ
12a80 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  er configuration
12a90 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a   options that.**
12aa0 20 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61   can be passed a
12ab0 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  s the first argu
12ac0 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c  ment to the [sql
12ad0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69  ite3_config()] i
12ae0 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
12af0 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  New configuratio
12b00 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65  n options may be
12b10 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
12b20 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c   releases of SQL
12b30 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67  ite..** Existing
12b40 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
12b50 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20  ptions might be 
12b60 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41  discontinued.  A
12b70 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73  pplications.** s
12b80 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20  hould check the 
12b90 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d  return code from
12ba0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
12bb0 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65  ()] to make sure
12bc0 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c   that.** the cal
12bd0 6c 20 77 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b  l worked.  The [
12be0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
12bf0 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c  ] interface will
12c00 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e   return a.** non
12c10 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64  -zero [error cod
12c20 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69  e] if a disconti
12c30 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72  nued or unsuppor
12c40 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ted configuratio
12c50 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69  n option.** is i
12c60 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64  nvoked..**.** <d
12c70 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  l>.** <dt>SQLITE
12c80 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
12c90 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  READ</dt>.** <dd
12ca0 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72  >There are no ar
12cb0 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20  guments to this 
12cc0 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f  option.  ^This o
12cd0 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a  ption sets the.*
12ce0 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  * [threading mod
12cf0 65 5d 20 74 6f 20 53 69 6e 67 6c 65 2d 74 68 72  e] to Single-thr
12d00 65 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77  ead.  In other w
12d10 6f 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65  ords, it disable
12d20 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 69 6e  s.** all mutexin
12d30 67 20 61 6e 64 20 70 75 74 73 20 53 51 4c 69 74  g and puts SQLit
12d40 65 20 69 6e 74 6f 20 61 20 6d 6f 64 65 20 77 68  e into a mode wh
12d50 65 72 65 20 69 74 20 63 61 6e 20 6f 6e 6c 79 20  ere it can only 
12d60 62 65 20 75 73 65 64 0a 2a 2a 20 62 79 20 61 20  be used.** by a 
12d70 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20  single thread.  
12d80 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63   ^If SQLite is c
12d90 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
12da0 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
12db0 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f  ADSAFE | SQLITE_
12dc0 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f  THREADSAFE=0] co
12dd0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
12de0 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20  n then.** it is 
12df0 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20  not possible to 
12e00 63 68 61 6e 67 65 20 74 68 65 20 5b 74 68 72 65  change the [thre
12e10 61 64 69 6e 67 20 6d 6f 64 65 5d 20 66 72 6f 6d  ading mode] from
12e20 20 69 74 73 20 64 65 66 61 75 6c 74 0a 2a 2a 20   its default.** 
12e30 76 61 6c 75 65 20 6f 66 20 53 69 6e 67 6c 65 2d  value of Single-
12e40 74 68 72 65 61 64 20 61 6e 64 20 73 6f 20 5b 73  thread and so [s
12e50 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
12e60 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 0a 2a 2a   will return .**
12e70 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
12e80 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74  if called with t
12e90 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
12ea0 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 0a 2a 2a  _SINGLETHREAD.**
12eb0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
12ec0 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ption.</dd>.**.*
12ed0 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
12ee0 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 3c  FIG_MULTITHREAD<
12ef0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72  /dt>.** <dd>Ther
12f00 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e  e are no argumen
12f10 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f  ts to this optio
12f20 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  n.  ^This option
12f30 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68   sets the.** [th
12f40 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f  reading mode] to
12f50 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 2e 20 20   Multi-thread.  
12f60 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
12f70 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 6d  it disables.** m
12f80 75 74 65 78 69 6e 67 20 6f 6e 20 5b 64 61 74 61  utexing on [data
12f90 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
12fa0 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73   and [prepared s
12fb0 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74  tatement] object
12fc0 73 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  s..** The applic
12fd0 61 74 69 6f 6e 20 69 73 20 72 65 73 70 6f 6e 73  ation is respons
12fe0 69 62 6c 65 20 66 6f 72 20 73 65 72 69 61 6c 69  ible for seriali
12ff0 7a 69 6e 67 20 61 63 63 65 73 73 20 74 6f 0a 2a  zing access to.*
13000 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
13010 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72  ections] and [pr
13020 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
13030 73 5d 2e 20 20 42 75 74 20 6f 74 68 65 72 20 6d  s].  But other m
13040 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e  utexes.** are en
13050 61 62 6c 65 64 20 73 6f 20 74 68 61 74 20 53 51  abled so that SQ
13060 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 73 61 66  Lite will be saf
13070 65 20 74 6f 20 75 73 65 20 69 6e 20 61 20 6d 75  e to use in a mu
13080 6c 74 69 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20  lti-threaded.** 
13090 65 6e 76 69 72 6f 6e 6d 65 6e 74 20 61 73 20 6c  environment as l
130a0 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20 74 68  ong as no two th
130b0 72 65 61 64 73 20 61 74 74 65 6d 70 74 20 74 6f  reads attempt to
130c0 20 75 73 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a   use the same.**
130d0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
130e0 63 74 69 6f 6e 5d 20 61 74 20 74 68 65 20 73 61  ction] at the sa
130f0 6d 65 20 74 69 6d 65 2e 20 20 5e 49 66 20 53 51  me time.  ^If SQ
13100 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
13110 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51   with.** the [SQ
13120 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
13130 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  | SQLITE_THREADS
13140 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74  AFE=0] compile-t
13150 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a  ime option then.
13160 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73  ** it is not pos
13170 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65  sible to set the
13180 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74   Multi-thread [t
13190 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61  hreading mode] a
131a0 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  nd.** [sqlite3_c
131b0 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65  onfig()] will re
131c0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52  turn [SQLITE_ERR
131d0 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69  OR] if called wi
131e0 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45  th the.** SQLITE
131f0 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
13200 45 41 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  EAD configuratio
13210 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a  n option.</dd>.*
13220 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
13230 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45  CONFIG_SERIALIZE
13240 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  D</dt>.** <dd>Th
13250 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d  ere are no argum
13260 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74  ents to this opt
13270 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69  ion.  ^This opti
13280 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b  on sets the.** [
13290 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
132a0 74 6f 20 53 65 72 69 61 6c 69 7a 65 64 2e 20 49  to Serialized. I
132b0 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74  n other words, t
132c0 68 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c  his option enabl
132d0 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65  es.** all mutexe
132e0 73 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 65 20  s including the 
132f0 72 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74  recursive.** mut
13300 65 78 65 73 20 6f 6e 20 5b 64 61 74 61 62 61 73  exes on [databas
13310 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e  e connection] an
13320 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
13330 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a  ement] objects..
13340 2a 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64 65 20  ** In this mode 
13350 28 77 68 69 63 68 20 69 73 20 74 68 65 20 64 65  (which is the de
13360 66 61 75 6c 74 20 77 68 65 6e 20 53 51 4c 69 74  fault when SQLit
13370 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
13380 74 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48  th.** [SQLITE_TH
13390 52 45 41 44 53 41 46 45 3d 31 5d 29 20 74 68 65  READSAFE=1]) the
133a0 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20   SQLite library 
133b0 77 69 6c 6c 20 69 74 73 65 6c 66 20 73 65 72 69  will itself seri
133c0 61 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20  alize access.** 
133d0 74 6f 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  to [database con
133e0 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70  nections] and [p
133f0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
13400 74 73 5d 20 73 6f 20 74 68 61 74 20 74 68 65 0a  ts] so that the.
13410 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69  ** application i
13420 73 20 66 72 65 65 20 74 6f 20 75 73 65 20 74 68  s free to use th
13430 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65  e same [database
13440 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20   connection] or 
13450 74 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65  the.** same [pre
13460 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
13470 20 69 6e 20 64 69 66 66 65 72 65 6e 74 20 74 68   in different th
13480 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d  reads at the sam
13490 65 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53  e time..** ^If S
134a0 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
134b0 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53  d with.** the [S
134c0 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
134d0 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44   | SQLITE_THREAD
134e0 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d  SAFE=0] compile-
134f0 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e  time option then
13500 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f  .** it is not po
13510 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68  ssible to set th
13520 65 20 53 65 72 69 61 6c 69 7a 65 64 20 5b 74 68  e Serialized [th
13530 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e  reading mode] an
13540 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d.** [sqlite3_co
13550 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74  nfig()] will ret
13560 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  urn [SQLITE_ERRO
13570 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74  R] if called wit
13580 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f  h the.** SQLITE_
13590 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45  CONFIG_SERIALIZE
135a0 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  D configuration 
135b0 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a  option.</dd>.**.
135c0 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
135d0 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e  NFIG_MALLOC</dt>
135e0 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20  .** <dd> ^(This 
135f0 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
13600 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
13610 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65  hich is a pointe
13620 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61  r to an.** insta
13630 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  nce of the [sqli
13640 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d  te3_mem_methods]
13650 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65   structure.  The
13660 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66   argument specif
13670 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69  ies.** alternati
13680 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d  ve low-level mem
13690 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
136a0 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73  outines to be us
136b0 65 64 20 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  ed in place of.*
136c0 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  * the memory all
136d0 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  ocation routines
136e0 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69   built into SQLi
136f0 74 65 2e 29 5e 20 5e 53 51 4c 69 74 65 20 6d 61  te.)^ ^SQLite ma
13700 6b 65 73 0a 2a 2a 20 69 74 73 20 6f 77 6e 20 70  kes.** its own p
13710 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74  rivate copy of t
13720 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  he content of th
13730 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  e [sqlite3_mem_m
13740 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
13750 65 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 65 20  e.** before the 
13760 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
13770 29 5d 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e  )] call returns.
13780 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
13790 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
137a0 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20  TMALLOC</dt>.** 
137b0 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69  <dd> ^(This opti
137c0 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
137d0 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
137e0 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
137f0 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20   an.** instance 
13800 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
13810 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  mem_methods] str
13820 75 63 74 75 72 65 2e 20 20 54 68 65 20 5b 73 71  ucture.  The [sq
13830 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
13840 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20  s].** structure 
13850 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74  is filled with t
13860 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66  he currently def
13870 69 6e 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ined memory allo
13880 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e  cation routines.
13890 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f  )^.** This optio
138a0 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  n can be used to
138b0 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65   overload the de
138c0 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c  fault memory all
138d0 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69  ocation.** routi
138e0 6e 65 73 20 77 69 74 68 20 61 20 77 72 61 70 70  nes with a wrapp
138f0 65 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 69  er that simulati
13900 6f 6e 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ons memory alloc
13910 61 74 69 6f 6e 20 66 61 69 6c 75 72 65 20 6f 72  ation failure or
13920 0a 2a 2a 20 74 72 61 63 6b 73 20 6d 65 6d 6f 72  .** tracks memor
13930 79 20 75 73 61 67 65 2c 20 66 6f 72 20 65 78 61  y usage, for exa
13940 6d 70 6c 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  mple. </dd>.**.*
13950 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
13960 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 3c 2f 64  FIG_MEMSTATUS</d
13970 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
13980 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 73 69   option takes si
13990 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66  ngle argument of
139a0 20 74 79 70 65 20 69 6e 74 2c 20 69 6e 74 65 72   type int, inter
139b0 70 72 65 74 65 64 20 61 73 20 61 20 0a 2a 2a 20  preted as a .** 
139c0 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 68 20 65  boolean, which e
139d0 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c  nables or disabl
139e0 65 73 20 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f  es the collectio
139f0 6e 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  n of memory allo
13a00 63 61 74 69 6f 6e 20 0a 2a 2a 20 73 74 61 74 69  cation .** stati
13a10 73 74 69 63 73 2e 20 5e 28 57 68 65 6e 20 6d 65  stics. ^(When me
13a20 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
13a30 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20 64  statistics are d
13a40 69 73 61 62 6c 65 64 2c 20 74 68 65 20 0a 2a 2a  isabled, the .**
13a50 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 69 74   following SQLit
13a60 65 20 69 6e 74 65 72 66 61 63 65 73 20 62 65 63  e interfaces bec
13a70 6f 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f  ome non-operatio
13a80 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a  nal:.**   <ul>.*
13a90 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65  *   <li> [sqlite
13aa0 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
13ab0 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69  .**   <li> [sqli
13ac0 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
13ad0 61 74 65 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69  ater()].**   <li
13ae0 3e 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f  > [sqlite3_soft_
13af0 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 5d 0a  heap_limit64()].
13b00 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74  **   <li> [sqlit
13b10 65 33 5f 73 74 61 74 75 73 28 29 5d 0a 2a 2a 20  e3_status()].** 
13b20 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65    </ul>)^.** ^Me
13b30 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
13b40 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20 65  statistics are e
13b50 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  nabled by defaul
13b60 74 20 75 6e 6c 65 73 73 20 53 51 4c 69 74 65 20  t unless SQLite 
13b70 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77  is.** compiled w
13b80 69 74 68 20 5b 53 51 4c 49 54 45 5f 44 45 46 41  ith [SQLITE_DEFA
13b90 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53 5d 3d 30  ULT_MEMSTATUS]=0
13ba0 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 6d   in which case m
13bb0 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74  emory.** allocat
13bc0 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61  ion statistics a
13bd0 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 64  re disabled by d
13be0 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e  efault..** </dd>
13bf0 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
13c00 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48  E_CONFIG_SCRATCH
13c10 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
13c20 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69  his option speci
13c30 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65  fies a static me
13c40 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68 61 74  mory buffer that
13c50 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20   SQLite can use 
13c60 66 6f 72 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d  for.** scratch m
13c70 65 6d 6f 72 79 2e 20 20 54 68 65 72 65 20 61 72  emory.  There ar
13c80 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74  e three argument
13c90 73 3a 20 20 41 20 70 6f 69 6e 74 65 72 20 61 6e  s:  A pointer an
13ca0 20 38 2d 62 79 74 65 0a 2a 2a 20 61 6c 69 67 6e   8-byte.** align
13cb0 65 64 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  ed memory buffer
13cc0 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20   from which the 
13cd0 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69  scratch allocati
13ce0 6f 6e 73 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 64  ons will be.** d
13cf0 72 61 77 6e 2c 20 74 68 65 20 73 69 7a 65 20 6f  rawn, the size o
13d00 66 20 65 61 63 68 20 73 63 72 61 74 63 68 20 61  f each scratch a
13d10 6c 6c 6f 63 61 74 69 6f 6e 20 28 73 7a 29 2c 0a  llocation (sz),.
13d20 2a 2a 20 61 6e 64 20 74 68 65 20 6d 61 78 69 6d  ** and the maxim
13d30 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 73 63 72  um number of scr
13d40 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  atch allocations
13d50 20 28 4e 29 2e 20 20 54 68 65 20 73 7a 0a 2a 2a   (N).  The sz.**
13d60 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62   argument must b
13d70 65 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20  e a multiple of 
13d80 31 36 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  16..** The first
13d90 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62   argument must b
13da0 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  e a pointer to a
13db0 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64  n 8-byte aligned
13dc0 20 62 75 66 66 65 72 0a 2a 2a 20 6f 66 20 61 74   buffer.** of at
13dd0 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65   least sz*N byte
13de0 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20  s of memory..** 
13df0 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65  ^SQLite will use
13e00 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 20 74 77   no more than tw
13e10 6f 20 73 63 72 61 74 63 68 20 62 75 66 66 65 72  o scratch buffer
13e20 73 20 70 65 72 20 74 68 72 65 61 64 2e 20 20 53  s per thread.  S
13e30 6f 0a 2a 2a 20 4e 20 73 68 6f 75 6c 64 20 62 65  o.** N should be
13e40 20 73 65 74 20 74 6f 20 74 77 69 63 65 20 74 68   set to twice th
13e50 65 20 65 78 70 65 63 74 65 64 20 6d 61 78 69 6d  e expected maxim
13e60 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 68 72  um number of thr
13e70 65 61 64 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  eads..** ^SQLite
13e80 20 77 69 6c 6c 20 6e 65 76 65 72 20 72 65 71 75   will never requ
13e90 69 72 65 20 61 20 73 63 72 61 74 63 68 20 62 75  ire a scratch bu
13ea0 66 66 65 72 20 74 68 61 74 20 69 73 20 6d 6f 72  ffer that is mor
13eb0 65 20 74 68 61 6e 20 36 0a 2a 2a 20 74 69 6d 65  e than 6.** time
13ec0 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 70  s the database p
13ed0 61 67 65 20 73 69 7a 65 2e 20 5e 49 66 20 53 51  age size. ^If SQ
13ee0 4c 69 74 65 20 6e 65 65 64 73 20 6e 65 65 64 73  Lite needs needs
13ef0 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 73   additional.** s
13f00 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 62 65  cratch memory be
13f10 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f  yond what is pro
13f20 76 69 64 65 64 20 62 79 20 74 68 69 73 20 63 6f  vided by this co
13f30 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
13f40 6f 6e 2c 20 74 68 65 6e 20 0a 2a 2a 20 5b 73 71  on, then .** [sq
13f50 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
13f60 77 69 6c 6c 20 62 65 20 75 73 65 64 20 74 6f 20  will be used to 
13f70 6f 62 74 61 69 6e 20 74 68 65 20 6d 65 6d 6f 72  obtain the memor
13f80 79 20 6e 65 65 64 65 64 2e 3c 2f 64 64 3e 0a 2a  y needed.</dd>.*
13f90 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
13fa0 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
13fb0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
13fc0 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69  his option speci
13fd0 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65  fies a static me
13fe0 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68 61 74  mory buffer that
13ff0 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20   SQLite can use 
14000 66 6f 72 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  for.** the datab
14010 61 73 65 20 70 61 67 65 20 63 61 63 68 65 20 77  ase page cache w
14020 69 74 68 20 74 68 65 20 64 65 66 61 75 6c 74 20  ith the default 
14030 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65  page cache imple
14040 6d 65 6e 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20 54  menation.  .** T
14050 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  his configuratio
14060 6e 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20  n should not be 
14070 75 73 65 64 20 69 66 20 61 6e 20 61 70 70 6c 69  used if an appli
14080 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 20 70 61  cation-define pa
14090 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c  ge.** cache impl
140a0 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6c 6f  ementation is lo
140b0 61 64 65 64 20 75 73 69 6e 67 20 74 68 65 20 53  aded using the S
140c0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
140d0 43 48 45 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 54  CHE option..** T
140e0 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61  here are three a
140f0 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73  rguments to this
14100 20 6f 70 74 69 6f 6e 3a 20 41 20 70 6f 69 6e 74   option: A point
14110 65 72 20 74 6f 20 38 2d 62 79 74 65 20 61 6c 69  er to 8-byte ali
14120 67 6e 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20  gned.** memory, 
14130 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68  the size of each
14140 20 70 61 67 65 20 62 75 66 66 65 72 20 28 73 7a   page buffer (sz
14150 29 2c 20 61 6e 64 20 74 68 65 20 6e 75 6d 62 65  ), and the numbe
14160 72 20 6f 66 20 70 61 67 65 73 20 28 4e 29 2e 0a  r of pages (N)..
14170 2a 2a 20 54 68 65 20 73 7a 20 61 72 67 75 6d 65  ** The sz argume
14180 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 74 68 65  nt should be the
14190 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6c 61 72   size of the lar
141a0 67 65 73 74 20 64 61 74 61 62 61 73 65 20 70 61  gest database pa
141b0 67 65 0a 2a 2a 20 28 61 20 70 6f 77 65 72 20 6f  ge.** (a power o
141c0 66 20 74 77 6f 20 62 65 74 77 65 65 6e 20 35 31  f two between 51
141d0 32 20 61 6e 64 20 33 32 37 36 38 29 20 70 6c 75  2 and 32768) plu
141e0 73 20 61 20 6c 69 74 74 6c 65 20 65 78 74 72 61  s a little extra
141f0 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70 61 67   for each.** pag
14200 65 20 68 65 61 64 65 72 2e 20 20 5e 54 68 65 20  e header.  ^The 
14210 70 61 67 65 20 68 65 61 64 65 72 20 73 69 7a 65  page header size
14220 20 69 73 20 32 30 20 74 6f 20 34 30 20 62 79 74   is 20 to 40 byt
14230 65 73 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 0a  es depending on.
14240 2a 2a 20 74 68 65 20 68 6f 73 74 20 61 72 63 68  ** the host arch
14250 69 74 65 63 74 75 72 65 2e 20 20 5e 49 74 20 69  itecture.  ^It i
14260 73 20 68 61 72 6d 6c 65 73 73 2c 20 61 70 61 72  s harmless, apar
14270 74 20 66 72 6f 6d 20 74 68 65 20 77 61 73 74 65  t from the waste
14280 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 6f 20  d memory,.** to 
14290 6d 61 6b 65 20 73 7a 20 61 20 6c 69 74 74 6c 65  make sz a little
142a0 20 74 6f 6f 20 6c 61 72 67 65 2e 20 20 54 68 65   too large.  The
142b0 20 66 69 72 73 74 0a 2a 2a 20 61 72 67 75 6d 65   first.** argume
142c0 6e 74 20 73 68 6f 75 6c 64 20 70 6f 69 6e 74 20  nt should point 
142d0 74 6f 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e  to an allocation
142e0 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a   of at least sz*
142f0 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72  N bytes of memor
14300 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69  y..** ^SQLite wi
14310 6c 6c 20 75 73 65 20 74 68 65 20 6d 65 6d 6f 72  ll use the memor
14320 79 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68  y provided by th
14330 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
14340 20 74 6f 20 73 61 74 69 73 66 79 20 69 74 73 0a   to satisfy its.
14350 2a 2a 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 20  ** memory needs 
14360 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 4e 20  for the first N 
14370 70 61 67 65 73 20 74 68 61 74 20 69 74 20 61 64  pages that it ad
14380 64 73 20 74 6f 20 63 61 63 68 65 2e 20 20 5e 49  ds to cache.  ^I
14390 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  f additional.** 
143a0 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72  page cache memor
143b0 79 20 69 73 20 6e 65 65 64 65 64 20 62 65 79 6f  y is needed beyo
143c0 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f 76 69  nd what is provi
143d0 64 65 64 20 62 79 20 74 68 69 73 20 6f 70 74 69  ded by this opti
143e0 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69  on, then.** SQLi
143f0 74 65 20 67 6f 65 73 20 74 6f 20 5b 73 71 6c 69  te goes to [sqli
14400 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 66 6f  te3_malloc()] fo
14410 72 20 74 68 65 20 61 64 64 69 74 69 6f 6e 61 6c  r the additional
14420 20 73 74 6f 72 61 67 65 20 73 70 61 63 65 2e 0a   storage space..
14430 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 20 69  ** The pointer i
14440 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
14450 6d 65 6e 74 20 6d 75 73 74 0a 2a 2a 20 62 65 20  ment must.** be 
14460 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d  aligned to an 8-
14470 62 79 74 65 20 62 6f 75 6e 64 61 72 79 20 6f 72  byte boundary or
14480 20 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61   subsequent beha
14490 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 0a 2a  vior of SQLite.*
144a0 2a 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66 69  * will be undefi
144b0 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ned.</dd>.**.** 
144c0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
144d0 47 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c  G_HEAP</dt>.** <
144e0 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  dd> ^This option
144f0 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61   specifies a sta
14500 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  tic memory buffe
14510 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69  r that SQLite wi
14520 6c 6c 20 75 73 65 0a 2a 2a 20 66 6f 72 20 61 6c  ll use.** for al
14530 6c 20 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63  l of its dynamic
14540 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
14550 6f 6e 20 6e 65 65 64 73 20 62 65 79 6f 6e 64 20  on needs beyond 
14560 74 68 6f 73 65 20 70 72 6f 76 69 64 65 64 0a 2a  those provided.*
14570 2a 20 66 6f 72 20 62 79 20 5b 53 51 4c 49 54 45  * for by [SQLITE
14580 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d  _CONFIG_SCRATCH]
14590 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 43 4f 4e   and [SQLITE_CON
145a0 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a  FIG_PAGECACHE]..
145b0 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 68 72  ** There are thr
145c0 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 41 6e  ee arguments: An
145d0 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20   8-byte aligned 
145e0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d  pointer to the m
145f0 65 6d 6f 72 79 2c 0a 2a 2a 20 74 68 65 20 6e 75  emory,.** the nu
14600 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
14610 20 74 68 65 20 6d 65 6d 6f 72 79 20 62 75 66 66   the memory buff
14620 65 72 2c 20 61 6e 64 20 74 68 65 20 6d 69 6e 69  er, and the mini
14630 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  mum allocation s
14640 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ize..** ^If the 
14650 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74  first pointer (t
14660 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65  he memory pointe
14670 72 29 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  r) is NULL, then
14680 20 53 51 4c 69 74 65 20 72 65 76 65 72 74 73 0a   SQLite reverts.
14690 2a 2a 20 74 6f 20 75 73 69 6e 67 20 69 74 73 20  ** to using its 
146a0 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61  default memory a
146b0 6c 6c 6f 63 61 74 6f 72 20 28 74 68 65 20 73 79  llocator (the sy
146c0 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 69 6d  stem malloc() im
146d0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a  plementation),.*
146e0 2a 20 75 6e 64 6f 69 6e 67 20 61 6e 79 20 70 72  * undoing any pr
146f0 69 6f 72 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f  ior invocation o
14700 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  f [SQLITE_CONFIG
14710 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 5e 49 66 20 74  _MALLOC].  ^If t
14720 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f 69  he.** memory poi
14730 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  nter is not NULL
14740 20 61 6e 64 20 65 69 74 68 65 72 20 5b 53 51 4c   and either [SQL
14750 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59  ITE_ENABLE_MEMSY
14760 53 33 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54  S3] or.** [SQLIT
14770 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 35  E_ENABLE_MEMSYS5
14780 5d 20 61 72 65 20 64 65 66 69 6e 65 64 2c 20 74  ] are defined, t
14790 68 65 6e 20 74 68 65 20 61 6c 74 65 72 6e 61 74  hen the alternat
147a0 69 76 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c  ive memory.** al
147b0 6c 6f 63 61 74 6f 72 20 69 73 20 65 6e 67 61 67  locator is engag
147c0 65 64 20 74 6f 20 68 61 6e 64 6c 65 20 61 6c 6c  ed to handle all
147d0 20 6f 66 20 53 51 4c 69 74 65 73 20 6d 65 6d 6f   of SQLites memo
147e0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65  ry allocation ne
147f0 65 64 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73  eds..** The firs
14800 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d  t pointer (the m
14810 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 6d  emory pointer) m
14820 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74  ust be aligned t
14830 6f 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 62  o an 8-byte.** b
14840 6f 75 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65  oundary or subse
14850 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f  quent behavior o
14860 66 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65  f SQLite will be
14870 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54   undefined..** T
14880 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63  he minimum alloc
14890 61 74 69 6f 6e 20 73 69 7a 65 20 69 73 20 63 61  ation size is ca
148a0 70 70 65 64 20 61 74 20 32 5e 31 32 2e 20 52 65  pped at 2^12. Re
148b0 61 73 6f 6e 61 62 6c 65 20 76 61 6c 75 65 73 0a  asonable values.
148c0 2a 2a 20 66 6f 72 20 74 68 65 20 6d 69 6e 69 6d  ** for the minim
148d0 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69  um allocation si
148e0 7a 65 20 61 72 65 20 32 5e 35 20 74 68 72 6f 75  ze are 2^5 throu
148f0 67 68 20 32 5e 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a  gh 2^8.</dd>.**.
14900 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
14910 4e 46 49 47 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a  NFIG_MUTEX</dt>.
14920 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f  ** <dd> ^(This o
14930 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
14940 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
14950 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ich is a pointer
14960 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e   to an.** instan
14970 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ce of the [sqlit
14980 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
14990 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68  ] structure.  Th
149a0 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69  e argument speci
149b0 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74  fies.** alternat
149c0 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75  ive low-level mu
149d0 74 65 78 20 72 6f 75 74 69 6e 65 73 20 74 6f 20  tex routines to 
149e0 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65  be used in place
149f0 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 20 72 6f  .** the mutex ro
14a00 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74  utines built int
14a10 6f 20 53 51 4c 69 74 65 2e 29 5e 20 20 5e 53 51  o SQLite.)^  ^SQ
14a20 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70  Lite makes a cop
14a30 79 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6e 74  y of the.** cont
14a40 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  ent of the [sqli
14a50 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
14a60 73 5d 20 73 74 72 75 63 74 75 72 65 20 62 65 66  s] structure bef
14a70 6f 72 65 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a  ore the call to.
14a80 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
14a90 69 67 28 29 5d 20 72 65 74 75 72 6e 73 2e 20 5e  ig()] returns. ^
14aa0 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
14ab0 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  piled with.** th
14ac0 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
14ad0 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48  SAFE | SQLITE_TH
14ae0 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70  READSAFE=0] comp
14af0 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
14b00 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69  then.** the enti
14b10 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73  re mutexing subs
14b20 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64  ystem is omitted
14b30 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20   from the build 
14b40 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20  and hence calls 
14b50 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  to.** [sqlite3_c
14b60 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74 68  onfig()] with th
14b70 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
14b80 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61 74  MUTEX configurat
14b90 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a  ion option will.
14ba0 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ** return [SQLIT
14bb0 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a  E_ERROR].</dd>.*
14bc0 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
14bd0 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 3c  CONFIG_GETMUTEX<
14be0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
14bf0 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
14c00 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
14c10 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f  nt which is a po
14c20 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69  inter to an.** i
14c30 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b  nstance of the [
14c40 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
14c50 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
14c60 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  .  The.** [sqlit
14c70 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
14c80 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69  ].** structure i
14c90 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68  s filled with th
14ca0 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69  e currently defi
14cb0 6e 65 64 20 6d 75 74 65 78 20 72 6f 75 74 69 6e  ned mutex routin
14cc0 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70  es.)^.** This op
14cd0 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64  tion can be used
14ce0 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65   to overload the
14cf0 20 64 65 66 61 75 6c 74 20 6d 75 74 65 78 20 61   default mutex a
14d00 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75  llocation.** rou
14d10 74 69 6e 65 73 20 77 69 74 68 20 61 20 77 72 61  tines with a wra
14d20 70 70 65 72 20 75 73 65 64 20 74 6f 20 74 72 61  pper used to tra
14d30 63 6b 20 6d 75 74 65 78 20 75 73 61 67 65 20 66  ck mutex usage f
14d40 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63 65 0a 2a  or performance.*
14d50 2a 20 70 72 6f 66 69 6c 69 6e 67 20 6f 72 20 74  * profiling or t
14d60 65 73 74 69 6e 67 2c 20 66 6f 72 20 65 78 61 6d  esting, for exam
14d70 70 6c 65 2e 20 20 20 5e 49 66 20 53 51 4c 69 74  ple.   ^If SQLit
14d80 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
14d90 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54  th.** the [SQLIT
14da0 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53  E_THREADSAFE | S
14db0 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
14dc0 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  =0] compile-time
14dd0 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20   option then.** 
14de0 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78  the entire mutex
14df0 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69 73  ing subsystem is
14e00 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68   omitted from th
14e10 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63  e build and henc
14e20 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73  e calls to.** [s
14e30 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
14e40 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45   with the SQLITE
14e50 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58  _CONFIG_GETMUTEX
14e60 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
14e70 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65  ption will.** re
14e80 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52  turn [SQLITE_ERR
14e90 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  OR].</dd>.**.** 
14ea0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
14eb0 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e  G_LOOKASIDE</dt>
14ec0 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20  .** <dd> ^(This 
14ed0 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f  option takes two
14ee0 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20   arguments that 
14ef0 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 64 65  determine the de
14f00 66 61 75 6c 74 0a 2a 2a 20 6d 65 6d 6f 72 79 20  fault.** memory 
14f10 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 20 74  allocation for t
14f20 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  he lookaside mem
14f30 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 6f 6e  ory allocator on
14f40 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61   each.** [databa
14f50 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20  se connection]. 
14f60 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
14f70 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69  ent is the.** si
14f80 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61  ze of each looka
14f90 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74  side buffer slot
14fa0 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20   and the second 
14fb0 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
14fc0 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 61  .** slots alloca
14fd0 74 65 64 20 74 6f 20 65 61 63 68 20 64 61 74 61  ted to each data
14fe0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e  base connection.
14ff0 29 5e 20 20 5e 28 54 68 69 73 20 6f 70 74 69 6f  )^  ^(This optio
15000 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 3c 69  n sets the.** <i
15010 3e 64 65 66 61 75 6c 74 3c 2f 69 3e 20 6c 6f 6f  >default</i> loo
15020 6b 61 73 69 64 65 20 73 69 7a 65 2e 20 54 68 65  kaside size. The
15030 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49   [SQLITE_DBCONFI
15040 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 0a 2a 2a 20  G_LOOKASIDE].** 
15050 76 65 72 62 20 74 6f 20 5b 73 71 6c 69 74 65 33  verb to [sqlite3
15060 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61  _db_config()] ca
15070 6e 20 62 65 20 75 73 65 64 20 74 6f 20 63 68 61  n be used to cha
15080 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64  nge the lookasid
15090 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69  e.** configurati
150a0 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c  on on individual
150b0 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29 5e 20   connections.)^ 
150c0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
150d0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
150e0 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ACHE</dt>.** <dd
150f0 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20  > ^(This option 
15100 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
15110 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
15120 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a   a pointer to.**
15130 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61   an [sqlite3_pca
15140 63 68 65 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  che_methods] obj
15150 65 63 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 63  ect.  This objec
15160 74 20 73 70 65 63 69 66 69 65 73 20 74 68 65 20  t specifies the 
15170 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 74 6f 20  interface.** to 
15180 61 20 63 75 73 74 6f 6d 20 70 61 67 65 20 63 61  a custom page ca
15190 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  che implementati
151a0 6f 6e 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d  on.)^  ^SQLite m
151b0 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74  akes a copy of t
151c0 68 65 0a 2a 2a 20 6f 62 6a 65 63 74 20 61 6e 64  he.** object and
151d0 20 75 73 65 73 20 69 74 20 66 6f 72 20 70 61 67   uses it for pag
151e0 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 61  e cache memory a
151f0 6c 6c 6f 63 61 74 69 6f 6e 73 2e 3c 2f 64 64 3e  llocations.</dd>
15200 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
15210 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43  E_CONFIG_GETPCAC
15220 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  HE</dt>.** <dd> 
15230 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61  ^(This option ta
15240 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
15250 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
15260 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a   pointer to an.*
15270 2a 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68  * [sqlite3_pcach
15280 65 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  e_methods] objec
15290 74 2e 20 20 53 51 4c 69 74 65 20 63 6f 70 69 65  t.  SQLite copie
152a0 73 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74  s of the current
152b0 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20 69  .** page cache i
152c0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e  mplementation in
152d0 74 6f 20 74 68 61 74 20 6f 62 6a 65 63 74 2e 29  to that object.)
152e0 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  ^ </dd>.**.** <d
152f0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
15300 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  LOG</dt>.** <dd>
15310 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e   ^The SQLITE_CON
15320 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 74  FIG_LOG option t
15330 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e  akes two argumen
15340 74 73 3a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  ts: a pointer to
15350 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77   a.** function w
15360 69 74 68 20 61 20 63 61 6c 6c 20 73 69 67 6e 61  ith a call signa
15370 74 75 72 65 20 6f 66 20 76 6f 69 64 28 2a 29 28  ture of void(*)(
15380 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
15390 63 68 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20  char*), .** and 
153a0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 76 6f 69  a pointer to voi
153b0 64 2e 20 5e 49 66 20 74 68 65 20 66 75 6e 63 74  d. ^If the funct
153c0 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e  ion pointer is n
153d0 6f 74 20 4e 55 4c 4c 2c 20 69 74 20 69 73 0a 2a  ot NULL, it is.*
153e0 2a 20 69 6e 76 6f 6b 65 64 20 62 79 20 5b 73 71  * invoked by [sq
153f0 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 74 6f 20  lite3_log()] to 
15400 70 72 6f 63 65 73 73 20 65 61 63 68 20 6c 6f 67  process each log
15410 67 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66  ging event.  ^If
15420 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e   the.** function
15430 20 70 6f 69 6e 74 65 72 20 69 73 20 4e 55 4c 4c   pointer is NULL
15440 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c  , the [sqlite3_l
15450 6f 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  og()] interface 
15460 62 65 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e  becomes a no-op.
15470 0a 2a 2a 20 5e 54 68 65 20 76 6f 69 64 20 70 6f  .** ^The void po
15480 69 6e 74 65 72 20 74 68 61 74 20 69 73 20 74 68  inter that is th
15490 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
154a0 74 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46  t to SQLITE_CONF
154b0 49 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70 61 73  IG_LOG is.** pas
154c0 73 65 64 20 74 68 72 6f 75 67 68 20 61 73 20 74  sed through as t
154d0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
154e0 65 72 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63  er to the applic
154f0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f  ation-defined lo
15500 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  gger.** function
15510 20 77 68 65 6e 65 76 65 72 20 74 68 61 74 20 66   whenever that f
15520 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b  unction is invok
15530 65 64 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64  ed.  ^The second
15540 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
15550 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63   the logger func
15560 74 69 6f 6e 20 69 73 20 61 20 63 6f 70 79 20 6f  tion is a copy o
15570 66 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  f the first para
15580 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 6f 72  meter to the cor
15590 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73  responding.** [s
155a0 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 63 61  qlite3_log()] ca
155b0 6c 6c 20 61 6e 64 20 69 73 20 69 6e 74 65 6e 64  ll and is intend
155c0 65 64 20 74 6f 20 62 65 20 61 20 5b 72 65 73 75  ed to be a [resu
155d0 6c 74 20 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a  lt code] or an.*
155e0 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  * [extended resu
155f0 6c 74 20 63 6f 64 65 5d 2e 20 20 5e 54 68 65 20  lt code].  ^The 
15600 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
15610 70 61 73 73 65 64 20 74 6f 20 74 68 65 20 6c 6f  passed to the lo
15620 67 67 65 72 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d  gger is.** log m
15630 65 73 73 61 67 65 20 61 66 74 65 72 20 66 6f 72  essage after for
15640 6d 61 74 74 69 6e 67 20 76 69 61 20 5b 73 71 6c  matting via [sql
15650 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d  ite3_snprintf()]
15660 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20  ..** The SQLite 
15670 6c 6f 67 67 69 6e 67 20 69 6e 74 65 72 66 61 63  logging interfac
15680 65 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61  e is not reentra
15690 6e 74 3b 20 74 68 65 20 6c 6f 67 67 65 72 20 66  nt; the logger f
156a0 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c  unction.** suppl
156b0 69 65 64 20 62 79 20 74 68 65 20 61 70 70 6c 69  ied by the appli
156c0 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  cation must not 
156d0 69 6e 76 6f 6b 65 20 61 6e 79 20 53 51 4c 69 74  invoke any SQLit
156e0 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20  e interface..** 
156f0 49 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61  In a multi-threa
15700 64 65 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c  ded application,
15710 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
15720 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a  -defined logger.
15730 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74  ** function must
15740 20 62 65 20 74 68 72 65 61 64 73 61 66 65 2e 20   be threadsafe. 
15750 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c  </dd>.**.** </dl
15760 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  >.*/.#define SQL
15770 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
15780 45 54 48 52 45 41 44 20 20 31 20 20 2f 2a 20 6e  ETHREAD  1  /* n
15790 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  il */.#define SQ
157a0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
157b0 49 54 48 52 45 41 44 20 20 20 32 20 20 2f 2a 20  ITHREAD   2  /* 
157c0 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nil */.#define S
157d0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52  QLITE_CONFIG_SER
157e0 49 41 4c 49 5a 45 44 20 20 20 20 33 20 20 2f 2a  IALIZED    3  /*
157f0 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20   nil */.#define 
15800 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
15810 4c 4c 4f 43 20 20 20 20 20 20 20 20 34 20 20 2f  LLOC        4  /
15820 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  * sqlite3_mem_me
15830 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e  thods* */.#defin
15840 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
15850 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20 20 35 20  GETMALLOC     5 
15860 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f   /* sqlite3_mem_
15870 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66  methods* */.#def
15880 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
15890 47 5f 53 43 52 41 54 43 48 20 20 20 20 20 20 20  G_SCRATCH       
158a0 36 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74  6  /* void*, int
158b0 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64   sz, int N */.#d
158c0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
158d0 46 49 47 5f 50 41 47 45 43 41 43 48 45 20 20 20  FIG_PAGECACHE   
158e0 20 20 37 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69    7  /* void*, i
158f0 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a  nt sz, int N */.
15900 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
15910 4f 4e 46 49 47 5f 48 45 41 50 20 20 20 20 20 20  ONFIG_HEAP      
15920 20 20 20 20 38 20 20 2f 2a 20 76 6f 69 64 2a 2c      8  /* void*,
15930 20 69 6e 74 20 6e 42 79 74 65 2c 20 69 6e 74 20   int nByte, int 
15940 6d 69 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  min */.#define S
15950 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
15960 53 54 41 54 55 53 20 20 20 20 20 39 20 20 2f 2a  STATUS     9  /*
15970 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65 66   boolean */.#def
15980 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
15990 47 5f 4d 55 54 45 58 20 20 20 20 20 20 20 20 31  G_MUTEX        1
159a0 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75  0  /* sqlite3_mu
159b0 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a  tex_methods* */.
159c0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
159d0 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 20  ONFIG_GETMUTEX  
159e0 20 20 20 31 31 20 20 2f 2a 20 73 71 6c 69 74 65     11  /* sqlite
159f0 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a  3_mutex_methods*
15a00 20 2a 2f 0a 2f 2a 20 70 72 65 76 69 6f 75 73 6c   */./* previousl
15a10 79 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  y SQLITE_CONFIG_
15a20 43 48 55 4e 4b 41 4c 4c 4f 43 20 31 32 20 77 68  CHUNKALLOC 12 wh
15a30 69 63 68 20 69 73 20 6e 6f 77 20 75 6e 75 73 65  ich is now unuse
15a40 64 2e 20 2a 2f 20 0a 23 64 65 66 69 6e 65 20 53  d. */ .#define S
15a50 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f  QLITE_CONFIG_LOO
15a60 4b 41 53 49 44 45 20 20 20 20 31 33 20 20 2f 2a  KASIDE    13  /*
15a70 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66   int int */.#def
15a80 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
15a90 47 5f 50 43 41 43 48 45 20 20 20 20 20 20 20 31  G_PCACHE       1
15aa0 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63  4  /* sqlite3_pc
15ab0 61 63 68 65 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f  ache_methods* */
15ac0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
15ad0 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
15ae0 20 20 20 20 31 35 20 20 2f 2a 20 73 71 6c 69 74      15  /* sqlit
15af0 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64  e3_pcache_method
15b00 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  s* */.#define SQ
15b10 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20  LITE_CONFIG_LOG 
15b20 20 20 20 20 20 20 20 20 20 31 36 20 20 2f 2a 20           16  /* 
15b30 78 46 75 6e 63 2c 20 76 6f 69 64 2a 20 2a 2f 0a  xFunc, void* */.
15b40 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
15b50 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63   Database Connec
15b60 74 69 6f 6e 20 43 6f 6e 66 69 67 75 72 61 74 69  tion Configurati
15b70 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a  on Options.**.**
15b80 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73   These constants
15b90 20 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62   are the availab
15ba0 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69  le integer confi
15bb0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
15bc0 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20   that.** can be 
15bd0 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65  passed as the se
15be0 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
15bf0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62   the [sqlite3_db
15c00 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72  _config()] inter
15c10 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20  face..**.** New 
15c20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
15c30 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64  tions may be add
15c40 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ed in future rel
15c50 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e  eases of SQLite.
15c60 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e  .** Existing con
15c70 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
15c80 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63  ns might be disc
15c90 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69  ontinued.  Appli
15ca0 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c  cations.** shoul
15cb0 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75  d check the retu
15cc0 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71  rn code from [sq
15cd0 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
15ce0 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20  )] to make sure 
15cf0 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c  that.** the call
15d00 20 77 6f 72 6b 65 64 2e 20 20 5e 54 68 65 20 5b   worked.  ^The [
15d10 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
15d20 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77  g()] interface w
15d30 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20  ill return a.** 
15d40 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20  non-zero [error 
15d50 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f  code] if a disco
15d60 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70  ntinued or unsup
15d70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61  ported configura
15d80 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69  tion option.** i
15d90 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a  s invoked..**.**
15da0 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c   <dl>.** <dt>SQL
15db0 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
15dc0 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c  KASIDE</dt>.** <
15dd0 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  dd> ^This option
15de0 20 74 61 6b 65 73 20 74 68 72 65 65 20 61 64 64   takes three add
15df0 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74  itional argument
15e00 73 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65  s that determine
15e10 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73   the .** [lookas
15e20 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ide memory alloc
15e30 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72 61 74  ator] configurat
15e40 69 6f 6e 20 66 6f 72 20 74 68 65 20 5b 64 61 74  ion for the [dat
15e50 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
15e60 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  ]..** ^The first
15e70 20 61 72 67 75 6d 65 6e 74 20 28 74 68 65 20 74   argument (the t
15e80 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
15e90 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  o [sqlite3_db_co
15ea0 6e 66 69 67 28 29 5d 20 69 73 20 61 0a 2a 2a 20  nfig()] is a.** 
15eb0 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d  pointer to a mem
15ec0 6f 72 79 20 62 75 66 66 65 72 20 74 6f 20 75 73  ory buffer to us
15ed0 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64 65 20  e for lookaside 
15ee0 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65 20  memory..** ^The 
15ef0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 61  first argument a
15f00 66 74 65 72 20 74 68 65 20 53 51 4c 49 54 45 5f  fter the SQLITE_
15f10 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  DBCONFIG_LOOKASI
15f20 44 45 20 76 65 72 62 0a 2a 2a 20 6d 61 79 20 62  DE verb.** may b
15f30 65 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63 68 20  e NULL in which 
15f40 63 61 73 65 20 53 51 4c 69 74 65 20 77 69 6c 6c  case SQLite will
15f50 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 0a 2a 2a   allocate the.**
15f60 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65   lookaside buffe
15f70 72 20 69 74 73 65 6c 66 20 75 73 69 6e 67 20 5b  r itself using [
15f80 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
15f90 5d 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61  ]. ^The second a
15fa0 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a  rgument is the.*
15fb0 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c  * size of each l
15fc0 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20  ookaside buffer 
15fd0 73 6c 6f 74 2e 20 20 5e 54 68 65 20 74 68 69 72  slot.  ^The thir
15fe0 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
15ff0 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73  e number of.** s
16000 6c 6f 74 73 2e 20 20 54 68 65 20 73 69 7a 65 20  lots.  The size 
16010 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 69 6e  of the buffer in
16020 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
16030 65 6e 74 20 6d 75 73 74 20 62 65 20 67 72 65 61  ent must be grea
16040 74 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72 20 65  ter than.** or e
16050 71 75 61 6c 20 74 6f 20 74 68 65 20 70 72 6f 64  qual to the prod
16060 75 63 74 20 6f 66 20 74 68 65 20 73 65 63 6f 6e  uct of the secon
16070 64 20 61 6e 64 20 74 68 69 72 64 20 61 72 67 75  d and third argu
16080 6d 65 6e 74 73 2e 20 20 54 68 65 20 62 75 66 66  ments.  The buff
16090 65 72 0a 2a 2a 20 6d 75 73 74 20 62 65 20 61 6c  er.** must be al
160a0 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79  igned to an 8-by
160b0 74 65 20 62 6f 75 6e 64 61 72 79 2e 20 20 5e 49  te boundary.  ^I
160c0 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  f the second arg
160d0 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c 49  ument to.** SQLI
160e0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
160f0 41 53 49 44 45 20 69 73 20 6e 6f 74 20 61 20 6d  ASIDE is not a m
16100 75 6c 74 69 70 6c 65 20 6f 66 20 38 2c 20 69 74  ultiple of 8, it
16110 20 69 73 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a   is internally.*
16120 2a 20 72 6f 75 6e 64 65 64 20 64 6f 77 6e 20 74  * rounded down t
16130 6f 20 74 68 65 20 6e 65 78 74 20 73 6d 61 6c 6c  o the next small
16140 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38  er multiple of 8
16150 2e 20 20 5e 28 54 68 65 20 6c 6f 6f 6b 61 73 69  .  ^(The lookasi
16160 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f 6e  de memory.** con
16170 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 61  figuration for a
16180 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
16190 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79 20 62 65  tion can only be
161a0 20 63 68 61 6e 67 65 64 20 77 68 65 6e 20 74 68   changed when th
161b0 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  at.** connection
161c0 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c   is not currentl
161d0 79 20 75 73 69 6e 67 20 6c 6f 6f 6b 61 73 69 64  y using lookasid
161e0 65 20 6d 65 6d 6f 72 79 2c 20 6f 72 20 69 6e 20  e memory, or in 
161f0 6f 74 68 65 72 20 77 6f 72 64 73 0a 2a 2a 20 77  other words.** w
16200 68 65 6e 20 74 68 65 20 22 63 75 72 72 65 6e 74  hen the "current
16210 20 76 61 6c 75 65 22 20 72 65 74 75 72 6e 65 64   value" returned
16220 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   by.** [sqlite3_
16230 64 62 5f 73 74 61 74 75 73 5d 28 44 2c 5b 53 51  db_status](D,[SQ
16240 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  LITE_CONFIG_LOOK
16250 41 53 49 44 45 5d 2c 2e 2e 2e 29 20 69 73 20 7a  ASIDE],...) is z
16260 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65  ero..** Any atte
16270 6d 70 74 20 74 6f 20 63 68 61 6e 67 65 20 74 68  mpt to change th
16280 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f  e lookaside memo
16290 72 79 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ry configuration
162a0 20 77 68 65 6e 20 6c 6f 6f 6b 61 73 69 64 65 0a   when lookaside.
162b0 2a 2a 20 6d 65 6d 6f 72 79 20 69 73 20 69 6e 20  ** memory is in 
162c0 75 73 65 20 6c 65 61 76 65 73 20 74 68 65 20 63  use leaves the c
162d0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 6e 63  onfiguration unc
162e0 68 61 6e 67 65 64 20 61 6e 64 20 72 65 74 75 72  hanged and retur
162f0 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42  ns .** [SQLITE_B
16300 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a  USY].)^</dd>.**.
16310 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42  ** <dt>SQLITE_DB
16320 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b  CONFIG_ENABLE_FK
16330 45 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  EY</dt>.** <dd> 
16340 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20  ^This option is 
16350 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f  used to enable o
16360 72 20 64 69 73 61 62 6c 65 20 74 68 65 20 65 6e  r disable the en
16370 66 6f 72 63 65 6d 65 6e 74 20 6f 66 0a 2a 2a 20  forcement of.** 
16380 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 63 6f 6e  [foreign key con
16390 73 74 72 61 69 6e 74 73 5d 2e 20 20 54 68 65 72  straints].  Ther
163a0 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20  e should be two 
163b0 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d  additional argum
163c0 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72  ents..** The fir
163d0 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  st argument is a
163e0 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20  n integer which 
163f0 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20  is 0 to disable 
16400 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 2c 0a  FK enforcement,.
16410 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65  ** positive to e
16420 6e 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65  nable FK enforce
16430 6d 65 6e 74 20 6f 72 20 6e 65 67 61 74 69 76 65  ment or negative
16440 20 74 6f 20 6c 65 61 76 65 20 46 4b 20 65 6e 66   to leave FK enf
16450 6f 72 63 65 6d 65 6e 74 0a 2a 2a 20 75 6e 63 68  orcement.** unch
16460 61 6e 67 65 64 2e 20 20 54 68 65 20 73 65 63 6f  anged.  The seco
16470 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
16480 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
16490 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69  integer into whi
164a0 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e  ch.** is written
164b0 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63   0 or 1 to indic
164c0 61 74 65 20 77 68 65 74 68 65 72 20 46 4b 20 65  ate whether FK e
164d0 6e 66 6f 72 63 65 6d 65 6e 74 20 69 73 20 6f 66  nforcement is of
164e0 66 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f  f or on.** follo
164f0 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20  wing this call. 
16500 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
16510 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e  meter may be a N
16520 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a  ULL pointer, in.
16530 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20 74 68  ** which case th
16540 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74  e FK enforcement
16550 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20   setting is not 
16560 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c  reported back. <
16570 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
16580 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45  QLITE_DBCONFIG_E
16590 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 3c 2f 64  NABLE_TRIGGER</d
165a0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
165b0 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20   option is used 
165c0 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73  to enable or dis
165d0 61 62 6c 65 20 5b 43 52 45 41 54 45 20 54 52 49  able [CREATE TRI
165e0 47 47 45 52 20 7c 20 74 72 69 67 67 65 72 73 5d  GGER | triggers]
165f0 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75 6c  ..** There shoul
16600 64 20 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f  d be two additio
16610 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a  nal arguments..*
16620 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
16630 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67  ment is an integ
16640 65 72 20 77 68 69 63 68 20 69 73 20 30 20 74 6f  er which is 0 to
16650 20 64 69 73 61 62 6c 65 20 74 72 69 67 67 65 72   disable trigger
16660 73 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74  s,.** positive t
16670 6f 20 65 6e 61 62 6c 65 20 74 72 69 67 67 65 72  o enable trigger
16680 73 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f  s or negative to
16690 20 6c 65 61 76 65 20 74 68 65 20 73 65 74 74 69   leave the setti
166a0 6e 67 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a  ng unchanged..**
166b0 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
166c0 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74  meter is a point
166d0 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  er to an integer
166e0 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69   into which.** i
166f0 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31  s written 0 or 1
16700 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65   to indicate whe
16710 74 68 65 72 20 74 72 69 67 67 65 72 73 20 61 72  ther triggers ar
16720 65 20 64 69 73 61 62 6c 65 64 20 6f 72 20 65 6e  e disabled or en
16730 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69  abled.** followi
16740 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54  ng this call.  T
16750 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
16760 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c  ter may be a NUL
16770 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a  L pointer, in.**
16780 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20   which case the 
16790 74 72 69 67 67 65 72 20 73 65 74 74 69 6e 67 20  trigger setting 
167a0 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20  is not reported 
167b0 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  back. </dd>.**.*
167c0 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69  * </dl>.*/.#defi
167d0 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  ne SQLITE_DBCONF
167e0 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20  IG_LOOKASIDE    
167f0 20 20 20 31 30 30 31 20 20 2f 2a 20 76 6f 69 64     1001  /* void
16800 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65  * int int */.#de
16810 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f  fine SQLITE_DBCO
16820 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59  NFIG_ENABLE_FKEY
16830 20 20 20 20 20 31 30 30 32 20 20 2f 2a 20 69 6e       1002  /* in
16840 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e  t int* */.#defin
16850 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  e SQLITE_DBCONFI
16860 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52  G_ENABLE_TRIGGER
16870 20 20 31 30 30 33 20 20 2f 2a 20 69 6e 74 20 69    1003  /* int i
16880 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43  nt* */.../*.** C
16890 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20  API3REF: Enable 
168a0 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74 65 6e  Or Disable Exten
168b0 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73  ded Result Codes
168c0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
168d0 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73  te3_extended_res
168e0 75 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f 75 74  ult_codes() rout
168f0 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 64  ine enables or d
16900 69 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a 20 5b  isables the.** [
16910 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
16920 63 6f 64 65 73 5d 20 66 65 61 74 75 72 65 20 6f  codes] feature o
16930 66 20 53 51 4c 69 74 65 2e 20 5e 54 68 65 20 65  f SQLite. ^The e
16940 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 0a 2a  xtended result.*
16950 2a 20 63 6f 64 65 73 20 61 72 65 20 64 69 73 61  * codes are disa
16960 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20  bled by default 
16970 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 20 63  for historical c
16980 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2f  ompatibility..*/
16990 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
169a0 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
169b0 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 73 71  _result_codes(sq
169c0 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66  lite3*, int onof
169d0 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  f);../*.** CAPI3
169e0 52 45 46 3a 20 4c 61 73 74 20 49 6e 73 65 72 74  REF: Last Insert
169f0 20 52 6f 77 69 64 0a 2a 2a 0a 2a 2a 20 5e 45 61   Rowid.**.** ^Ea
16a00 63 68 20 65 6e 74 72 79 20 69 6e 20 61 6e 20 53  ch entry in an S
16a10 51 4c 69 74 65 20 74 61 62 6c 65 20 68 61 73 20  QLite table has 
16a20 61 20 75 6e 69 71 75 65 20 36 34 2d 62 69 74 20  a unique 64-bit 
16a30 73 69 67 6e 65 64 0a 2a 2a 20 69 6e 74 65 67 65  signed.** intege
16a40 72 20 6b 65 79 20 63 61 6c 6c 65 64 20 74 68 65  r key called the
16a50 20 5b 52 4f 57 49 44 20 7c 20 22 72 6f 77 69 64   [ROWID | "rowid
16a60 22 5d 2e 20 5e 54 68 65 20 72 6f 77 69 64 20 69  "]. ^The rowid i
16a70 73 20 61 6c 77 61 79 73 20 61 76 61 69 6c 61 62  s always availab
16a80 6c 65 0a 2a 2a 20 61 73 20 61 6e 20 75 6e 64 65  le.** as an unde
16a90 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 20 6e 61  clared column na
16aa0 6d 65 64 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20  med ROWID, OID, 
16ab0 6f 72 20 5f 52 4f 57 49 44 5f 20 61 73 20 6c 6f  or _ROWID_ as lo
16ac0 6e 67 20 61 73 20 74 68 6f 73 65 0a 2a 2a 20 6e  ng as those.** n
16ad0 61 6d 65 73 20 61 72 65 20 6e 6f 74 20 61 6c 73  ames are not als
16ae0 6f 20 75 73 65 64 20 62 79 20 65 78 70 6c 69 63  o used by explic
16af0 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20 63 6f  itly declared co
16b00 6c 75 6d 6e 73 2e 20 5e 49 66 0a 2a 2a 20 74 68  lumns. ^If.** th
16b10 65 20 74 61 62 6c 65 20 68 61 73 20 61 20 63 6f  e table has a co
16b20 6c 75 6d 6e 20 6f 66 20 74 79 70 65 20 5b 49 4e  lumn of type [IN
16b30 54 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45  TEGER PRIMARY KE
16b40 59 5d 20 74 68 65 6e 20 74 68 61 74 20 63 6f 6c  Y] then that col
16b50 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e 6f 74 68 65  umn.** is anothe
16b60 72 20 61 6c 69 61 73 20 66 6f 72 20 74 68 65 20  r alias for the 
16b70 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  rowid..**.** ^Th
16b80 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  is routine retur
16b90 6e 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f  ns the [rowid] o
16ba0 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
16bb0 74 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20  t.** successful 
16bc0 5b 49 4e 53 45 52 54 5d 20 69 6e 74 6f 20 74 68  [INSERT] into th
16bd0 65 20 64 61 74 61 62 61 73 65 20 66 72 6f 6d 20  e database from 
16be0 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
16bf0 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20  nnection].** in 
16c00 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
16c10 6e 74 2e 20 20 5e 49 66 20 6e 6f 20 73 75 63 63  nt.  ^If no succ
16c20 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 73  essful [INSERT]s
16c30 0a 2a 2a 20 68 61 76 65 20 65 76 65 72 20 6f 63  .** have ever oc
16c40 63 75 72 72 65 64 20 6f 6e 20 74 68 61 74 20 64  curred on that d
16c50 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
16c60 6f 6e 2c 20 7a 65 72 6f 20 69 73 20 72 65 74 75  on, zero is retu
16c70 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66  rned..**.** ^(If
16c80 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 6f 63 63   an [INSERT] occ
16c90 75 72 73 20 77 69 74 68 69 6e 20 61 20 74 72 69  urs within a tri
16ca0 67 67 65 72 2c 20 74 68 65 6e 20 74 68 65 20 5b  gger, then the [
16cb0 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 69 6e  rowid] of the in
16cc0 73 65 72 74 65 64 0a 2a 2a 20 72 6f 77 20 69 73  serted.** row is
16cd0 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69   returned by thi
16ce0 73 20 72 6f 75 74 69 6e 65 20 61 73 20 6c 6f 6e  s routine as lon
16cf0 67 20 61 73 20 74 68 65 20 74 72 69 67 67 65 72  g as the trigger
16d00 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20   is running..** 
16d10 42 75 74 20 6f 6e 63 65 20 74 68 65 20 74 72 69  But once the tri
16d20 67 67 65 72 20 74 65 72 6d 69 6e 61 74 65 73 2c  gger terminates,
16d30 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
16d40 6e 65 64 20 62 79 20 74 68 69 73 20 72 6f 75 74  ned by this rout
16d50 69 6e 65 0a 2a 2a 20 72 65 76 65 72 74 73 20 74  ine.** reverts t
16d60 6f 20 74 68 65 20 6c 61 73 74 20 76 61 6c 75 65  o the last value
16d70 20 69 6e 73 65 72 74 65 64 20 62 65 66 6f 72 65   inserted before
16d80 20 74 68 65 20 74 72 69 67 67 65 72 20 66 69 72   the trigger fir
16d90 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20  ed.)^.**.** ^An 
16da0 5b 49 4e 53 45 52 54 5d 20 74 68 61 74 20 66 61  [INSERT] that fa
16db0 69 6c 73 20 64 75 65 20 74 6f 20 61 20 63 6f 6e  ils due to a con
16dc0 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f  straint violatio
16dd0 6e 20 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 75  n is not a.** su
16de0 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54  ccessful [INSERT
16df0 5d 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63  ] and does not c
16e00 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 20  hange the value 
16e10 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73  returned by this
16e20 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 20 5e 54  .** routine.  ^T
16e30 68 75 73 20 49 4e 53 45 52 54 20 4f 52 20 46 41  hus INSERT OR FA
16e40 49 4c 2c 20 49 4e 53 45 52 54 20 4f 52 20 49 47  IL, INSERT OR IG
16e50 4e 4f 52 45 2c 20 49 4e 53 45 52 54 20 4f 52 20  NORE, INSERT OR 
16e60 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64  ROLLBACK,.** and
16e70 20 49 4e 53 45 52 54 20 4f 52 20 41 42 4f 52 54   INSERT OR ABORT
16e80 20 6d 61 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73   make no changes
16e90 20 74 6f 20 74 68 65 20 72 65 74 75 72 6e 20 76   to the return v
16ea0 61 6c 75 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20  alue of this.** 
16eb0 72 6f 75 74 69 6e 65 20 77 68 65 6e 20 74 68 65  routine when the
16ec0 69 72 20 69 6e 73 65 72 74 69 6f 6e 20 66 61 69  ir insertion fai
16ed0 6c 73 2e 20 20 5e 28 57 68 65 6e 20 49 4e 53 45  ls.  ^(When INSE
16ee0 52 54 20 4f 52 20 52 45 50 4c 41 43 45 0a 2a 2a  RT OR REPLACE.**
16ef0 20 65 6e 63 6f 75 6e 74 65 72 73 20 61 20 63 6f   encounters a co
16f00 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69  nstraint violati
16f10 6f 6e 2c 20 69 74 20 64 6f 65 73 20 6e 6f 74 20  on, it does not 
16f20 66 61 69 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e  fail.  The.** IN
16f30 53 45 52 54 20 63 6f 6e 74 69 6e 75 65 73 20 74  SERT continues t
16f40 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74  o completion aft
16f50 65 72 20 64 65 6c 65 74 69 6e 67 20 72 6f 77 73  er deleting rows
16f60 20 74 68 61 74 20 63 61 75 73 65 64 0a 2a 2a 20   that caused.** 
16f70 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 70  the constraint p
16f80 72 6f 62 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54  roblem so INSERT
16f90 20 4f 52 20 52 45 50 4c 41 43 45 20 77 69 6c 6c   OR REPLACE will
16fa0 20 61 6c 77 61 79 73 20 63 68 61 6e 67 65 0a 2a   always change.*
16fb0 2a 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  * the return val
16fc0 75 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72  ue of this inter
16fd0 66 61 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46  face.)^.**.** ^F
16fe0 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65 73 20  or the purposes 
16ff0 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c  of this routine,
17000 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 69 73 20   an [INSERT] is 
17010 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 0a 2a 2a  considered to.**
17020 20 62 65 20 73 75 63 63 65 73 73 66 75 6c 20 65   be successful e
17030 76 65 6e 20 69 66 20 69 74 20 69 73 20 73 75 62  ven if it is sub
17040 73 65 71 75 65 6e 74 6c 79 20 72 6f 6c 6c 65 64  sequently rolled
17050 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 69   back..**.** Thi
17060 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 63  s function is ac
17070 63 65 73 73 69 62 6c 65 20 74 6f 20 53 51 4c 20  cessible to SQL 
17080 73 74 61 74 65 6d 65 6e 74 73 20 76 69 61 20 74  statements via t
17090 68 65 0a 2a 2a 20 5b 6c 61 73 74 5f 69 6e 73 65  he.** [last_inse
170a0 72 74 5f 72 6f 77 69 64 28 29 20 53 51 4c 20 66  rt_rowid() SQL f
170b0 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20  unction]..**.** 
170c0 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68  If a separate th
170d0 72 65 61 64 20 70 65 72 66 6f 72 6d 73 20 61 20  read performs a 
170e0 6e 65 77 20 5b 49 4e 53 45 52 54 5d 20 6f 6e 20  new [INSERT] on 
170f0 74 68 65 20 73 61 6d 65 0a 2a 2a 20 64 61 74 61  the same.** data
17100 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
17110 77 68 69 6c 65 20 74 68 65 20 5b 73 71 6c 69 74  while the [sqlit
17120 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  e3_last_insert_r
17130 6f 77 69 64 28 29 5d 0a 2a 2a 20 66 75 6e 63 74  owid()].** funct
17140 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 20 61  ion is running a
17150 6e 64 20 74 68 75 73 20 63 68 61 6e 67 65 73 20  nd thus changes 
17160 74 68 65 20 6c 61 73 74 20 69 6e 73 65 72 74 20  the last insert 
17170 5b 72 6f 77 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e  [rowid],.** then
17180 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
17190 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
171a0 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
171b0 64 28 29 5d 20 69 73 0a 2a 2a 20 75 6e 70 72 65  d()] is.** unpre
171c0 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6d 69 67  dictable and mig
171d0 68 74 20 6e 6f 74 20 65 71 75 61 6c 20 65 69 74  ht not equal eit
171e0 68 65 72 20 74 68 65 20 6f 6c 64 20 6f 72 20 74  her the old or t
171f0 68 65 20 6e 65 77 0a 2a 2a 20 6c 61 73 74 20 69  he new.** last i
17200 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a  nsert [rowid]..*
17210 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c  /.SQLITE_API sql
17220 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
17230 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  e3_last_insert_r
17240 6f 77 69 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a  owid(sqlite3*);.
17250 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
17260 20 43 6f 75 6e 74 20 54 68 65 20 4e 75 6d 62 65   Count The Numbe
17270 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69  r Of Rows Modifi
17280 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66  ed.**.** ^This f
17290 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
172a0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 61  the number of da
172b0 74 61 62 61 73 65 20 72 6f 77 73 20 74 68 61 74  tabase rows that
172c0 20 77 65 72 65 20 63 68 61 6e 67 65 64 0a 2a 2a   were changed.**
172d0 20 6f 72 20 69 6e 73 65 72 74 65 64 20 6f 72 20   or inserted or 
172e0 64 65 6c 65 74 65 64 20 62 79 20 74 68 65 20 6d  deleted by the m
172f0 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d  ost recently com
17300 70 6c 65 74 65 64 20 53 51 4c 20 73 74 61 74 65  pleted SQL state
17310 6d 65 6e 74 0a 2a 2a 20 6f 6e 20 74 68 65 20 5b  ment.** on the [
17320 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
17330 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20 62  ion] specified b
17340 79 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  y the first para
17350 6d 65 74 65 72 2e 0a 2a 2a 20 5e 28 4f 6e 6c 79  meter..** ^(Only
17360 20 63 68 61 6e 67 65 73 20 74 68 61 74 20 61 72   changes that ar
17370 65 20 64 69 72 65 63 74 6c 79 20 73 70 65 63 69  e directly speci
17380 66 69 65 64 20 62 79 20 74 68 65 20 5b 49 4e 53  fied by the [INS
17390 45 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d 2c 0a  ERT], [UPDATE],.
173a0 2a 2a 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73  ** or [DELETE] s
173b0 74 61 74 65 6d 65 6e 74 20 61 72 65 20 63 6f 75  tatement are cou
173c0 6e 74 65 64 2e 20 20 41 75 78 69 6c 69 61 72 79  nted.  Auxiliary
173d0 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20   changes caused 
173e0 62 79 0a 2a 2a 20 74 72 69 67 67 65 72 73 20 6f  by.** triggers o
173f0 72 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61  r [foreign key a
17400 63 74 69 6f 6e 73 5d 20 61 72 65 20 6e 6f 74 20  ctions] are not 
17410 63 6f 75 6e 74 65 64 2e 29 5e 20 55 73 65 20 74  counted.)^ Use t
17420 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 74  he.** [sqlite3_t
17430 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20  otal_changes()] 
17440 66 75 6e 63 74 69 6f 6e 20 74 6f 20 66 69 6e 64  function to find
17450 20 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65   the total numbe
17460 72 20 6f 66 20 63 68 61 6e 67 65 73 0a 2a 2a 20  r of changes.** 
17470 69 6e 63 6c 75 64 69 6e 67 20 63 68 61 6e 67 65  including change
17480 73 20 63 61 75 73 65 64 20 62 79 20 74 72 69 67  s caused by trig
17490 67 65 72 73 20 61 6e 64 20 66 6f 72 65 69 67 6e  gers and foreign
174a0 20 6b 65 79 20 61 63 74 69 6f 6e 73 2e 0a 2a 2a   key actions..**
174b0 0a 2a 2a 20 5e 43 68 61 6e 67 65 73 20 74 6f 20  .** ^Changes to 
174c0 61 20 76 69 65 77 20 74 68 61 74 20 61 72 65 20  a view that are 
174d0 73 69 6d 75 6c 61 74 65 64 20 62 79 20 61 6e 20  simulated by an 
174e0 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67  [INSTEAD OF trig
174f0 67 65 72 5d 0a 2a 2a 20 61 72 65 20 6e 6f 74 20  ger].** are not 
17500 63 6f 75 6e 74 65 64 2e 20 20 4f 6e 6c 79 20 72  counted.  Only r
17510 65 61 6c 20 74 61 62 6c 65 20 63 68 61 6e 67 65  eal table change
17520 73 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 0a 2a  s are counted..*
17530 2a 0a 2a 2a 20 5e 28 41 20 22 72 6f 77 20 63 68  *.** ^(A "row ch
17540 61 6e 67 65 22 20 69 73 20 61 20 63 68 61 6e 67  ange" is a chang
17550 65 20 74 6f 20 61 20 73 69 6e 67 6c 65 20 72 6f  e to a single ro
17560 77 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 74 61  w of a single ta
17570 62 6c 65 0a 2a 2a 20 63 61 75 73 65 64 20 62 79  ble.** caused by
17580 20 61 6e 20 49 4e 53 45 52 54 2c 20 44 45 4c 45   an INSERT, DELE
17590 54 45 2c 20 6f 72 20 55 50 44 41 54 45 20 73 74  TE, or UPDATE st
175a0 61 74 65 6d 65 6e 74 2e 20 20 52 6f 77 73 20 74  atement.  Rows t
175b0 68 61 74 0a 2a 2a 20 61 72 65 20 63 68 61 6e 67  hat.** are chang
175c0 65 64 20 61 73 20 73 69 64 65 20 65 66 66 65 63  ed as side effec
175d0 74 73 20 6f 66 20 5b 52 45 50 4c 41 43 45 5d 20  ts of [REPLACE] 
175e0 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73 6f 6c  constraint resol
175f0 75 74 69 6f 6e 2c 0a 2a 2a 20 72 6f 6c 6c 62 61  ution,.** rollba
17600 63 6b 2c 20 41 42 4f 52 54 20 70 72 6f 63 65 73  ck, ABORT proces
17610 73 69 6e 67 2c 20 5b 44 52 4f 50 20 54 41 42 4c  sing, [DROP TABL
17620 45 5d 2c 20 6f 72 20 62 79 20 61 6e 79 20 6f 74  E], or by any ot
17630 68 65 72 0a 2a 2a 20 6d 65 63 68 61 6e 69 73 6d  her.** mechanism
17640 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61  s do not count a
17650 73 20 64 69 72 65 63 74 20 72 6f 77 20 63 68 61  s direct row cha
17660 6e 67 65 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20  nges.)^.**.** A 
17670 22 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74  "trigger context
17680 22 20 69 73 20 61 20 73 63 6f 70 65 20 6f 66 20  " is a scope of 
17690 65 78 65 63 75 74 69 6f 6e 20 74 68 61 74 20 62  execution that b
176a0 65 67 69 6e 73 20 61 6e 64 0a 2a 2a 20 65 6e 64  egins and.** end
176b0 73 20 77 69 74 68 20 74 68 65 20 73 63 72 69 70  s with the scrip
176c0 74 20 6f 66 20 61 20 5b 43 52 45 41 54 45 20 54  t of a [CREATE T
176d0 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 65 72  RIGGER | trigger
176e0 5d 2e 20 0a 2a 2a 20 4d 6f 73 74 20 53 51 4c 20  ]. .** Most SQL 
176f0 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 0a 2a  statements are.*
17700 2a 20 65 76 61 6c 75 61 74 65 64 20 6f 75 74 73  * evaluated outs
17710 69 64 65 20 6f 66 20 61 6e 79 20 74 72 69 67 67  ide of any trigg
17720 65 72 2e 20 20 54 68 69 73 20 69 73 20 74 68 65  er.  This is the
17730 20 22 74 6f 70 20 6c 65 76 65 6c 22 0a 2a 2a 20   "top level".** 
17740 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e  trigger context.
17750 20 20 49 66 20 61 20 74 72 69 67 67 65 72 20 66    If a trigger f
17760 69 72 65 73 20 66 72 6f 6d 20 74 68 65 20 74 6f  ires from the to
17770 70 20 6c 65 76 65 6c 2c 20 61 0a 2a 2a 20 6e 65  p level, a.** ne
17780 77 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78  w trigger contex
17790 74 20 69 73 20 65 6e 74 65 72 65 64 20 66 6f 72  t is entered for
177a0 20 74 68 65 20 64 75 72 61 74 69 6f 6e 20 6f 66   the duration of
177b0 20 74 68 61 74 20 6f 6e 65 0a 2a 2a 20 74 72 69   that one.** tri
177c0 67 67 65 72 2e 20 20 53 75 62 74 72 69 67 67 65  gger.  Subtrigge
177d0 72 73 20 63 72 65 61 74 65 20 73 75 62 63 6f 6e  rs create subcon
177e0 74 65 78 74 73 20 66 6f 72 20 74 68 65 69 72 20  texts for their 
177f0 64 75 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  duration..**.** 
17800 5e 43 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65  ^Calling [sqlite
17810 33 5f 65 78 65 63 28 29 5d 20 6f 72 20 5b 73 71  3_exec()] or [sq
17820 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65  lite3_step()] re
17830 63 75 72 73 69 76 65 6c 79 20 64 6f 65 73 0a 2a  cursively does.*
17840 2a 20 6e 6f 74 20 63 72 65 61 74 65 20 61 20 6e  * not create a n
17850 65 77 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65  ew trigger conte
17860 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  xt..**.** ^This 
17870 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
17880 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64   the number of d
17890 69 72 65 63 74 20 72 6f 77 20 63 68 61 6e 67 65  irect row change
178a0 73 20 69 6e 20 74 68 65 0a 2a 2a 20 6d 6f 73 74  s in the.** most
178b0 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c 20   recent INSERT, 
178c0 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54  UPDATE, or DELET
178d0 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68  E statement with
178e0 69 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 74  in the same.** t
178f0 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a  rigger context..
17900 2a 2a 0a 2a 2a 20 5e 54 68 75 73 2c 20 77 68 65  **.** ^Thus, whe
17910 6e 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  n called from th
17920 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20 74 68 69  e top level, thi
17930 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  s function retur
17940 6e 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72  ns the.** number
17950 20 6f 66 20 63 68 61 6e 67 65 73 20 69 6e 20 74   of changes in t
17960 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 49  he most recent I
17970 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f  NSERT, UPDATE, o
17980 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74  r DELETE.** that
17990 20 61 6c 73 6f 20 6f 63 63 75 72 72 65 64 20 61   also occurred a
179a0 74 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2e  t the top level.
179b0 20 20 5e 28 57 69 74 68 69 6e 20 74 68 65 20 62    ^(Within the b
179c0 6f 64 79 20 6f 66 20 61 20 74 72 69 67 67 65 72  ody of a trigger
179d0 2c 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33  ,.** the sqlite3
179e0 5f 63 68 61 6e 67 65 73 28 29 20 69 6e 74 65 72  _changes() inter
179f0 66 61 63 65 20 63 61 6e 20 62 65 20 63 61 6c 6c  face can be call
17a00 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e  ed to find the n
17a10 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 6e  umber of.** chan
17a20 67 65 73 20 69 6e 20 74 68 65 20 6d 6f 73 74 20  ges in the most 
17a30 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74  recently complet
17a40 65 64 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  ed INSERT, UPDAT
17a50 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20  E, or DELETE.** 
17a60 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e  statement within
17a70 20 74 68 65 20 62 6f 64 79 20 6f 66 20 74 68 65   the body of the
17a80 20 73 61 6d 65 20 74 72 69 67 67 65 72 2e 0a 2a   same trigger..*
17a90 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20 6e  * However, the n
17aa0 75 6d 62 65 72 20 72 65 74 75 72 6e 65 64 20 64  umber returned d
17ab0 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20  oes not include 
17ac0 63 68 61 6e 67 65 73 0a 2a 2a 20 63 61 75 73 65  changes.** cause
17ad0 64 20 62 79 20 73 75 62 74 72 69 67 67 65 72 73  d by subtriggers
17ae0 20 73 69 6e 63 65 20 74 68 6f 73 65 20 68 61 76   since those hav
17af0 65 20 74 68 65 69 72 20 6f 77 6e 20 63 6f 6e 74  e their own cont
17b00 65 78 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65  ext.)^.**.** See
17b10 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74   also the [sqlit
17b20 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
17b30 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 74  ()] interface, t
17b40 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61  he.** [count_cha
17b50 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e  nges pragma], an
17b60 64 20 74 68 65 20 5b 63 68 61 6e 67 65 73 28 29  d the [changes()
17b70 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a   SQL function]..
17b80 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72  **.** If a separ
17b90 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73  ate thread makes
17ba0 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20   changes on the 
17bb0 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f  same database co
17bc0 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c  nnection.** whil
17bd0 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  e [sqlite3_chang
17be0 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67  es()] is running
17bf0 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20   then the value 
17c00 72 65 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20 75  returned.** is u
17c10 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64  npredictable and
17c20 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e   not meaningful.
17c30 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
17c40 6e 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  nt sqlite3_chang
17c50 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  es(sqlite3*);../
17c60 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
17c70 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52  otal Number Of R
17c80 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a  ows Modified.**.
17c90 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f  ** ^This functio
17ca0 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  n returns the nu
17cb0 6d 62 65 72 20 6f 66 20 72 6f 77 20 63 68 61 6e  mber of row chan
17cc0 67 65 73 20 63 61 75 73 65 64 20 62 79 20 5b 49  ges caused by [I
17cd0 4e 53 45 52 54 5d 2c 0a 2a 2a 20 5b 55 50 44 41  NSERT],.** [UPDA
17ce0 54 45 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20  TE] or [DELETE] 
17cf0 73 74 61 74 65 6d 65 6e 74 73 20 73 69 6e 63 65  statements since
17d00 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
17d10 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 61 73 20 6f  onnection] was o
17d20 70 65 6e 65 64 2e 0a 2a 2a 20 5e 28 54 68 65 20  pened..** ^(The 
17d30 63 6f 75 6e 74 20 72 65 74 75 72 6e 65 64 20 62  count returned b
17d40 79 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f  y sqlite3_total_
17d50 63 68 61 6e 67 65 73 28 29 20 69 6e 63 6c 75 64  changes() includ
17d60 65 73 20 61 6c 6c 20 63 68 61 6e 67 65 73 0a 2a  es all changes.*
17d70 2a 20 66 72 6f 6d 20 61 6c 6c 20 5b 43 52 45 41  * from all [CREA
17d80 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69  TE TRIGGER | tri
17d90 67 67 65 72 5d 20 63 6f 6e 74 65 78 74 73 20 61  gger] contexts a
17da0 6e 64 20 63 68 61 6e 67 65 73 20 6d 61 64 65 20  nd changes made 
17db0 62 79 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b  by.** [foreign k
17dc0 65 79 20 61 63 74 69 6f 6e 73 5d 2e 20 48 6f 77  ey actions]. How
17dd0 65 76 65 72 2c 0a 2a 2a 20 74 68 65 20 63 6f 75  ever,.** the cou
17de0 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c  nt does not incl
17df0 75 64 65 20 63 68 61 6e 67 65 73 20 75 73 65 64  ude changes used
17e00 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b 52   to implement [R
17e10 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61 69  EPLACE] constrai
17e20 6e 74 73 2c 0a 2a 2a 20 64 6f 20 72 6f 6c 6c 62  nts,.** do rollb
17e30 61 63 6b 73 20 6f 72 20 41 42 4f 52 54 20 70 72  acks or ABORT pr
17e40 6f 63 65 73 73 69 6e 67 2c 20 6f 72 20 5b 44 52  ocessing, or [DR
17e50 4f 50 20 54 41 42 4c 45 5d 20 70 72 6f 63 65 73  OP TABLE] proces
17e60 73 69 6e 67 2e 20 20 54 68 65 0a 2a 2a 20 63 6f  sing.  The.** co
17e70 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63  unt does not inc
17e80 6c 75 64 65 20 72 6f 77 73 20 6f 66 20 76 69 65  lude rows of vie
17e90 77 73 20 74 68 61 74 20 66 69 72 65 20 61 6e 20  ws that fire an 
17ea0 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67  [INSTEAD OF trig
17eb0 67 65 72 5d 2c 0a 2a 2a 20 74 68 6f 75 67 68 20  ger],.** though 
17ec0 69 66 20 74 68 65 20 49 4e 53 54 45 41 44 20 4f  if the INSTEAD O
17ed0 46 20 74 72 69 67 67 65 72 20 6d 61 6b 65 73 20  F trigger makes 
17ee0 63 68 61 6e 67 65 73 20 6f 66 20 69 74 73 20 6f  changes of its o
17ef0 77 6e 2c 20 74 68 6f 73 65 20 63 68 61 6e 67 65  wn, those change
17f00 73 20 0a 2a 2a 20 61 72 65 20 63 6f 75 6e 74 65  s .** are counte
17f10 64 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  d.)^.** ^The sql
17f20 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
17f30 65 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 6f  es() function co
17f40 75 6e 74 73 20 74 68 65 20 63 68 61 6e 67 65 73  unts the changes
17f50 20 61 73 20 73 6f 6f 6e 20 61 73 0a 2a 2a 20 74   as soon as.** t
17f60 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61  he statement tha
17f70 74 20 6d 61 6b 65 73 20 74 68 65 6d 20 69 73 20  t makes them is 
17f80 63 6f 6d 70 6c 65 74 65 64 20 28 77 68 65 6e 20  completed (when 
17f90 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61  the statement ha
17fa0 6e 64 6c 65 0a 2a 2a 20 69 73 20 70 61 73 73 65  ndle.** is passe
17fb0 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  d to [sqlite3_re
17fc0 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  set()] or [sqlit
17fd0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 29 2e  e3_finalize()]).
17fe0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20  .**.** See also 
17ff0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61  the [sqlite3_cha
18000 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63  nges()] interfac
18010 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74  e, the.** [count
18020 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d  _changes pragma]
18030 2c 20 61 6e 64 20 74 68 65 20 5b 74 6f 74 61 6c  , and the [total
18040 5f 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66  _changes() SQL f
18050 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20  unction]..**.** 
18060 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68  If a separate th
18070 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67  read makes chang
18080 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64  es on the same d
18090 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
180a0 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c  on.** while [sql
180b0 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
180c0 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67  es()] is running
180d0 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 0a   then the value.
180e0 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 73 20 75  ** returned is u
180f0 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64  npredictable and
18100 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e   not meaningful.
18110 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
18120 6e 74 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  nt sqlite3_total
18130 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33  _changes(sqlite3
18140 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
18150 52 45 46 3a 20 49 6e 74 65 72 72 75 70 74 20 41  REF: Interrupt A
18160 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 75   Long-Running Qu
18170 65 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  ery.**.** ^This 
18180 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20  function causes 
18190 61 6e 79 20 70 65 6e 64 69 6e 67 20 64 61 74 61  any pending data
181a0 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 74  base operation t
181b0 6f 20 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72  o abort and.** r
181c0 65 74 75 72 6e 20 61 74 20 69 74 73 20 65 61 72  eturn at its ear
181d0 6c 69 65 73 74 20 6f 70 70 6f 72 74 75 6e 69 74  liest opportunit
181e0 79 2e 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  y. This routine 
181f0 69 73 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20  is typically.** 
18200 63 61 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e  called in respon
18210 73 65 20 74 6f 20 61 20 75 73 65 72 20 61 63 74  se to a user act
18220 69 6f 6e 20 73 75 63 68 20 61 73 20 70 72 65 73  ion such as pres
18230 73 69 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a 2a  sing "Cancel".**
18240 20 6f 72 20 43 74 72 6c 2d 43 20 77 68 65 72 65   or Ctrl-C where
18250 20 74 68 65 20 75 73 65 72 20 77 61 6e 74 73 20   the user wants 
18260 61 20 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70 65  a long query ope
18270 72 61 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a  ration to halt.*
18280 2a 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a  * immediately..*
18290 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 73 61 66 65  *.** ^It is safe
182a0 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f   to call this ro
182b0 75 74 69 6e 65 20 66 72 6f 6d 20 61 20 74 68 72  utine from a thr
182c0 65 61 64 20 64 69 66 66 65 72 65 6e 74 20 66 72  ead different fr
182d0 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 72 65 61 64  om the.** thread
182e0 20 74 68 61 74 20 69 73 20 63 75 72 72 65 6e 74   that is current
182f0 6c 79 20 72 75 6e 6e 69 6e 67 20 74 68 65 20 64  ly running the d
18300 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f  atabase operatio
18310 6e 2e 20 20 42 75 74 20 69 74 0a 2a 2a 20 69 73  n.  But it.** is
18320 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 63 61 6c   not safe to cal
18330 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  l this routine w
18340 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 20  ith a [database 
18350 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74  connection] that
18360 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 64 20 6f 72  .** is closed or
18370 20 6d 69 67 68 74 20 63 6c 6f 73 65 20 62 65 66   might close bef
18380 6f 72 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  ore sqlite3_inte
18390 72 72 75 70 74 28 29 20 72 65 74 75 72 6e 73 2e  rrupt() returns.
183a0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 53 51  .**.** ^If an SQ
183b0 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 76  L operation is v
183c0 65 72 79 20 6e 65 61 72 6c 79 20 66 69 6e 69 73  ery nearly finis
183d0 68 65 64 20 61 74 20 74 68 65 20 74 69 6d 65 20  hed at the time 
183e0 77 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  when.** sqlite3_
183f0 69 6e 74 65 72 72 75 70 74 28 29 20 69 73 20 63  interrupt() is c
18400 61 6c 6c 65 64 2c 20 74 68 65 6e 20 69 74 20 6d  alled, then it m
18410 69 67 68 74 20 6e 6f 74 20 68 61 76 65 20 61 6e  ight not have an
18420 20 6f 70 70 6f 72 74 75 6e 69 74 79 0a 2a 2a 20   opportunity.** 
18430 74 6f 20 62 65 20 69 6e 74 65 72 72 75 70 74 65  to be interrupte
18440 64 20 61 6e 64 20 6d 69 67 68 74 20 63 6f 6e 74  d and might cont
18450 69 6e 75 65 20 74 6f 20 63 6f 6d 70 6c 65 74 69  inue to completi
18460 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 53 51  on..**.** ^An SQ
18470 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74  L operation that
18480 20 69 73 20 69 6e 74 65 72 72 75 70 74 65 64 20   is interrupted 
18490 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c  will return [SQL
184a0 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a  ITE_INTERRUPT]..
184b0 2a 2a 20 5e 49 66 20 74 68 65 20 69 6e 74 65 72  ** ^If the inter
184c0 72 75 70 74 65 64 20 53 51 4c 20 6f 70 65 72 61  rupted SQL opera
184d0 74 69 6f 6e 20 69 73 20 61 6e 20 49 4e 53 45 52  tion is an INSER
184e0 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45  T, UPDATE, or DE
184f0 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 69 73 20  LETE.** that is 
18500 69 6e 73 69 64 65 20 61 6e 20 65 78 70 6c 69 63  inside an explic
18510 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20  it transaction, 
18520 74 68 65 6e 20 74 68 65 20 65 6e 74 69 72 65 20  then the entire 
18530 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20 77  transaction.** w
18540 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62 61  ill be rolled ba
18550 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ck automatically
18560 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
18570 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44  ite3_interrupt(D
18580 29 20 63 61 6c 6c 20 69 73 20 69 6e 20 65 66 66  ) call is in eff
18590 65 63 74 20 75 6e 74 69 6c 20 61 6c 6c 20 63 75  ect until all cu
185a0 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 0a  rrently running.
185b0 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
185c0 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63  s on [database c
185d0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 63 6f 6d  onnection] D com
185e0 70 6c 65 74 65 2e 20 20 5e 41 6e 79 20 6e 65 77  plete.  ^Any new
185f0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
18600 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72  ** that are star
18610 74 65 64 20 61 66 74 65 72 20 74 68 65 20 73 71  ted after the sq
18620 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
18630 29 20 63 61 6c 6c 20 61 6e 64 20 62 65 66 6f 72  ) call and befor
18640 65 20 74 68 65 20 0a 2a 2a 20 72 75 6e 6e 69 6e  e the .** runnin
18650 67 20 73 74 61 74 65 6d 65 6e 74 73 20 72 65 61  g statements rea
18660 63 68 65 73 20 7a 65 72 6f 20 61 72 65 20 69 6e  ches zero are in
18670 74 65 72 72 75 70 74 65 64 20 61 73 20 69 66 20  terrupted as if 
18680 74 68 65 79 20 68 61 64 20 62 65 65 6e 0a 2a 2a  they had been.**
18690 20 72 75 6e 6e 69 6e 67 20 70 72 69 6f 72 20 74   running prior t
186a0 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  o the sqlite3_in
186b0 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 2e 20  terrupt() call. 
186c0 20 5e 4e 65 77 20 53 51 4c 20 73 74 61 74 65 6d   ^New SQL statem
186d0 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65  ents.** that are
186e0 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74   started after t
186f0 68 65 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65  he running state
18700 6d 65 6e 74 20 63 6f 75 6e 74 20 72 65 61 63 68  ment count reach
18710 65 73 20 7a 65 72 6f 20 61 72 65 0a 2a 2a 20 6e  es zero are.** n
18720 6f 74 20 65 66 66 65 63 74 65 64 20 62 79 20 74  ot effected by t
18730 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  he sqlite3_inter
18740 72 75 70 74 28 29 2e 0a 2a 2a 20 5e 41 20 63 61  rupt()..** ^A ca
18750 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e  ll to sqlite3_in
18760 74 65 72 72 75 70 74 28 44 29 20 74 68 61 74 20  terrupt(D) that 
18770 6f 63 63 75 72 73 20 77 68 65 6e 20 74 68 65 72  occurs when ther
18780 65 20 61 72 65 20 6e 6f 20 72 75 6e 6e 69 6e 67  e are no running
18790 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
187a0 74 73 20 69 73 20 61 20 6e 6f 2d 6f 70 20 61 6e  ts is a no-op an
187b0 64 20 68 61 73 20 6e 6f 20 65 66 66 65 63 74 20  d has no effect 
187c0 6f 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  on SQL statement
187d0 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74  s.** that are st
187e0 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20  arted after the 
187f0 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
18800 74 28 29 20 63 61 6c 6c 20 72 65 74 75 72 6e 73  t() call returns
18810 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 64  ..**.** If the d
18820 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
18830 6f 6e 20 63 6c 6f 73 65 73 20 77 68 69 6c 65 20  on closes while 
18840 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75  [sqlite3_interru
18850 70 74 28 29 5d 0a 2a 2a 20 69 73 20 72 75 6e 6e  pt()].** is runn
18860 69 6e 67 20 74 68 65 6e 20 62 61 64 20 74 68 69  ing then bad thi
18870 6e 67 73 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20  ngs will likely 
18880 68 61 70 70 65 6e 2e 0a 2a 2f 0a 53 51 4c 49 54  happen..*/.SQLIT
18890 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74  E_API void sqlit
188a0 65 33 5f 69 6e 74 65 72 72 75 70 74 28 73 71 6c  e3_interrupt(sql
188b0 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
188c0 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69  API3REF: Determi
188d0 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61  ne If An SQL Sta
188e0 74 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65  tement Is Comple
188f0 74 65 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  te.**.** These r
18900 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 66  outines are usef
18910 75 6c 20 64 75 72 69 6e 67 20 63 6f 6d 6d 61 6e  ul during comman
18920 64 2d 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f 20  d-line input to 
18930 64 65 74 65 72 6d 69 6e 65 20 69 66 20 74 68 65  determine if the
18940 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 65 6e  .** currently en
18950 74 65 72 65 64 20 74 65 78 74 20 73 65 65 6d 73  tered text seems
18960 20 74 6f 20 66 6f 72 6d 20 61 20 63 6f 6d 70 6c   to form a compl
18970 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ete SQL statemen
18980 74 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69 74  t or.** if addit
18990 69 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73 20 6e  ional input is n
189a0 65 65 64 65 64 20 62 65 66 6f 72 65 20 73 65 6e  eeded before sen
189b0 64 69 6e 67 20 74 68 65 20 74 65 78 74 20 69 6e  ding the text in
189c0 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72  to.** SQLite for
189d0 20 70 61 72 73 69 6e 67 2e 20 20 5e 54 68 65 73   parsing.  ^Thes
189e0 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  e routines retur
189f0 6e 20 31 20 69 66 20 74 68 65 20 69 6e 70 75 74  n 1 if the input
18a00 20 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61   string.** appea
18a10 72 73 20 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c  rs to be a compl
18a20 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ete SQL statemen
18a30 74 2e 20 20 5e 41 20 73 74 61 74 65 6d 65 6e 74  t.  ^A statement
18a40 20 69 73 20 6a 75 64 67 65 64 20 74 6f 20 62 65   is judged to be
18a50 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66 20  .** complete if 
18a60 69 74 20 65 6e 64 73 20 77 69 74 68 20 61 20 73  it ends with a s
18a70 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61  emicolon token a
18a80 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 72 65 66  nd is not a pref
18a90 69 78 20 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d  ix of a.** well-
18aa0 66 6f 72 6d 65 64 20 43 52 45 41 54 45 20 54 52  formed CREATE TR
18ab0 49 47 47 45 52 20 73 74 61 74 65 6d 65 6e 74 2e  IGGER statement.
18ac0 20 20 5e 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 68    ^Semicolons th
18ad0 61 74 20 61 72 65 20 65 6d 62 65 64 64 65 64 20  at are embedded 
18ae0 77 69 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e 67  within.** string
18af0 20 6c 69 74 65 72 61 6c 73 20 6f 72 20 71 75 6f   literals or quo
18b00 74 65 64 20 69 64 65 6e 74 69 66 69 65 72 20 6e  ted identifier n
18b10 61 6d 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 73  ames or comments
18b20 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65   are not.** inde
18b30 70 65 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20 28  pendent tokens (
18b40 74 68 65 79 20 61 72 65 20 70 61 72 74 20 6f 66  they are part of
18b50 20 74 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77 68   the token in wh
18b60 69 63 68 20 74 68 65 79 20 61 72 65 0a 2a 2a 20  ich they are.** 
18b70 65 6d 62 65 64 64 65 64 29 20 61 6e 64 20 74 68  embedded) and th
18b80 75 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20  us do not count 
18b90 61 73 20 61 20 73 74 61 74 65 6d 65 6e 74 20 74  as a statement t
18ba0 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 57 68 69  erminator.  ^Whi
18bb0 74 65 73 70 61 63 65 0a 2a 2a 20 61 6e 64 20 63  tespace.** and c
18bc0 6f 6d 6d 65 6e 74 73 20 74 68 61 74 20 66 6f 6c  omments that fol
18bd0 6c 6f 77 20 74 68 65 20 66 69 6e 61 6c 20 73 65  low the final se
18be0 6d 69 63 6f 6c 6f 6e 20 61 72 65 20 69 67 6e 6f  micolon are igno
18bf0 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  red..**.** ^Thes
18c00 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  e routines retur
18c10 6e 20 30 20 69 66 20 74 68 65 20 73 74 61 74 65  n 0 if the state
18c20 6d 65 6e 74 20 69 73 20 69 6e 63 6f 6d 70 6c 65  ment is incomple
18c30 74 65 2e 20 20 5e 49 66 20 61 0a 2a 2a 20 6d 65  te.  ^If a.** me
18c40 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
18c50 66 61 69 6c 73 2c 20 74 68 65 6e 20 53 51 4c 49  fails, then SQLI
18c60 54 45 5f 4e 4f 4d 45 4d 20 69 73 20 72 65 74 75  TE_NOMEM is retu
18c70 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  rned..**.** ^The
18c80 73 65 20 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e  se routines do n
18c90 6f 74 20 70 61 72 73 65 20 74 68 65 20 53 51 4c  ot parse the SQL
18ca0 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 75 73   statements thus
18cb0 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74  .** will not det
18cc0 65 63 74 20 73 79 6e 74 61 63 74 69 63 61 6c 6c  ect syntacticall
18cd0 79 20 69 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e  y incorrect SQL.
18ce0 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53 51 4c 69  .**.** ^(If SQLi
18cf0 74 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20  te has not been 
18d00 69 6e 69 74 69 61 6c 69 7a 65 64 20 75 73 69 6e  initialized usin
18d10 67 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  g [sqlite3_initi
18d20 61 6c 69 7a 65 28 29 5d 20 70 72 69 6f 72 20 0a  alize()] prior .
18d30 2a 2a 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 20 73  ** to invoking s
18d40 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
18d50 36 28 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33  6() then sqlite3
18d60 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
18d70 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f   invoked.** auto
18d80 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c  matically by sql
18d90 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
18da0 29 2e 20 20 49 66 20 74 68 61 74 20 69 6e 69 74  ).  If that init
18db0 69 61 6c 69 7a 61 74 69 6f 6e 20 66 61 69 6c 73  ialization fails
18dc0 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 65  ,.** then the re
18dd0 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20  turn value from 
18de0 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
18df0 31 36 28 29 20 77 69 6c 6c 20 62 65 20 6e 6f 6e  16() will be non
18e00 2d 7a 65 72 6f 0a 2a 2a 20 72 65 67 61 72 64 6c  -zero.** regardl
18e10 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f  ess of whether o
18e20 72 20 6e 6f 74 20 74 68 65 20 69 6e 70 75 74 20  r not the input 
18e30 53 51 4c 20 69 73 20 63 6f 6d 70 6c 65 74 65 2e  SQL is complete.
18e40 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70  )^.**.** The inp
18e50 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ut to [sqlite3_c
18e60 6f 6d 70 6c 65 74 65 28 29 5d 20 6d 75 73 74 20  omplete()] must 
18e70 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  be a zero-termin
18e80 61 74 65 64 0a 2a 2a 20 55 54 46 2d 38 20 73 74  ated.** UTF-8 st
18e90 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ring..**.** The 
18ea0 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65  input to [sqlite
18eb0 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20  3_complete16()] 
18ec0 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74  must be a zero-t
18ed0 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46  erminated.** UTF
18ee0 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61  -16 string in na
18ef0 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e  tive byte order.
18f00 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
18f10 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  nt sqlite3_compl
18f20 65 74 65 28 63 6f 6e 73 74 20 63 68 61 72 20 2a  ete(const char *
18f30 73 71 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  sql);.SQLITE_API
18f40 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d   int sqlite3_com
18f50 70 6c 65 74 65 31 36 28 63 6f 6e 73 74 20 76 6f  plete16(const vo
18f60 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a  id *sql);../*.**
18f70 20 43 41 50 49 33 52 45 46 3a 20 52 65 67 69 73   CAPI3REF: Regis
18f80 74 65 72 20 41 20 43 61 6c 6c 62 61 63 6b 20 54  ter A Callback T
18f90 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f  o Handle SQLITE_
18fa0 42 55 53 59 20 45 72 72 6f 72 73 0a 2a 2a 0a 2a  BUSY Errors.**.*
18fb0 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20  * ^This routine 
18fc0 73 65 74 73 20 61 20 63 61 6c 6c 62 61 63 6b 20  sets a callback 
18fd0 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 6d 69  function that mi
18fe0 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77  ght be invoked w
18ff0 68 65 6e 65 76 65 72 0a 2a 2a 20 61 6e 20 61 74  henever.** an at
19000 74 65 6d 70 74 20 69 73 20 6d 61 64 65 20 74 6f  tempt is made to
19010 20 6f 70 65 6e 20 61 20 64 61 74 61 62 61 73 65   open a database
19020 20 74 61 62 6c 65 20 74 68 61 74 20 61 6e 6f 74   table that anot
19030 68 65 72 20 74 68 72 65 61 64 0a 2a 2a 20 6f 72  her thread.** or
19040 20 70 72 6f 63 65 73 73 20 68 61 73 20 6c 6f 63   process has loc
19050 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ked..**.** ^If t
19060 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  he busy callback
19070 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b   is NULL, then [
19080 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20  SQLITE_BUSY] or 
19090 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c  [SQLITE_IOERR_BL
190a0 4f 43 4b 45 44 5d 0a 2a 2a 20 69 73 20 72 65 74  OCKED].** is ret
190b0 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c  urned immediatel
190c0 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 72  y upon encounter
190d0 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e 20 20 5e  ing the lock.  ^
190e0 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c  If the busy call
190f0 62 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e  back.** is not N
19100 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 63 61  ULL, then the ca
19110 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 62 65 20  llback might be 
19120 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 77 6f  invoked with two
19130 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a   arguments..**.*
19140 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67  * ^The first arg
19150 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 62 75 73  ument to the bus
19160 79 20 68 61 6e 64 6c 65 72 20 69 73 20 61 20 63  y handler is a c
19170 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64 2a  opy of the void*
19180 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 0a 2a   pointer which.*
19190 2a 20 69 73 20 74 68 65 20 74 68 69 72 64 20 61  * is the third a
191a0 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
191b0 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28  e3_busy_handler(
191c0 29 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  ).  ^The second 
191d0 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74  argument to.** t
191e0 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  he busy handler 
191f0 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20  callback is the 
19200 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20  number of times 
19210 74 68 61 74 20 74 68 65 20 62 75 73 79 20 68 61  that the busy ha
19220 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20 62 65 65  ndler has.** bee
19230 6e 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 74 68  n invoked for th
19240 69 73 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74  is locking event
19250 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 62 75  .  ^If the.** bu
19260 73 79 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  sy callback retu
19270 72 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61  rns 0, then no a
19280 64 64 69 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70  dditional attemp
19290 74 73 20 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a  ts are made to.*
192a0 2a 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74  * access the dat
192b0 61 62 61 73 65 20 61 6e 64 20 5b 53 51 4c 49 54  abase and [SQLIT
192c0 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49  E_BUSY] or [SQLI
192d0 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
192e0 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  ] is returned..*
192f0 2a 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61  * ^If the callba
19300 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a  ck returns non-z
19310 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68 65  ero, then anothe
19320 72 20 61 74 74 65 6d 70 74 0a 2a 2a 20 69 73 20  r attempt.** is 
19330 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20 74 68 65  made to open the
19340 20 64 61 74 61 62 61 73 65 20 66 6f 72 20 72 65   database for re
19350 61 64 69 6e 67 20 61 6e 64 20 74 68 65 20 63 79  ading and the cy
19360 63 6c 65 20 72 65 70 65 61 74 73 2e 0a 2a 2a 0a  cle repeats..**.
19370 2a 2a 20 54 68 65 20 70 72 65 73 65 6e 63 65 20  ** The presence 
19380 6f 66 20 61 20 62 75 73 79 20 68 61 6e 64 6c 65  of a busy handle
19390 72 20 64 6f 65 73 20 6e 6f 74 20 67 75 61 72 61  r does not guara
193a0 6e 74 65 65 20 74 68 61 74 20 69 74 20 77 69 6c  ntee that it wil
193b0 6c 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20  l be invoked.** 
193c0 77 68 65 6e 20 74 68 65 72 65 20 69 73 20 6c 6f  when there is lo
193d0 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20 5e  ck contention. ^
193e0 49 66 20 53 51 4c 69 74 65 20 64 65 74 65 72 6d  If SQLite determ
193f0 69 6e 65 73 20 74 68 61 74 20 69 6e 76 6f 6b 69  ines that invoki
19400 6e 67 20 74 68 65 20 62 75 73 79 0a 2a 2a 20 68  ng the busy.** h
19410 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20 72 65 73  andler could res
19420 75 6c 74 20 69 6e 20 61 20 64 65 61 64 6c 6f 63  ult in a deadloc
19430 6b 2c 20 69 74 20 77 69 6c 6c 20 67 6f 20 61 68  k, it will go ah
19440 65 61 64 20 61 6e 64 20 72 65 74 75 72 6e 20 5b  ead and return [
19450 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20  SQLITE_BUSY].** 
19460 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  or [SQLITE_IOERR
19470 5f 42 4c 4f 43 4b 45 44 5d 20 69 6e 73 74 65 61  _BLOCKED] instea
19480 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20 74 68  d of invoking th
19490 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a  e busy handler..
194a0 2a 2a 20 43 6f 6e 73 69 64 65 72 20 61 20 73 63  ** Consider a sc
194b0 65 6e 61 72 69 6f 20 77 68 65 72 65 20 6f 6e 65  enario where one
194c0 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64   process is hold
194d0 69 6e 67 20 61 20 72 65 61 64 20 6c 6f 63 6b 20  ing a read lock 
194e0 74 68 61 74 0a 2a 2a 20 69 74 20 69 73 20 74 72  that.** it is tr
194f0 79 69 6e 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20  ying to promote 
19500 74 6f 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f  to a reserved lo
19510 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f  ck and.** a seco
19520 6e 64 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f  nd process is ho
19530 6c 64 69 6e 67 20 61 20 72 65 73 65 72 76 65 64  lding a reserved
19540 20 6c 6f 63 6b 20 74 68 61 74 20 69 74 20 69 73   lock that it is
19550 20 74 72 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72   trying.** to pr
19560 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 65 78 63 6c  omote to an excl
19570 75 73 69 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65  usive lock.  The
19580 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 63   first process c
19590 61 6e 6e 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a  annot proceed.**
195a0 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62   because it is b
195b0 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 73 65  locked by the se
195c0 63 6f 6e 64 20 61 6e 64 20 74 68 65 20 73 65 63  cond and the sec
195d0 6f 6e 64 20 70 72 6f 63 65 73 73 20 63 61 6e 6e  ond process cann
195e0 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 64 20 62 65  ot.** proceed be
195f0 63 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63  cause it is bloc
19600 6b 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74  ked by the first
19610 2e 20 20 49 66 20 62 6f 74 68 20 70 72 6f 63 65  .  If both proce
19620 73 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74  sses.** invoke t
19630 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73  he busy handlers
19640 2c 20 6e 65 69 74 68 65 72 20 77 69 6c 6c 20 6d  , neither will m
19650 61 6b 65 20 61 6e 79 20 70 72 6f 67 72 65 73 73  ake any progress
19660 2e 20 20 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a  .  Therefore,.**
19670 20 53 51 4c 69 74 65 20 72 65 74 75 72 6e 73 20   SQLite returns 
19680 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f  [SQLITE_BUSY] fo
19690 72 20 74 68 65 20 66 69 72 73 74 20 70 72 6f 63  r the first proc
196a0 65 73 73 2c 20 68 6f 70 69 6e 67 20 74 68 61 74  ess, hoping that
196b0 20 74 68 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e   this.** will in
196c0 64 75 63 65 20 74 68 65 20 66 69 72 73 74 20 70  duce the first p
196d0 72 6f 63 65 73 73 20 74 6f 20 72 65 6c 65 61 73  rocess to releas
196e0 65 20 69 74 73 20 72 65 61 64 20 6c 6f 63 6b 20  e its read lock 
196f0 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65  and allow.** the
19700 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20   second process 
19710 74 6f 20 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a  to proceed..**.*
19720 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 62  * ^The default b
19730 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  usy callback is 
19740 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  NULL..**.** ^The
19750 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 65   [SQLITE_BUSY] e
19760 72 72 6f 72 20 69 73 20 63 6f 6e 76 65 72 74 65  rror is converte
19770 64 20 74 6f 20 5b 53 51 4c 49 54 45 5f 49 4f 45  d to [SQLITE_IOE
19780 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 77  RR_BLOCKED].** w
19790 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 69 6e  hen SQLite is in
197a0 20 74 68 65 20 6d 69 64 64 6c 65 20 6f 66 20 61   the middle of a
197b0 20 6c 61 72 67 65 20 74 72 61 6e 73 61 63 74 69   large transacti
197c0 6f 6e 20 77 68 65 72 65 20 61 6c 6c 20 74 68 65  on where all the
197d0 0a 2a 2a 20 63 68 61 6e 67 65 73 20 77 69 6c 6c  .** changes will
197e0 20 6e 6f 74 20 66 69 74 20 69 6e 74 6f 20 74 68   not fit into th
197f0 65 20 69 6e 2d 6d 65 6d 6f 72 79 20 63 61 63 68  e in-memory cach
19800 65 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 0a  e.  SQLite will.
19810 2a 2a 20 61 6c 72 65 61 64 79 20 68 6f 6c 64 20  ** already hold 
19820 61 20 52 45 53 45 52 56 45 44 20 6c 6f 63 6b 20  a RESERVED lock 
19830 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  on the database 
19840 66 69 6c 65 2c 20 62 75 74 20 69 74 20 6e 65 65  file, but it nee
19850 64 73 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65  ds.** to promote
19860 20 74 68 69 73 20 6c 6f 63 6b 20 74 6f 20 45 58   this lock to EX
19870 43 4c 55 53 49 56 45 20 73 6f 20 74 68 61 74 20  CLUSIVE so that 
19880 69 74 20 63 61 6e 20 73 70 69 6c 6c 20 63 61 63  it can spill cac
19890 68 65 0a 2a 2a 20 70 61 67 65 73 20 69 6e 74 6f  he.** pages into
198a0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
198b0 6c 65 20 77 69 74 68 6f 75 74 20 68 61 72 6d 20  le without harm 
198c0 74 6f 20 63 6f 6e 63 75 72 72 65 6e 74 0a 2a 2a  to concurrent.**
198d0 20 72 65 61 64 65 72 73 2e 20 20 5e 49 66 20 69   readers.  ^If i
198e0 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 70  t is unable to p
198f0 72 6f 6d 6f 74 65 20 74 68 65 20 6c 6f 63 6b 2c  romote the lock,
19900 20 74 68 65 6e 20 74 68 65 20 69 6e 2d 6d 65 6d   then the in-mem
19910 6f 72 79 0a 2a 2a 20 63 61 63 68 65 20 77 69 6c  ory.** cache wil
19920 6c 20 62 65 20 6c 65 66 74 20 69 6e 20 61 6e 20  l be left in an 
19930 69 6e 63 6f 6e 73 69 73 74 65 6e 74 20 73 74 61  inconsistent sta
19940 74 65 20 61 6e 64 20 73 6f 20 74 68 65 20 65 72  te and so the er
19950 72 6f 72 0a 2a 2a 20 63 6f 64 65 20 69 73 20 70  ror.** code is p
19960 72 6f 6d 6f 74 65 64 20 66 72 6f 6d 20 74 68 65  romoted from the
19970 20 72 65 6c 61 74 69 76 65 6c 79 20 62 65 6e 69   relatively beni
19980 67 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  gn [SQLITE_BUSY]
19990 20 74 6f 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20   to.** the more 
199a0 73 65 76 65 72 65 20 5b 53 51 4c 49 54 45 5f 49  severe [SQLITE_I
199b0 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 20 20  OERR_BLOCKED].  
199c0 5e 54 68 69 73 20 65 72 72 6f 72 20 63 6f 64 65  ^This error code
199d0 20 70 72 6f 6d 6f 74 69 6f 6e 0a 2a 2a 20 66 6f   promotion.** fo
199e0 72 63 65 73 20 61 6e 20 61 75 74 6f 6d 61 74 69  rces an automati
199f0 63 20 72 6f 6c 6c 62 61 63 6b 20 6f 66 20 74 68  c rollback of th
19a00 65 20 63 68 61 6e 67 65 73 2e 20 20 53 65 65 20  e changes.  See 
19a10 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22  the.** <a href="
19a20 2f 63 76 73 74 72 61 63 2f 77 69 6b 69 3f 70 3d  /cvstrac/wiki?p=
19a30 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77  CorruptionFollow
19a40 69 6e 67 42 75 73 79 45 72 72 6f 72 22 3e 0a 2a  ingBusyError">.*
19a50 2a 20 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c  * CorruptionFoll
19a60 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72 3c 2f  owingBusyError</
19a70 61 3e 20 77 69 6b 69 20 70 61 67 65 20 66 6f 72  a> wiki page for
19a80 20 61 20 64 69 73 63 75 73 73 69 6f 6e 20 6f 66   a discussion of
19a90 20 77 68 79 0a 2a 2a 20 74 68 69 73 20 69 73 20   why.** this is 
19aa0 69 6d 70 6f 72 74 61 6e 74 2e 0a 2a 2a 0a 2a 2a  important..**.**
19ab0 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c   ^(There can onl
19ac0 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75  y be a single bu
19ad0 73 79 20 68 61 6e 64 6c 65 72 20 64 65 66 69 6e  sy handler defin
19ae0 65 64 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 5b  ed for each.** [
19af0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
19b00 69 6f 6e 5d 2e 20 20 53 65 74 74 69 6e 67 20 61  ion].  Setting a
19b10 20 6e 65 77 20 62 75 73 79 20 68 61 6e 64 6c 65   new busy handle
19b20 72 20 63 6c 65 61 72 73 20 61 6e 79 0a 2a 2a 20  r clears any.** 
19b30 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74 20 68  previously set h
19b40 61 6e 64 6c 65 72 2e 29 5e 20 20 5e 4e 6f 74 65  andler.)^  ^Note
19b50 20 74 68 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73   that calling [s
19b60 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65  qlite3_busy_time
19b70 6f 75 74 28 29 5d 0a 2a 2a 20 77 69 6c 6c 20 61  out()].** will a
19b80 6c 73 6f 20 73 65 74 20 6f 72 20 63 6c 65 61 72  lso set or clear
19b90 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
19ba0 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62 75 73  r..**.** The bus
19bb0 79 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c  y callback shoul
19bc0 64 20 6e 6f 74 20 74 61 6b 65 20 61 6e 79 20 61  d not take any a
19bd0 63 74 69 6f 6e 73 20 77 68 69 63 68 20 6d 6f 64  ctions which mod
19be0 69 66 79 20 74 68 65 0a 2a 2a 20 64 61 74 61 62  ify the.** datab
19bf0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
19c00 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20  hat invoked the 
19c10 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 20 20 41  busy handler.  A
19c20 6e 79 20 73 75 63 68 20 61 63 74 69 6f 6e 73 0a  ny such actions.
19c30 2a 2a 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64  ** result in und
19c40 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e  efined behavior.
19c50 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75 73 79 20 68  .** .** A busy h
19c60 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20  andler must not 
19c70 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62 61  close the databa
19c80 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
19c90 20 6f 72 20 5b 70 72 65 70 61 72 65 64 20 73 74   or [prepared st
19ca0 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 6e  atement] that in
19cb0 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20 68  voked the busy h
19cc0 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 53 51 4c 49 54  andler..*/.SQLIT
19cd0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
19ce0 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 73  3_busy_handler(s
19cf0 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28  qlite3*, int(*)(
19d00 76 6f 69 64 2a 2c 69 6e 74 29 2c 20 76 6f 69 64  void*,int), void
19d10 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
19d20 52 45 46 3a 20 53 65 74 20 41 20 42 75 73 79 20  REF: Set A Busy 
19d30 54 69 6d 65 6f 75 74 0a 2a 2a 0a 2a 2a 20 5e 54  Timeout.**.** ^T
19d40 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73  his routine sets
19d50 20 61 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79   a [sqlite3_busy
19d60 5f 68 61 6e 64 6c 65 72 20 7c 20 62 75 73 79 20  _handler | busy 
19d70 68 61 6e 64 6c 65 72 5d 20 74 68 61 74 20 73 6c  handler] that sl
19d80 65 65 70 73 0a 2a 2a 20 66 6f 72 20 61 20 73 70  eeps.** for a sp
19d90 65 63 69 66 69 65 64 20 61 6d 6f 75 6e 74 20 6f  ecified amount o
19da0 66 20 74 69 6d 65 20 77 68 65 6e 20 61 20 74 61  f time when a ta
19db0 62 6c 65 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20  ble is locked.  
19dc0 5e 54 68 65 20 68 61 6e 64 6c 65 72 0a 2a 2a 20  ^The handler.** 
19dd0 77 69 6c 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69  will sleep multi
19de0 70 6c 65 20 74 69 6d 65 73 20 75 6e 74 69 6c 20  ple times until 
19df0 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69  at least "ms" mi
19e00 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c  lliseconds of sl
19e10 65 65 70 69 6e 67 0a 2a 2a 20 68 61 76 65 20 61  eeping.** have a
19e20 63 63 75 6d 75 6c 61 74 65 64 2e 20 20 5e 41 66  ccumulated.  ^Af
19e30 74 65 72 20 61 74 20 6c 65 61 73 74 20 22 6d 73  ter at least "ms
19e40 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f  " milliseconds o
19e50 66 20 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74  f sleeping,.** t
19e60 68 65 20 68 61 6e 64 6c 65 72 20 72 65 74 75 72  he handler retur
19e70 6e 73 20 30 20 77 68 69 63 68 20 63 61 75 73 65  ns 0 which cause
19e80 73 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  s [sqlite3_step(
19e90 29 5d 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20  )] to return.** 
19ea0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72  [SQLITE_BUSY] or
19eb0 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42   [SQLITE_IOERR_B
19ec0 4c 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  LOCKED]..**.** ^
19ed0 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75  Calling this rou
19ee0 74 69 6e 65 20 77 69 74 68 20 61 6e 20 61 72 67  tine with an arg
19ef0 75 6d 65 6e 74 20 6c 65 73 73 20 74 68 61 6e 20  ument less than 
19f00 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f  or equal to zero
19f10 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20 61 6c  .** turns off al
19f20 6c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2e  l busy handlers.
19f30 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63  .**.** ^(There c
19f40 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e  an only be a sin
19f50 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  gle busy handler
19f60 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61   for a particula
19f70 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  r.** [database c
19f80 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 79 20 61  onnection] any a
19f90 6e 79 20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e  ny given moment.
19fa0 20 20 49 66 20 61 6e 6f 74 68 65 72 20 62 75 73    If another bus
19fb0 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73  y handler.** was
19fc0 20 64 65 66 69 6e 65 64 20 20 28 75 73 69 6e 67   defined  (using
19fd0 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68   [sqlite3_busy_h
19fe0 61 6e 64 6c 65 72 28 29 5d 29 20 70 72 69 6f 72  andler()]) prior
19ff0 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74   to calling.** t
1a000 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 74 68 61  his routine, tha
1a010 74 20 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e  t other busy han
1a020 64 6c 65 72 20 69 73 20 63 6c 65 61 72 65 64 2e  dler is cleared.
1a030 29 5e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  )^.*/.SQLITE_API
1a040 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73   int sqlite3_bus
1a050 79 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 65  y_timeout(sqlite
1a060 33 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a  3*, int ms);../*
1a070 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
1a080 6e 76 65 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e  nvenience Routin
1a090 65 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51  es For Running Q
1a0a0 75 65 72 69 65 73 0a 2a 2a 0a 2a 2a 20 54 68 69  ueries.**.** Thi
1a0b0 73 20 69 73 20 61 20 6c 65 67 61 63 79 20 69 6e  s is a legacy in
1a0c0 74 65 72 66 61 63 65 20 74 68 61 74 20 69 73 20  terface that is 
1a0d0 70 72 65 73 65 72 76 65 64 20 66 6f 72 20 62 61  preserved for ba
1a0e0 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62  ckwards compatib
1a0f0 69 6c 69 74 79 2e 0a 2a 2a 20 55 73 65 20 6f 66  ility..** Use of
1a100 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   this interface 
1a110 69 73 20 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e 64  is not recommend
1a120 65 64 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69  ed..**.** Defini
1a130 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c  tion: A <b>resul
1a140 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d  t table</b> is m
1a150 65 6d 6f 72 79 20 64 61 74 61 20 73 74 72 75 63  emory data struc
1a160 74 75 72 65 20 63 72 65 61 74 65 64 20 62 79 20  ture created by 
1a170 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
1a180 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74  get_table()] int
1a190 65 72 66 61 63 65 2e 20 20 41 20 72 65 73 75 6c  erface.  A resul
1a1a0 74 20 74 61 62 6c 65 20 72 65 63 6f 72 64 73 20  t table records 
1a1b0 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20  the.** complete 
1a1c0 71 75 65 72 79 20 72 65 73 75 6c 74 73 20 66 72  query results fr
1a1d0 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71  om one or more q
1a1e0 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  ueries..**.** Th
1a1f0 65 20 74 61 62 6c 65 20 63 6f 6e 63 65 70 74 75  e table conceptu
1a200 61 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d 62 65  ally has a numbe
1a210 72 20 6f 66 20 72 6f 77 73 20 61 6e 64 20 63 6f  r of rows and co
1a220 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74  lumns.  But.** t
1a230 68 65 73 65 20 6e 75 6d 62 65 72 73 20 61 72 65  hese numbers are
1a240 20 6e 6f 74 20 70 61 72 74 20 6f 66 20 74 68 65   not part of the
1a250 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 74   result table it
1a260 73 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20  self.  These.** 
1a270 6e 75 6d 62 65 72 73 20 61 72 65 20 6f 62 74 61  numbers are obta
1a280 69 6e 65 64 20 73 65 70 61 72 61 74 65 6c 79 2e  ined separately.
1a290 20 20 4c 65 74 20 4e 20 62 65 20 74 68 65 20 6e    Let N be the n
1a2a0 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a  umber of rows.**
1a2b0 20 61 6e 64 20 4d 20 62 65 20 74 68 65 20 6e 75   and M be the nu
1a2c0 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e  mber of columns.
1a2d0 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20  .**.** A result 
1a2e0 74 61 62 6c 65 20 69 73 20 61 6e 20 61 72 72 61  table is an arra
1a2f0 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f  y of pointers to
1a300 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
1a310 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a   UTF-8 strings..
1a320 2a 2a 20 54 68 65 72 65 20 61 72 65 20 28 4e 2b  ** There are (N+
1a330 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e  1)*M elements in
1a340 20 74 68 65 20 61 72 72 61 79 2e 20 20 54 68 65   the array.  The
1a350 20 66 69 72 73 74 20 4d 20 70 6f 69 6e 74 65 72   first M pointer
1a360 73 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65  s point.** to ze
1a370 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74  ro-terminated st
1a380 72 69 6e 67 73 20 74 68 61 74 20 20 63 6f 6e 74  rings that  cont
1a390 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66  ain the names of
1a3a0 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a   the columns..**
1a3b0 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 65   The remaining e
1a3c0 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74  ntries all point
1a3d0 20 74 6f 20 71 75 65 72 79 20 72 65 73 75 6c 74   to query result
1a3e0 73 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20  s.  NULL values 
1a3f0 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c  result.** in NUL
1a400 4c 20 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c  L pointers.  All
1a410 20 6f 74 68 65 72 20 76 61 6c 75 65 73 20 61 72   other values ar
1a420 65 20 69 6e 20 74 68 65 69 72 20 55 54 46 2d 38  e in their UTF-8
1a430 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
1a440 0a 2a 2a 20 73 74 72 69 6e 67 20 72 65 70 72 65  .** string repre
1a450 73 65 6e 74 61 74 69 6f 6e 20 61 73 20 72 65 74  sentation as ret
1a460 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
1a470 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d  3_column_text()]
1a480 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74  ..**.** A result
1a490 20 74 61 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e   table might con
1a4a0 73 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d  sist of one or m
1a4b0 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ore memory alloc
1a4c0 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73  ations..** It is
1a4d0 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 70 61 73   not safe to pas
1a4e0 73 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65  s a result table
1a4f0 20 64 69 72 65 63 74 6c 79 20 74 6f 20 5b 73 71   directly to [sq
1a500 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a  lite3_free()]..*
1a510 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65  * A result table
1a520 20 73 68 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c   should be deall
1a530 6f 63 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71  ocated using [sq
1a540 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65  lite3_free_table
1a550 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73 20  ()]..**.** ^(As 
1a560 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 74 68  an example of th
1a570 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 66  e result table f
1a580 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73 65 20 61  ormat, suppose a
1a590 20 71 75 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a   query result.**
1a5a0 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a   is as follows:.
1a5b0 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
1a5c0 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20  e><pre>.**      
1a5d0 20 20 4e 61 6d 65 20 20 20 20 20 20 20 20 7c 20    Name        | 
1a5e0 41 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d  Age.**        --
1a5f0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
1a600 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20  -----.**        
1a610 41 6c 69 63 65 20 20 20 20 20 20 20 7c 20 34 33  Alice       | 43
1a620 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f 62 20 20  .**        Bob  
1a630 20 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20         | 28.**  
1a640 20 20 20 20 20 20 43 69 6e 64 79 20 20 20 20 20        Cindy     
1a650 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e    | 21.** </pre>
1a660 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
1a670 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 77  .** There are tw
1a680 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20  o column (M==2) 
1a690 61 6e 64 20 74 68 72 65 65 20 72 6f 77 73 20 28  and three rows (
1a6a0 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20 74 68 65  N==3).  Thus the
1a6b0 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61 62 6c 65  .** result table
1a6c0 20 68 61 73 20 38 20 65 6e 74 72 69 65 73 2e 20   has 8 entries. 
1a6d0 20 53 75 70 70 6f 73 65 20 74 68 65 20 72 65 73   Suppose the res
1a6e0 75 6c 74 20 74 61 62 6c 65 20 69 73 20 73 74 6f  ult table is sto
1a6f0 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72  red.** in an arr
1a700 61 79 20 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c  ay names azResul
1a710 74 2e 20 20 54 68 65 6e 20 61 7a 52 65 73 75 6c  t.  Then azResul
1a720 74 20 68 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e  t holds this con
1a730 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  tent:.**.** <blo
1a740 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
1a750 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
1a760 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22  &#91;0] = "Name"
1a770 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
1a780 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22 41  sult&#91;1] = "A
1a790 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  ge";.**        a
1a7a0 7a 52 65 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d  zResult&#91;2] =
1a7b0 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20   "Alice";.**    
1a7c0 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
1a7d0 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20  ;3] = "43";.**  
1a7e0 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
1a7f0 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a  91;4] = "Bob";.*
1a800 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
1a810 74 26 23 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b  t&#91;5] = "28";
1a820 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
1a830 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22 43 69  ult&#91;6] = "Ci
1a840 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  ndy";.**        
1a850 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 37 5d 20  azResult&#91;7] 
1a860 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65  = "21";.** </pre
1a870 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e  ></blockquote>)^
1a880 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1a890 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20  te3_get_table() 
1a8a0 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61 74  function evaluat
1a8b0 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a  es one or more.*
1a8c0 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61  * semicolon-sepa
1a8d0 72 61 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d  rated SQL statem
1a8e0 65 6e 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f  ents in the zero
1a8f0 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d  -terminated UTF-
1a900 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20 69  8.** string of i
1a910 74 73 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  ts 2nd parameter
1a920 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 72   and returns a r
1a930 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 74  esult table to t
1a940 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69  he.** pointer gi
1a950 76 65 6e 20 69 6e 20 69 74 73 20 33 72 64 20 70  ven in its 3rd p
1a960 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
1a970 41 66 74 65 72 20 74 68 65 20 61 70 70 6c 69 63  After the applic
1a980 61 74 69 6f 6e 20 68 61 73 20 66 69 6e 69 73 68  ation has finish
1a990 65 64 20 77 69 74 68 20 74 68 65 20 72 65 73 75  ed with the resu
1a9a0 6c 74 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  lt from sqlite3_
1a9b0 67 65 74 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a 20  get_table(),.** 
1a9c0 69 74 20 6d 75 73 74 20 70 61 73 73 20 74 68 65  it must pass the
1a9d0 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 70 6f   result table po
1a9e0 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  inter to sqlite3
1a9f0 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 20 69 6e  _free_table() in
1aa00 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c   order to.** rel
1aa10 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20  ease the memory 
1aa20 74 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65  that was malloce
1aa30 64 2e 20 20 42 65 63 61 75 73 65 20 6f 66 20 74  d.  Because of t
1aa40 68 65 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73  he way the.** [s
1aa50 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
1aa60 20 68 61 70 70 65 6e 73 20 77 69 74 68 69 6e 20   happens within 
1aa70 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
1aa80 65 28 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67  e(), the calling
1aa90 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73  .** function mus
1aaa0 74 20 6e 6f 74 20 74 72 79 20 74 6f 20 63 61 6c  t not try to cal
1aab0 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  l [sqlite3_free(
1aac0 29 5d 20 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e  )] directly.  On
1aad0 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  ly.** [sqlite3_f
1aae0 72 65 65 5f 74 61 62 6c 65 28 29 5d 20 69 73 20  ree_table()] is 
1aaf0 61 62 6c 65 20 74 6f 20 72 65 6c 65 61 73 65 20  able to release 
1ab00 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65  the memory prope
1ab10 72 6c 79 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a  rly and safely..
1ab20 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
1ab30 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 69 6e  3_get_table() in
1ab40 74 65 72 66 61 63 65 20 69 73 20 69 6d 70 6c 65  terface is imple
1ab50 6d 65 6e 74 65 64 20 61 73 20 61 20 77 72 61 70  mented as a wrap
1ab60 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73  per around.** [s
1ab70 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2e 20  qlite3_exec()]. 
1ab80 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74   The sqlite3_get
1ab90 5f 74 61 62 6c 65 28 29 20 72 6f 75 74 69 6e 65  _table() routine
1aba0 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 61   does not have a
1abb0 63 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20  ccess.** to any 
1abc0 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 20 73 74  internal data st
1abd0 72 75 63 74 75 72 65 73 20 6f 66 20 53 51 4c 69  ructures of SQLi
1abe0 74 65 2e 20 20 49 74 20 75 73 65 73 20 6f 6e 6c  te.  It uses onl
1abf0 79 20 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20  y the public.** 
1ac00 69 6e 74 65 72 66 61 63 65 20 64 65 66 69 6e 65  interface define
1ac10 64 20 68 65 72 65 2e 20 20 41 73 20 61 20 63 6f  d here.  As a co
1ac20 6e 73 65 71 75 65 6e 63 65 2c 20 65 72 72 6f 72  nsequence, error
1ac30 73 20 74 68 61 74 20 6f 63 63 75 72 20 69 6e 20  s that occur in 
1ac40 74 68 65 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c  the.** wrapper l
1ac50 61 79 65 72 20 6f 75 74 73 69 64 65 20 6f 66 20  ayer outside of 
1ac60 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71  the internal [sq
1ac70 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 63 61  lite3_exec()] ca
1ac80 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65  ll are not.** re
1ac90 66 6c 65 63 74 65 64 20 69 6e 20 73 75 62 73 65  flected in subse
1aca0 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b  quent calls to [
1acb0 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
1acc0 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
1acd0 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a  3_errmsg()]..*/.
1ace0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
1acf0 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
1ad00 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
1ad10 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20            /* An 
1ad20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f  open database */
1ad30 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
1ad40 53 71 6c 2c 20 20 20 20 20 2f 2a 20 53 51 4c 20  Sql,     /* SQL 
1ad50 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 20  to be evaluated 
1ad60 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 2a 70 61 7a  */.  char ***paz
1ad70 52 65 73 75 6c 74 2c 20 20 20 20 2f 2a 20 52 65  Result,    /* Re
1ad80 73 75 6c 74 73 20 6f 66 20 74 68 65 20 71 75 65  sults of the que
1ad90 72 79 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 52  ry */.  int *pnR
1ada0 6f 77 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a  ow,           /*
1adb0 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c   Number of resul
1adc0 74 20 72 6f 77 73 20 77 72 69 74 74 65 6e 20 68  t rows written h
1add0 65 72 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e  ere */.  int *pn
1ade0 43 6f 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20 2f  Column,        /
1adf0 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75  * Number of resu
1ae00 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74  lt columns writt
1ae10 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 63 68 61  en here */.  cha
1ae20 72 20 2a 2a 70 7a 45 72 72 6d 73 67 20 20 20 20  r **pzErrmsg    
1ae30 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20     /* Error msg 
1ae40 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a  written here */.
1ae50 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  );.SQLITE_API vo
1ae60 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f  id sqlite3_free_
1ae70 74 61 62 6c 65 28 63 68 61 72 20 2a 2a 72 65 73  table(char **res
1ae80 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ult);../*.** CAP
1ae90 49 33 52 45 46 3a 20 46 6f 72 6d 61 74 74 65 64  I3REF: Formatted
1aea0 20 53 74 72 69 6e 67 20 50 72 69 6e 74 69 6e 67   String Printing
1aeb0 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a   Functions.**.**
1aec0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
1aed0 61 72 65 20 77 6f 72 6b 2d 61 6c 69 6b 65 73 20  are work-alikes 
1aee0 6f 66 20 74 68 65 20 22 70 72 69 6e 74 66 28 29  of the "printf()
1aef0 22 20 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63  " family of func
1af00 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68  tions.** from th
1af10 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62  e standard C lib
1af20 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  rary..**.** ^The
1af30 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66   sqlite3_mprintf
1af40 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76  () and sqlite3_v
1af50 6d 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e  mprintf() routin
1af60 65 73 20 77 72 69 74 65 20 74 68 65 69 72 0a 2a  es write their.*
1af70 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 6f 20 6d  * results into m
1af80 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66  emory obtained f
1af90 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
1afa0 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73  loc()]..** The s
1afb0 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20  trings returned 
1afc0 62 79 20 74 68 65 73 65 20 74 77 6f 20 72 6f 75  by these two rou
1afd0 74 69 6e 65 73 20 73 68 6f 75 6c 64 20 62 65 0a  tines should be.
1afe0 2a 2a 20 72 65 6c 65 61 73 65 64 20 62 79 20 5b  ** released by [
1aff0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e  sqlite3_free()].
1b000 20 20 5e 42 6f 74 68 20 72 6f 75 74 69 6e 65 73    ^Both routines
1b010 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c   return a.** NUL
1b020 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 5b 73 71  L pointer if [sq
1b030 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
1b040 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c  is unable to all
1b050 6f 63 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20  ocate enough.** 
1b060 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74  memory to hold t
1b070 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72  he resulting str
1b080 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ing..**.** ^(The
1b090 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
1b0a0 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73  f() routine is s
1b0b0 69 6d 69 6c 61 72 20 74 6f 20 22 73 6e 70 72 69  imilar to "snpri
1b0c0 6e 74 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 74  ntf()" from.** t
1b0d0 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  he standard C li
1b0e0 62 72 61 72 79 2e 20 20 54 68 65 20 72 65 73 75  brary.  The resu
1b0f0 6c 74 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e  lt is written in
1b100 74 6f 20 74 68 65 0a 2a 2a 20 62 75 66 66 65 72  to the.** buffer
1b110 20 73 75 70 70 6c 69 65 64 20 61 73 20 74 68 65   supplied as the
1b120 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
1b130 72 20 77 68 6f 73 65 20 73 69 7a 65 20 69 73 20  r whose size is 
1b140 67 69 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65 20  given by.** the 
1b150 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e  first parameter.
1b160 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 6f   Note that the o
1b170 72 64 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66  rder of the.** f
1b180 69 72 73 74 20 74 77 6f 20 70 61 72 61 6d 65 74  irst two paramet
1b190 65 72 73 20 69 73 20 72 65 76 65 72 73 65 64 20  ers is reversed 
1b1a0 66 72 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e  from snprintf().
1b1b0 29 5e 20 20 54 68 69 73 20 69 73 20 61 6e 0a 2a  )^  This is an.*
1b1c0 2a 20 68 69 73 74 6f 72 69 63 61 6c 20 61 63 63  * historical acc
1b1d0 69 64 65 6e 74 20 74 68 61 74 20 63 61 6e 6e 6f  ident that canno
1b1e0 74 20 62 65 20 66 69 78 65 64 20 77 69 74 68 6f  t be fixed witho
1b1f0 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 62  ut breaking.** b
1b200 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69  ackwards compati
1b210 62 69 6c 69 74 79 2e 20 20 5e 28 4e 6f 74 65 20  bility.  ^(Note 
1b220 61 6c 73 6f 20 74 68 61 74 20 73 71 6c 69 74 65  also that sqlite
1b230 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20  3_snprintf().** 
1b240 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
1b250 72 20 74 6f 20 69 74 73 20 62 75 66 66 65 72 20  r to its buffer 
1b260 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 6e  instead of the n
1b270 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 72  umber of.** char
1b280 61 63 74 65 72 73 20 61 63 74 75 61 6c 6c 79 20  acters actually 
1b290 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65  written into the
1b2a0 20 62 75 66 66 65 72 2e 29 5e 20 20 57 65 20 61   buffer.)^  We a
1b2b0 64 6d 69 74 20 74 68 61 74 0a 2a 2a 20 74 68 65  dmit that.** the
1b2c0 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61   number of chara
1b2d0 63 74 65 72 73 20 77 72 69 74 74 65 6e 20 77 6f  cters written wo
1b2e0 75 6c 64 20 62 65 20 61 20 6d 6f 72 65 20 75 73  uld be a more us
1b2f0 65 66 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76  eful return.** v
1b300 61 6c 75 65 20 62 75 74 20 77 65 20 63 61 6e 6e  alue but we cann
1b310 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 69 6d  ot change the im
1b320 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
1b330 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
1b340 28 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75  ().** now withou
1b350 74 20 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61  t breaking compa
1b360 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20  tibility..**.** 
1b370 5e 41 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20  ^As long as the 
1b380 62 75 66 66 65 72 20 73 69 7a 65 20 69 73 20 67  buffer size is g
1b390 72 65 61 74 65 72 20 74 68 61 6e 20 7a 65 72 6f  reater than zero
1b3a0 2c 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e  , sqlite3_snprin
1b3b0 74 66 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65  tf().** guarante
1b3c0 65 73 20 74 68 61 74 20 74 68 65 20 62 75 66 66  es that the buff
1b3d0 65 72 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72  er is always zer
1b3e0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e  o-terminated.  ^
1b3f0 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72  The first.** par
1b400 61 6d 65 74 65 72 20 22 6e 22 20 69 73 20 74 68  ameter "n" is th
1b410 65 20 74 6f 74 61 6c 20 73 69 7a 65 20 6f 66 20  e total size of 
1b420 74 68 65 20 62 75 66 66 65 72 2c 20 69 6e 63 6c  the buffer, incl
1b430 75 64 69 6e 67 20 73 70 61 63 65 20 66 6f 72 0a  uding space for.
1b440 2a 2a 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d  ** the zero term
1b450 69 6e 61 74 6f 72 2e 20 20 53 6f 20 74 68 65 20  inator.  So the 
1b460 6c 6f 6e 67 65 73 74 20 73 74 72 69 6e 67 20 74  longest string t
1b470 68 61 74 20 63 61 6e 20 62 65 20 63 6f 6d 70 6c  hat can be compl
1b480 65 74 65 6c 79 0a 2a 2a 20 77 72 69 74 74 65 6e  etely.** written
1b490 20 77 69 6c 6c 20 62 65 20 6e 2d 31 20 63 68 61   will be n-1 cha
1b4a0 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e  racters..**.** ^
1b4b0 54 68 65 20 73 71 6c 69 74 65 33 5f 76 73 6e 70  The sqlite3_vsnp
1b4c0 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20  rintf() routine 
1b4d0 69 73 20 61 20 76 61 72 61 72 67 73 20 76 65 72  is a varargs ver
1b4e0 73 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f  sion of sqlite3_
1b4f0 73 6e 70 72 69 6e 74 66 28 29 2e 0a 2a 2a 0a 2a  snprintf()..**.*
1b500 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
1b510 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 20 73   all implement s
1b520 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 66  ome additional f
1b530 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f 70 74  ormatting.** opt
1b540 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 75 73  ions that are us
1b550 65 66 75 6c 20 66 6f 72 20 63 6f 6e 73 74 72 75  eful for constru
1b560 63 74 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d  cting SQL statem
1b570 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20  ents..** All of 
1b580 74 68 65 20 75 73 75 61 6c 20 70 72 69 6e 74 66  the usual printf
1b590 28 29 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70  () formatting op
1b5a0 74 69 6f 6e 73 20 61 70 70 6c 79 2e 20 20 49 6e  tions apply.  In
1b5b0 20 61 64 64 69 74 69 6f 6e 2c 20 74 68 65 72 65   addition, there
1b5c0 0a 2a 2a 20 69 73 20 61 72 65 20 22 25 71 22 2c  .** is are "%q",
1b5d0 20 22 25 51 22 2c 20 61 6e 64 20 22 25 7a 22 20   "%Q", and "%z" 
1b5e0 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  options..**.** ^
1b5f0 28 54 68 65 20 25 71 20 6f 70 74 69 6f 6e 20 77  (The %q option w
1b600 6f 72 6b 73 20 6c 69 6b 65 20 25 73 20 69 6e 20  orks like %s in 
1b610 74 68 61 74 20 69 74 20 73 75 62 73 74 69 74 75  that it substitu
1b620 74 65 73 20 61 20 6e 75 6c 6c 2d 74 65 72 6d 69  tes a null-termi
1b630 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20  nated.** string 
1b640 66 72 6f 6d 20 74 68 65 20 61 72 67 75 6d 65 6e  from the argumen
1b650 74 20 6c 69 73 74 2e 20 20 42 75 74 20 25 71 20  t list.  But %q 
1b660 61 6c 73 6f 20 64 6f 75 62 6c 65 73 20 65 76 65  also doubles eve
1b670 72 79 20 27 5c 27 27 20 63 68 61 72 61 63 74 65  ry '\'' characte
1b680 72 2e 0a 2a 2a 20 25 71 20 69 73 20 64 65 73 69  r..** %q is desi
1b690 67 6e 65 64 20 66 6f 72 20 75 73 65 20 69 6e 73  gned for use ins
1b6a0 69 64 65 20 61 20 73 74 72 69 6e 67 20 6c 69 74  ide a string lit
1b6b0 65 72 61 6c 2e 29 5e 20 20 42 79 20 64 6f 75 62  eral.)^  By doub
1b6c0 6c 69 6e 67 20 65 61 63 68 20 27 5c 27 27 0a 2a  ling each '\''.*
1b6d0 2a 20 63 68 61 72 61 63 74 65 72 20 69 74 20 65  * character it e
1b6e0 73 63 61 70 65 73 20 74 68 61 74 20 63 68 61 72  scapes that char
1b6f0 61 63 74 65 72 20 61 6e 64 20 61 6c 6c 6f 77 73  acter and allows
1b700 20 69 74 20 74 6f 20 62 65 20 69 6e 73 65 72 74   it to be insert
1b710 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 73  ed into.** the s
1b720 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72  tring..**.** For
1b730 20 65 78 61 6d 70 6c 65 2c 20 61 73 73 75 6d 65   example, assume
1b740 20 74 68 65 20 73 74 72 69 6e 67 20 76 61 72 69   the string vari
1b750 61 62 6c 65 20 7a 54 65 78 74 20 63 6f 6e 74 61  able zText conta
1b760 69 6e 73 20 74 65 78 74 20 61 73 20 66 6f 6c 6c  ins text as foll
1b770 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ows:.**.** <bloc
1b780 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
1b790 20 63 68 61 72 20 2a 7a 54 65 78 74 20 3d 20 22   char *zText = "
1b7a0 49 74 27 73 20 61 20 68 61 70 70 79 20 64 61 79  It's a happy day
1b7b0 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  !";.** </pre></b
1b7c0 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
1b7d0 20 4f 6e 65 20 63 61 6e 20 75 73 65 20 74 68 69   One can use thi
1b7e0 73 20 74 65 78 74 20 69 6e 20 61 6e 20 53 51 4c  s text in an SQL
1b7f0 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20 66 6f   statement as fo
1b800 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  llows:.**.** <bl
1b810 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
1b820 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20  *  char *zSQL = 
1b830 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
1b840 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62  "INSERT INTO tab
1b850 6c 65 20 56 41 4c 55 45 53 28 27 25 71 27 29 22  le VALUES('%q')"
1b860 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71  , zText);.**  sq
1b870 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a  lite3_exec(db, z
1b880 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a  SQL, 0, 0, 0);.*
1b890 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  *  sqlite3_free(
1b8a0 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  zSQL);.** </pre>
1b8b0 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
1b8c0 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65 20  .** Because the 
1b8d0 25 71 20 66 6f 72 6d 61 74 20 73 74 72 69 6e 67  %q format string
1b8e0 20 69 73 20 75 73 65 64 2c 20 74 68 65 20 27 5c   is used, the '\
1b8f0 27 27 20 63 68 61 72 61 63 74 65 72 20 69 6e 20  '' character in 
1b900 7a 54 65 78 74 0a 2a 2a 20 69 73 20 65 73 63 61  zText.** is esca
1b910 70 65 64 20 61 6e 64 20 74 68 65 20 53 51 4c 20  ped and the SQL 
1b920 67 65 6e 65 72 61 74 65 64 20 69 73 20 61 73 20  generated is as 
1b930 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c  follows:.**.** <
1b940 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
1b950 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f  .**  INSERT INTO
1b960 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27   table1 VALUES('
1b970 49 74 27 27 73 20 61 20 68 61 70 70 79 20 64 61  It''s a happy da
1b980 79 21 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  y!').** </pre></
1b990 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
1b9a0 2a 20 54 68 69 73 20 69 73 20 63 6f 72 72 65 63  * This is correc
1b9b0 74 2e 20 20 48 61 64 20 77 65 20 75 73 65 64 20  t.  Had we used 
1b9c0 25 73 20 69 6e 73 74 65 61 64 20 6f 66 20 25 71  %s instead of %q
1b9d0 2c 20 74 68 65 20 67 65 6e 65 72 61 74 65 64 20  , the generated 
1b9e0 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68 61 76  SQL.** would hav
1b9f0 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20 74 68  e looked like th
1ba00 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  is:.**.** <block
1ba10 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
1ba20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c  INSERT INTO tabl
1ba30 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 73 20  e1 VALUES('It's 
1ba40 61 20 68 61 70 70 79 20 64 61 79 21 27 29 3b 0a  a happy day!');.
1ba50 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
1ba60 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69  quote>.**.** Thi
1ba70 73 20 73 65 63 6f 6e 64 20 65 78 61 6d 70 6c 65  s second example
1ba80 20 69 73 20 61 6e 20 53 51 4c 20 73 79 6e 74 61   is an SQL synta
1ba90 78 20 65 72 72 6f 72 2e 20 20 41 73 20 61 20 67  x error.  As a g
1baa0 65 6e 65 72 61 6c 20 72 75 6c 65 20 79 6f 75 20  eneral rule you 
1bab0 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77 61 79 73  should.** always
1bac0 20 75 73 65 20 25 71 20 69 6e 73 74 65 61 64 20   use %q instead 
1bad0 6f 66 20 25 73 20 77 68 65 6e 20 69 6e 73 65 72  of %s when inser
1bae0 74 69 6e 67 20 74 65 78 74 20 69 6e 74 6f 20 61  ting text into a
1baf0 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e   string literal.
1bb00 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 51 20  .**.** ^(The %Q 
1bb10 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b  option works lik
1bb20 65 20 25 71 20 65 78 63 65 70 74 20 69 74 20 61  e %q except it a
1bb30 6c 73 6f 20 61 64 64 73 20 73 69 6e 67 6c 65 20  lso adds single 
1bb40 71 75 6f 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a  quotes around.**
1bb50 20 74 68 65 20 6f 75 74 73 69 64 65 20 6f 66 20   the outside of 
1bb60 74 68 65 20 74 6f 74 61 6c 20 73 74 72 69 6e 67  the total string
1bb70 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c  .  Additionally,
1bb80 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   if the paramete
1bb90 72 20 69 6e 20 74 68 65 0a 2a 2a 20 61 72 67 75  r in the.** argu
1bba0 6d 65 6e 74 20 6c 69 73 74 20 69 73 20 61 20 4e  ment list is a N
1bbb0 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 25 51 20  ULL pointer, %Q 
1bbc0 73 75 62 73 74 69 74 75 74 65 73 20 74 68 65 20  substitutes the 
1bbd0 74 65 78 74 20 22 4e 55 4c 4c 22 20 28 77 69 74  text "NULL" (wit
1bbe0 68 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c 65 20 71  hout.** single q
1bbf0 75 6f 74 65 73 29 2e 29 5e 20 20 53 6f 2c 20 66  uotes).)^  So, f
1bc00 6f 72 20 65 78 61 6d 70 6c 65 2c 20 6f 6e 65 20  or example, one 
1bc10 63 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a  could say:.**.**
1bc20 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
1bc30 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51  e>.**  char *zSQ
1bc40 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69  L = sqlite3_mpri
1bc50 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f  ntf("INSERT INTO
1bc60 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28 25 51   table VALUES(%Q
1bc70 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20  )", zText);.**  
1bc80 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c  sqlite3_exec(db,
1bc90 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b   zSQL, 0, 0, 0);
1bca0 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65  .**  sqlite3_fre
1bcb0 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72  e(zSQL);.** </pr
1bcc0 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
1bcd0 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 61  **.** The code a
1bce0 62 6f 76 65 20 77 69 6c 6c 20 72 65 6e 64 65 72  bove will render
1bcf0 20 61 20 63 6f 72 72 65 63 74 20 53 51 4c 20 73   a correct SQL s
1bd00 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20  tatement in the 
1bd10 7a 53 51 4c 0a 2a 2a 20 76 61 72 69 61 62 6c 65  zSQL.** variable
1bd20 20 65 76 65 6e 20 69 66 20 74 68 65 20 7a 54 65   even if the zTe
1bd30 78 74 20 76 61 72 69 61 62 6c 65 20 69 73 20 61  xt variable is a
1bd40 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
1bd50 2a 0a 2a 2a 20 5e 28 54 68 65 20 22 25 7a 22 20  *.** ^(The "%z" 
1bd60 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f  formatting optio
1bd70 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 22 25 73  n works like "%s
1bd80 22 20 62 75 74 20 77 69 74 68 20 74 68 65 0a 2a  " but with the.*
1bd90 2a 20 61 64 64 69 74 69 6f 6e 20 74 68 61 74 20  * addition that 
1bda0 61 66 74 65 72 20 74 68 65 20 73 74 72 69 6e 67  after the string
1bdb0 20 68 61 73 20 62 65 65 6e 20 72 65 61 64 20 61   has been read a
1bdc0 6e 64 20 63 6f 70 69 65 64 20 69 6e 74 6f 0a 2a  nd copied into.*
1bdd0 2a 20 74 68 65 20 72 65 73 75 6c 74 2c 20 5b 73  * the result, [s
1bde0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 69  qlite3_free()] i
1bdf0 73 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20  s called on the 
1be00 69 6e 70 75 74 20 73 74 72 69 6e 67 2e 29 5e 0a  input string.)^.
1be10 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 68  */.SQLITE_API ch
1be20 61 72 20 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69  ar *sqlite3_mpri
1be30 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ntf(const char*,
1be40 2e 2e 2e 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  ...);.SQLITE_API
1be50 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76   char *sqlite3_v
1be60 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68  mprintf(const ch
1be70 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 53  ar*, va_list);.S
1be80 51 4c 49 54 45 5f 41 50 49 20 63 68 61 72 20 2a  QLITE_API char *
1be90 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
1bea0 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74  (int,char*,const
1beb0 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 53 51   char*, ...);.SQ
1bec0 4c 49 54 45 5f 41 50 49 20 63 68 61 72 20 2a 73  LITE_API char *s
1bed0 71 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66  qlite3_vsnprintf
1bee0 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74  (int,char*,const
1bef0 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29   char*, va_list)
1bf00 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1bf10 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61  F: Memory Alloca
1bf20 74 69 6f 6e 20 53 75 62 73 79 73 74 65 6d 0a 2a  tion Subsystem.*
1bf30 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20  *.** The SQLite 
1bf40 63 6f 72 65 20 75 73 65 73 20 74 68 65 73 65 20  core uses these 
1bf50 74 68 72 65 65 20 72 6f 75 74 69 6e 65 73 20 66  three routines f
1bf60 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77  or all of its ow
1bf70 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65  n.** internal me
1bf80 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
1bf90 6e 65 65 64 73 2e 20 22 43 6f 72 65 22 20 69 6e  needs. "Core" in
1bfa0 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 65   the previous se
1bfb0 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e  ntence.** does n
1bfc0 6f 74 20 69 6e 63 6c 75 64 65 20 6f 70 65 72 61  ot include opera
1bfd0 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63  ting-system spec
1bfe0 69 66 69 63 20 56 46 53 20 69 6d 70 6c 65 6d 65  ific VFS impleme
1bff0 6e 74 61 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a  ntation.  The.**
1c000 20 57 69 6e 64 6f 77 73 20 56 46 53 20 75 73 65   Windows VFS use
1c010 73 20 6e 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28  s native malloc(
1c020 29 20 61 6e 64 20 66 72 65 65 28 29 20 66 6f 72  ) and free() for
1c030 20 73 6f 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73   some operations
1c040 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
1c050 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f  ite3_malloc() ro
1c060 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20  utine returns a 
1c070 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f  pointer to a blo
1c080 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20  ck.** of memory 
1c090 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73  at least N bytes
1c0a0 20 69 6e 20 6c 65 6e 67 74 68 2c 20 77 68 65 72   in length, wher
1c0b0 65 20 4e 20 69 73 20 74 68 65 20 70 61 72 61 6d  e N is the param
1c0c0 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c  eter..** ^If sql
1c0d0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73  ite3_malloc() is
1c0e0 20 75 6e 61 62 6c 65 20 74 6f 20 6f 62 74 61 69   unable to obtai
1c0f0 6e 20 73 75 66 66 69 63 69 65 6e 74 20 66 72 65  n sufficient fre
1c100 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20  e.** memory, it 
1c110 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70  returns a NULL p
1c120 6f 69 6e 74 65 72 2e 20 20 5e 49 66 20 74 68 65  ointer.  ^If the
1c130 20 70 61 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a   parameter N to.
1c140 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  ** sqlite3_mallo
1c150 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e  c() is zero or n
1c160 65 67 61 74 69 76 65 20 74 68 65 6e 20 73 71 6c  egative then sql
1c170 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65  ite3_malloc() re
1c180 74 75 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20  turns.** a NULL 
1c190 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  pointer..**.** ^
1c1a0 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f  Calling sqlite3_
1c1b0 66 72 65 65 28 29 20 77 69 74 68 20 61 20 70 6f  free() with a po
1c1c0 69 6e 74 65 72 20 70 72 65 76 69 6f 75 73 6c 79  inter previously
1c1d0 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20   returned.** by 
1c1e0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1c1f0 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   or sqlite3_real
1c200 6c 6f 63 28 29 20 72 65 6c 65 61 73 65 73 20 74  loc() releases t
1c210 68 61 74 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a  hat memory so.**
1c220 20 74 68 61 74 20 69 74 20 6d 69 67 68 74 20 62   that it might b
1c230 65 20 72 65 75 73 65 64 2e 20 20 5e 54 68 65 20  e reused.  ^The 
1c240 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 72  sqlite3_free() r
1c250 6f 75 74 69 6e 65 20 69 73 0a 2a 2a 20 61 20 6e  outine is.** a n
1c260 6f 2d 6f 70 20 69 66 20 69 73 20 63 61 6c 6c 65  o-op if is calle
1c270 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f  d with a NULL po
1c280 69 6e 74 65 72 2e 20 20 50 61 73 73 69 6e 67 20  inter.  Passing 
1c290 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a  a NULL pointer.*
1c2a0 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65  * to sqlite3_fre
1c2b0 65 28 29 20 69 73 20 68 61 72 6d 6c 65 73 73 2e  e() is harmless.
1c2c0 20 20 41 66 74 65 72 20 62 65 69 6e 67 20 66 72    After being fr
1c2d0 65 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73  eed, memory.** s
1c2e0 68 6f 75 6c 64 20 6e 65 69 74 68 65 72 20 62 65  hould neither be
1c2f0 20 72 65 61 64 20 6e 6f 72 20 77 72 69 74 74 65   read nor writte
1c300 6e 2e 20 20 45 76 65 6e 20 72 65 61 64 69 6e 67  n.  Even reading
1c310 20 70 72 65 76 69 6f 75 73 6c 79 20 66 72 65 65   previously free
1c320 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 68  d.** memory migh
1c330 74 20 72 65 73 75 6c 74 20 69 6e 20 61 20 73 65  t result in a se
1c340 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74  gmentation fault
1c350 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 65   or other severe
1c360 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72   error..** Memor
1c370 79 20 63 6f 72 72 75 70 74 69 6f 6e 2c 20 61 20  y corruption, a 
1c380 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75  segmentation fau
1c390 6c 74 2c 20 6f 72 20 6f 74 68 65 72 20 73 65 76  lt, or other sev
1c3a0 65 72 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 67  ere error.** mig
1c3b0 68 74 20 72 65 73 75 6c 74 20 69 66 20 73 71 6c  ht result if sql
1c3c0 69 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 63  ite3_free() is c
1c3d0 61 6c 6c 65 64 20 77 69 74 68 20 61 20 6e 6f 6e  alled with a non
1c3e0 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68  -NULL pointer th
1c3f0 61 74 0a 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 62  at.** was not ob
1c400 74 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69  tained from sqli
1c410 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20  te3_malloc() or 
1c420 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1c430 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73  )..**.** ^(The s
1c440 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1c450 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d   interface attem
1c460 70 74 73 20 74 6f 20 72 65 73 69 7a 65 20 61 0a  pts to resize a.
1c470 2a 2a 20 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20  ** prior memory 
1c480 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65  allocation to be
1c490 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65   at least N byte
1c4a0 73 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  s, where N is th
1c4b0 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61  e.** second para
1c4c0 6d 65 74 65 72 2e 20 20 54 68 65 20 6d 65 6d 6f  meter.  The memo
1c4d0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f  ry allocation to
1c4e0 20 62 65 20 72 65 73 69 7a 65 64 20 69 73 20 74   be resized is t
1c4f0 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61  he first.** para
1c500 6d 65 74 65 72 2e 29 5e 20 5e 20 49 66 20 74 68  meter.)^ ^ If th
1c510 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
1c520 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61  r to sqlite3_rea
1c530 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 20 4e  lloc().** is a N
1c540 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e  ULL pointer then
1c550 20 69 74 73 20 62 65 68 61 76 69 6f 72 20 69 73   its behavior is
1c560 20 69 64 65 6e 74 69 63 61 6c 20 74 6f 20 63 61   identical to ca
1c570 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33  lling.** sqlite3
1c580 5f 6d 61 6c 6c 6f 63 28 4e 29 20 77 68 65 72 65  _malloc(N) where
1c590 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64   N is the second
1c5a0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
1c5b0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e  lite3_realloc().
1c5c0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 65 63 6f  .** ^If the seco
1c5d0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  nd parameter to 
1c5e0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1c5f0 29 20 69 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20  ) is zero or.** 
1c600 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 74 68  negative then th
1c610 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 65 78  e behavior is ex
1c620 61 63 74 6c 79 20 74 68 65 20 73 61 6d 65 20 61  actly the same a
1c630 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c  s calling.** sql
1c640 69 74 65 33 5f 66 72 65 65 28 50 29 20 77 68 65  ite3_free(P) whe
1c650 72 65 20 50 20 69 73 20 74 68 65 20 66 69 72 73  re P is the firs
1c660 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  t parameter to s
1c670 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1c680 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65  ..** ^sqlite3_re
1c690 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 20  alloc() returns 
1c6a0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d  a pointer to a m
1c6b0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
1c6c0 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20  .** of at least 
1c6d0 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20  N bytes in size 
1c6e0 6f 72 20 4e 55 4c 4c 20 69 66 20 73 75 66 66 69  or NULL if suffi
1c6f0 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20  cient memory is 
1c700 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20  unavailable..** 
1c710 5e 49 66 20 4d 20 69 73 20 74 68 65 20 73 69 7a  ^If M is the siz
1c720 65 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61  e of the prior a
1c730 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20  llocation, then 
1c740 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73 0a 2a  min(N,M) bytes.*
1c750 2a 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61  * of the prior a
1c760 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20 63 6f  llocation are co
1c770 70 69 65 64 20 69 6e 74 6f 20 74 68 65 20 62 65  pied into the be
1c780 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66 66 65  ginning of buffe
1c790 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79  r returned.** by
1c7a0 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1c7b0 28 29 20 61 6e 64 20 74 68 65 20 70 72 69 6f 72  () and the prior
1c7c0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66   allocation is f
1c7d0 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c  reed..** ^If sql
1c7e0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72  ite3_realloc() r
1c7f0 65 74 75 72 6e 73 20 4e 55 4c 4c 2c 20 74 68 65  eturns NULL, the
1c800 6e 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f  n the prior allo
1c810 63 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6e 6f 74  cation.** is not
1c820 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54   freed..**.** ^T
1c830 68 65 20 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e  he memory return
1c840 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61  ed by sqlite3_ma
1c850 6c 6c 6f 63 28 29 20 61 6e 64 20 73 71 6c 69 74  lloc() and sqlit
1c860 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20  e3_realloc().** 
1c870 69 73 20 61 6c 77 61 79 73 20 61 6c 69 67 6e 65  is always aligne
1c880 64 20 74 6f 20 61 74 20 6c 65 61 73 74 20 61 6e  d to at least an
1c890 20 38 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79   8 byte boundary
1c8a0 2c 20 6f 72 20 74 6f 20 61 0a 2a 2a 20 34 20 62  , or to a.** 4 b
1c8b0 79 74 65 20 62 6f 75 6e 64 61 72 79 20 69 66 20  yte boundary if 
1c8c0 74 68 65 20 5b 53 51 4c 49 54 45 5f 34 5f 42 59  the [SQLITE_4_BY
1c8d0 54 45 5f 41 4c 49 47 4e 45 44 5f 4d 41 4c 4c 4f  TE_ALIGNED_MALLO
1c8e0 43 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a  C] compile-time.
1c8f0 2a 2a 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65  ** option is use
1c900 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69  d..**.** In SQLi
1c910 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30  te version 3.5.0
1c920 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74 20 77   and 3.5.1, it w
1c930 61 73 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 64  as possible to d
1c940 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53 51 4c  efine.** the SQL
1c950 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f  ITE_OMIT_MEMORY_
1c960 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69 63 68  ALLOCATION which
1c970 20 77 6f 75 6c 64 20 63 61 75 73 65 20 74 68 65   would cause the
1c980 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70   built-in.** imp
1c990 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74  lementation of t
1c9a0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 6f  hese routines to
1c9b0 20 62 65 20 6f 6d 69 74 74 65 64 2e 20 20 54 68   be omitted.  Th
1c9c0 61 74 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a  at capability.**
1c9d0 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 70 72   is no longer pr
1c9e0 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20 62 75  ovided.  Only bu
1c9f0 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c  ilt-in memory al
1ca00 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20 62 65 20  locators can be 
1ca10 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  used..**.** The 
1ca20 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65 72  Windows OS inter
1ca30 66 61 63 65 20 6c 61 79 65 72 20 63 61 6c 6c 73  face layer calls
1ca40 0a 2a 2a 20 74 68 65 20 73 79 73 74 65 6d 20 6d  .** the system m
1ca50 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65  alloc() and free
1ca60 28 29 20 64 69 72 65 63 74 6c 79 20 77 68 65 6e  () directly when
1ca70 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a 20 66   converting.** f
1ca80 69 6c 65 6e 61 6d 65 73 20 62 65 74 77 65 65 6e  ilenames between
1ca90 20 74 68 65 20 55 54 46 2d 38 20 65 6e 63 6f 64   the UTF-8 encod
1caa0 69 6e 67 20 75 73 65 64 20 62 79 20 53 51 4c 69  ing used by SQLi
1cab0 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74 65 76  te.** and whatev
1cac0 65 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e 63 6f  er filename enco
1cad0 64 69 6e 67 20 69 73 20 75 73 65 64 20 62 79 20  ding is used by 
1cae0 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 57  the particular W
1caf0 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 61 6c  indows.** instal
1cb00 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20  lation.  Memory 
1cb10 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72  allocation error
1cb20 73 20 61 72 65 20 64 65 74 65 63 74 65 64 2c 20  s are detected, 
1cb30 62 75 74 0a 2a 2a 20 74 68 65 79 20 61 72 65 20  but.** they are 
1cb40 72 65 70 6f 72 74 65 64 20 62 61 63 6b 20 61 73  reported back as
1cb50 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45   [SQLITE_CANTOPE
1cb60 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45  N] or.** [SQLITE
1cb70 5f 49 4f 45 52 52 5d 20 72 61 74 68 65 72 20 74  _IOERR] rather t
1cb80 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45  han [SQLITE_NOME
1cb90 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f  M]..**.** The po
1cba0 69 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 73 20  inter arguments 
1cbb0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  to [sqlite3_free
1cbc0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
1cbd0 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d  _realloc()].** m
1cbe0 75 73 74 20 62 65 20 65 69 74 68 65 72 20 4e 55  ust be either NU
1cbf0 4c 4c 20 6f 72 20 65 6c 73 65 20 70 6f 69 6e 74  LL or else point
1cc00 65 72 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ers obtained fro
1cc10 6d 20 61 20 70 72 69 6f 72 0a 2a 2a 20 69 6e 76  m a prior.** inv
1cc20 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69  ocation of [sqli
1cc30 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72  te3_malloc()] or
1cc40 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
1cc50 63 28 29 5d 20 74 68 61 74 20 68 61 76 65 0a 2a  c()] that have.*
1cc60 2a 20 6e 6f 74 20 79 65 74 20 62 65 65 6e 20 72  * not yet been r
1cc70 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  eleased..**.** T
1cc80 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
1cc90 75 73 74 20 6e 6f 74 20 72 65 61 64 20 6f 72 20  ust not read or 
1cca0 77 72 69 74 65 20 61 6e 79 20 70 61 72 74 20 6f  write any part o
1ccb0 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f 66 20  f.** a block of 
1ccc0 6d 65 6d 6f 72 79 20 61 66 74 65 72 20 69 74 20  memory after it 
1ccd0 68 61 73 20 62 65 65 6e 20 72 65 6c 65 61 73 65  has been release
1cce0 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  d using.** [sqli
1ccf0 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 72 20 5b  te3_free()] or [
1cd00 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1cd10 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  )]..*/.SQLITE_AP
1cd20 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  I void *sqlite3_
1cd30 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 53 51 4c  malloc(int);.SQL
1cd40 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71  ITE_API void *sq
1cd50 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f  lite3_realloc(vo
1cd60 69 64 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54  id*, int);.SQLIT
1cd70 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74  E_API void sqlit
1cd80 65 33 5f 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a  e3_free(void*);.
1cd90 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1cda0 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f   Memory Allocato
1cdb0 72 20 53 74 61 74 69 73 74 69 63 73 0a 2a 2a 0a  r Statistics.**.
1cdc0 2a 2a 20 53 51 4c 69 74 65 20 70 72 6f 76 69 64  ** SQLite provid
1cdd0 65 73 20 74 68 65 73 65 20 74 77 6f 20 69 6e 74  es these two int
1cde0 65 72 66 61 63 65 73 20 66 6f 72 20 72 65 70 6f  erfaces for repo
1cdf0 72 74 69 6e 67 20 6f 6e 20 74 68 65 20 73 74 61  rting on the sta
1ce00 74 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73  tus.** of the [s
1ce10 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
1ce20 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  , [sqlite3_free(
1ce30 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  )], and [sqlite3
1ce40 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72  _realloc()].** r
1ce50 6f 75 74 69 6e 65 73 2c 20 77 68 69 63 68 20 66  outines, which f
1ce60 6f 72 6d 20 74 68 65 20 62 75 69 6c 74 2d 69 6e  orm the built-in
1ce70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
1ce80 6f 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a 2a 2a  on subsystem..**
1ce90 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  .** ^The [sqlite
1cea0 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
1ceb0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
1cec0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
1ced0 79 74 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72  ytes.** of memor
1cee0 79 20 63 75 72 72 65 6e 74 6c 79 20 6f 75 74 73  y currently outs
1cef0 74 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65  tanding (malloce
1cf00 64 20 62 75 74 20 6e 6f 74 20 66 72 65 65 64 29  d but not freed)
1cf10 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74  ..** ^The [sqlit
1cf20 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
1cf30 74 65 72 28 29 5d 20 72 6f 75 74 69 6e 65 20 72  ter()] routine r
1cf40 65 74 75 72 6e 73 20 74 68 65 20 6d 61 78 69 6d  eturns the maxim
1cf50 75 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 5b  um.** value of [
1cf60 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
1cf70 73 65 64 28 29 5d 20 73 69 6e 63 65 20 74 68 65  sed()] since the
1cf80 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b   high-water mark
1cf90 0a 2a 2a 20 77 61 73 20 6c 61 73 74 20 72 65 73  .** was last res
1cfa0 65 74 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 73  et.  ^The values
1cfb0 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
1cfc0 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
1cfd0 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  d()] and.** [sql
1cfe0 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
1cff0 77 61 74 65 72 28 29 5d 20 69 6e 63 6c 75 64 65  water()] include
1d000 20 61 6e 79 20 6f 76 65 72 68 65 61 64 0a 2a 2a   any overhead.**
1d010 20 61 64 64 65 64 20 62 79 20 53 51 4c 69 74 65   added by SQLite
1d020 20 69 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e   in its implemen
1d030 74 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74  tation of [sqlit
1d040 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a  e3_malloc()],.**
1d050 20 62 75 74 20 6e 6f 74 20 6f 76 65 72 68 65 61   but not overhea
1d060 64 20 61 64 64 65 64 20 62 79 20 74 68 65 20 61  d added by the a
1d070 6e 79 20 75 6e 64 65 72 6c 79 69 6e 67 20 73 79  ny underlying sy
1d080 73 74 65 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20  stem library.** 
1d090 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 5b 73  routines that [s
1d0a0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
1d0b0 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a   may call..**.**
1d0c0 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 68 69 67   ^The memory hig
1d0d0 68 2d 77 61 74 65 72 20 6d 61 72 6b 20 69 73 20  h-water mark is 
1d0e0 72 65 73 65 74 20 74 6f 20 74 68 65 20 63 75 72  reset to the cur
1d0f0 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a  rent value of.**
1d100 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
1d110 5f 75 73 65 64 28 29 5d 20 69 66 20 61 6e 64 20  _used()] if and 
1d120 6f 6e 6c 79 20 69 66 20 74 68 65 20 70 61 72 61  only if the para
1d130 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c  meter to.** [sql
1d140 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
1d150 77 61 74 65 72 28 29 5d 20 69 73 20 74 72 75 65  water()] is true
1d160 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 20 72 65  .  ^The value re
1d170 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 5b 73 71  turned.** by [sq
1d180 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
1d190 68 77 61 74 65 72 28 31 29 5d 20 69 73 20 74 68  hwater(1)] is th
1d1a0 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72  e high-water mar
1d1b0 6b 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 74 68  k.** prior to th
1d1c0 65 20 72 65 73 65 74 2e 0a 2a 2f 0a 53 51 4c 49  e reset..*/.SQLI
1d1d0 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69  TE_API sqlite3_i
1d1e0 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d  nt64 sqlite3_mem
1d1f0 6f 72 79 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a  ory_used(void);.
1d200 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74  SQLITE_API sqlit
1d210 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
1d220 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
1d230 72 28 69 6e 74 20 72 65 73 65 74 46 6c 61 67 29  r(int resetFlag)
1d240 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1d250 46 3a 20 50 73 65 75 64 6f 2d 52 61 6e 64 6f 6d  F: Pseudo-Random
1d260 20 4e 75 6d 62 65 72 20 47 65 6e 65 72 61 74 6f   Number Generato
1d270 72 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63  r.**.** SQLite c
1d280 6f 6e 74 61 69 6e 73 20 61 20 68 69 67 68 2d 71  ontains a high-q
1d290 75 61 6c 69 74 79 20 70 73 65 75 64 6f 2d 72 61  uality pseudo-ra
1d2a0 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67 65 6e 65  ndom number gene
1d2b0 72 61 74 6f 72 20 28 50 52 4e 47 29 20 75 73 65  rator (PRNG) use
1d2c0 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63 74 20 72  d to.** select r
1d2d0 61 6e 64 6f 6d 20 5b 52 4f 57 49 44 20 7c 20 52  andom [ROWID | R
1d2e0 4f 57 49 44 73 5d 20 77 68 65 6e 20 69 6e 73 65  OWIDs] when inse
1d2f0 72 74 69 6e 67 20 6e 65 77 20 72 65 63 6f 72 64  rting new record
1d300 73 20 69 6e 74 6f 20 61 20 74 61 62 6c 65 20 74  s into a table t
1d310 68 61 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 75  hat.** already u
1d320 73 65 73 20 74 68 65 20 6c 61 72 67 65 73 74 20  ses the largest 
1d330 70 6f 73 73 69 62 6c 65 20 5b 52 4f 57 49 44 5d  possible [ROWID]
1d340 2e 20 20 54 68 65 20 50 52 4e 47 20 69 73 20 61  .  The PRNG is a
1d350 6c 73 6f 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20  lso used for.** 
1d360 74 68 65 20 62 75 69 6c 64 2d 69 6e 20 72 61 6e  the build-in ran
1d370 64 6f 6d 28 29 20 61 6e 64 20 72 61 6e 64 6f 6d  dom() and random
1d380 62 6c 6f 62 28 29 20 53 51 4c 20 66 75 6e 63 74  blob() SQL funct
1d390 69 6f 6e 73 2e 20 20 54 68 69 73 20 69 6e 74 65  ions.  This inte
1d3a0 72 66 61 63 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20  rface allows.** 
1d3b0 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 6f 20  applications to 
1d3c0 61 63 63 65 73 73 20 74 68 65 20 73 61 6d 65 20  access the same 
1d3d0 50 52 4e 47 20 66 6f 72 20 6f 74 68 65 72 20 70  PRNG for other p
1d3e0 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e  urposes..**.** ^
1d3f0 41 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 72  A call to this r
1d400 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20 4e 20  outine stores N 
1d410 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e  bytes of randomn
1d420 65 73 73 20 69 6e 74 6f 20 62 75 66 66 65 72 20  ess into buffer 
1d430 50 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  P..**.** ^The fi
1d440 72 73 74 20 74 69 6d 65 20 74 68 69 73 20 72 6f  rst time this ro
1d450 75 74 69 6e 65 20 69 73 20 69 6e 76 6f 6b 65 64  utine is invoked
1d460 20 28 65 69 74 68 65 72 20 69 6e 74 65 72 6e 61   (either interna
1d470 6c 6c 79 20 6f 72 20 62 79 0a 2a 2a 20 74 68 65  lly or by.** the
1d480 20 61 70 70 6c 69 63 61 74 69 6f 6e 29 20 74 68   application) th
1d490 65 20 50 52 4e 47 20 69 73 20 73 65 65 64 65 64  e PRNG is seeded
1d4a0 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73   using randomnes
1d4b0 73 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72  s obtained.** fr
1d4c0 6f 6d 20 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65  om the xRandomne
1d4d0 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65  ss method of the
1d4e0 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65   default [sqlite
1d4f0 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a  3_vfs] object..*
1d500 2a 20 5e 4f 6e 20 61 6c 6c 20 73 75 62 73 65 71  * ^On all subseq
1d510 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 73  uent invocations
1d520 2c 20 74 68 65 20 70 73 65 75 64 6f 2d 72 61 6e  , the pseudo-ran
1d530 64 6f 6d 6e 65 73 73 20 69 73 20 67 65 6e 65 72  domness is gener
1d540 61 74 65 64 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c  ated.** internal
1d550 6c 79 20 61 6e 64 20 77 69 74 68 6f 75 74 20 72  ly and without r
1d560 65 63 6f 75 72 73 65 20 74 6f 20 74 68 65 20 5b  ecourse to the [
1d570 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 52 61  sqlite3_vfs] xRa
1d580 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74 68  ndomness.** meth
1d590 6f 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  od..*/.SQLITE_AP
1d5a0 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  I void sqlite3_r
1d5b0 61 6e 64 6f 6d 6e 65 73 73 28 69 6e 74 20 4e 2c  andomness(int N,
1d5c0 20 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a   void *P);../*.*
1d5d0 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70  * CAPI3REF: Comp
1d5e0 69 6c 65 2d 54 69 6d 65 20 41 75 74 68 6f 72 69  ile-Time Authori
1d5f0 7a 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73  zation Callbacks
1d600 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75  .**.** ^This rou
1d610 74 69 6e 65 20 72 65 67 69 73 74 65 72 73 20 61  tine registers a
1d620 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  n authorizer cal
1d630 6c 62 61 63 6b 20 77 69 74 68 20 61 20 70 61 72  lback with a par
1d640 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61  ticular.** [data
1d650 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
1d660 2c 20 73 75 70 70 6c 69 65 64 20 69 6e 20 74 68  , supplied in th
1d670 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
1d680 2e 0a 2a 2a 20 5e 54 68 65 20 61 75 74 68 6f 72  ..** ^The author
1d690 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
1d6a0 20 69 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c 20   invoked as SQL 
1d6b0 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 62  statements are b
1d6c0 65 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a  eing compiled.**
1d6d0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   by [sqlite3_pre
1d6e0 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76  pare()] or its v
1d6f0 61 72 69 61 6e 74 73 20 5b 73 71 6c 69 74 65 33  ariants [sqlite3
1d700 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a  _prepare_v2()],.
1d710 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
1d720 61 72 65 31 36 28 29 5d 20 61 6e 64 20 5b 73 71  are16()] and [sq
1d730 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
1d740 76 32 28 29 5d 2e 20 20 5e 41 74 20 76 61 72 69  v2()].  ^At vari
1d750 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75  ous.** points du
1d760 72 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 61  ring the compila
1d770 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61 73  tion process, as
1d780 20 6c 6f 67 69 63 20 69 73 20 62 65 69 6e 67 20   logic is being 
1d790 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65  created.** to pe
1d7a0 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 61 63  rform various ac
1d7b0 74 69 6f 6e 73 2c 20 74 68 65 20 61 75 74 68 6f  tions, the autho
1d7c0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
1d7d0 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20  s invoked to.** 
1d7e0 73 65 65 20 69 66 20 74 68 6f 73 65 20 61 63 74  see if those act
1d7f0 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65 64  ions are allowed
1d800 2e 20 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a  .  ^The authoriz
1d810 65 72 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75  er callback shou
1d820 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51  ld.** return [SQ
1d830 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f  LITE_OK] to allo
1d840 77 20 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53  w the action, [S
1d850 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f  QLITE_IGNORE] to
1d860 20 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a   disallow the.**
1d870 20 73 70 65 63 69 66 69 63 20 61 63 74 69 6f 6e   specific action
1d880 20 62 75 74 20 61 6c 6c 6f 77 20 74 68 65 20 53   but allow the S
1d890 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20  QL statement to 
1d8a0 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a  continue to be.*
1d8b0 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b  * compiled, or [
1d8c0 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20  SQLITE_DENY] to 
1d8d0 63 61 75 73 65 20 74 68 65 20 65 6e 74 69 72 65  cause the entire
1d8e0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
1d8f0 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64  o be.** rejected
1d900 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20   with an error. 
1d910 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72 69   ^If the authori
1d920 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  zer callback ret
1d930 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75  urns.** any valu
1d940 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  e other than [SQ
1d950 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53  LITE_IGNORE], [S
1d960 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53  QLITE_OK], or [S
1d970 51 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74  QLITE_DENY].** t
1d980 68 65 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33  hen the [sqlite3
1d990 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
1d9a0 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c  r equivalent cal
1d9b0 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64  l that triggered
1d9c0 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a  .** the authoriz
1d9d0 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74  er will fail wit
1d9e0 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61  h an error messa
1d9f0 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74  ge..**.** When t
1da00 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
1da10 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c  rns [SQLITE_OK],
1da20 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20   that means the 
1da30 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71  operation.** req
1da40 75 65 73 74 65 64 20 69 73 20 6f 6b 2e 20 20 5e  uested is ok.  ^
1da50 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63  When the callbac
1da60 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  k returns [SQLIT
1da70 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20  E_DENY], the.** 
1da80 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1da90 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61  _v2()] or equiva
1daa0 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74  lent call that t
1dab0 72 69 67 67 65 72 65 64 20 74 68 65 0a 2a 2a 20  riggered the.** 
1dac0 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20  authorizer will 
1dad0 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72  fail with an err
1dae0 6f 72 20 6d 65 73 73 61 67 65 20 65 78 70 6c 61  or message expla
1daf0 69 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63  ining that.** ac
1db00 63 65 73 73 20 69 73 20 64 65 6e 69 65 64 2e 20  cess is denied. 
1db10 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
1db20 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  t parameter to t
1db30 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
1db40 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79  llback is a copy
1db50 20 6f 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a   of the third.**
1db60 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
1db70 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  e sqlite3_set_au
1db80 74 68 6f 72 69 7a 65 72 28 29 20 69 6e 74 65 72  thorizer() inter
1db90 66 61 63 65 2e 20 5e 54 68 65 20 73 65 63 6f 6e  face. ^The secon
1dba0 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74  d parameter.** t
1dbb0 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  o the callback i
1dbc0 73 20 61 6e 20 69 6e 74 65 67 65 72 20 5b 53 51  s an integer [SQ
1dbd0 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 69  LITE_COPY | acti
1dbe0 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70  on code] that sp
1dbf0 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 70  ecifies.** the p
1dc00 61 72 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e  articular action
1dc10 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65   to be authorize
1dc20 64 2e 20 5e 54 68 65 20 74 68 69 72 64 20 74 68  d. ^The third th
1dc30 72 6f 75 67 68 20 73 69 78 74 68 20 70 61 72 61  rough sixth para
1dc40 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65  meters.** to the
1dc50 20 63 61 6c 6c 62 61 63 6b 20 61 72 65 20 7a 65   callback are ze
1dc60 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74  ro-terminated st
1dc70 72 69 6e 67 73 20 74 68 61 74 20 63 6f 6e 74 61  rings that conta
1dc80 69 6e 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a  in additional.**
1dc90 20 64 65 74 61 69 6c 73 20 61 62 6f 75 74 20 74   details about t
1dca0 68 65 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20  he action to be 
1dcb0 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a  authorized..**.*
1dcc0 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e  * ^If the action
1dcd0 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45   code is [SQLITE
1dce0 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68  _READ].** and th
1dcf0 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
1dd00 6e 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  ns [SQLITE_IGNOR
1dd10 45 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b  E] then the.** [
1dd20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1dd30 6e 74 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73  nt] statement is
1dd40 20 63 6f 6e 73 74 72 75 63 74 65 64 20 74 6f 20   constructed to 
1dd50 73 75 62 73 74 69 74 75 74 65 0a 2a 2a 20 61 20  substitute.** a 
1dd60 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c  NULL value in pl
1dd70 61 63 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65  ace of the table
1dd80 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75   column that wou
1dd90 6c 64 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20  ld have.** been 
1dda0 72 65 61 64 20 69 66 20 5b 53 51 4c 49 54 45 5f  read if [SQLITE_
1ddb0 4f 4b 5d 20 68 61 64 20 62 65 65 6e 20 72 65 74  OK] had been ret
1ddc0 75 72 6e 65 64 2e 20 20 54 68 65 20 5b 53 51 4c  urned.  The [SQL
1ddd0 49 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72  ITE_IGNORE].** r
1dde0 65 74 75 72 6e 20 63 61 6e 20 62 65 20 75 73 65  eturn can be use
1ddf0 64 20 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74  d to deny an unt
1de00 72 75 73 74 65 64 20 75 73 65 72 20 61 63 63 65  rusted user acce
1de10 73 73 20 74 6f 20 69 6e 64 69 76 69 64 75 61 6c  ss to individual
1de20 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61  .** columns of a
1de30 20 74 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 74   table..** ^If t
1de40 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69  he action code i
1de50 73 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45  s [SQLITE_DELETE
1de60 5d 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61  ] and the callba
1de70 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53  ck returns.** [S
1de80 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68  QLITE_IGNORE] th
1de90 65 6e 20 74 68 65 20 5b 44 45 4c 45 54 45 5d 20  en the [DELETE] 
1dea0 6f 70 65 72 61 74 69 6f 6e 20 70 72 6f 63 65 65  operation procee
1deb0 64 73 20 62 75 74 20 74 68 65 0a 2a 2a 20 5b 74  ds but the.** [t
1dec0 72 75 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a 61  runcate optimiza
1ded0 74 69 6f 6e 5d 20 69 73 20 64 69 73 61 62 6c 65  tion] is disable
1dee0 64 20 61 6e 64 20 61 6c 6c 20 72 6f 77 73 20 61  d and all rows a
1def0 72 65 20 64 65 6c 65 74 65 64 20 69 6e 64 69 76  re deleted indiv
1df00 69 64 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41  idually..**.** A
1df10 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20  n authorizer is 
1df20 75 73 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74  used when [sqlit
1df30 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65  e3_prepare | pre
1df40 70 61 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73  paring].** SQL s
1df50 74 61 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61  tatements from a
1df60 6e 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72  n untrusted sour
1df70 63 65 2c 20 74 6f 20 65 6e 73 75 72 65 20 74 68  ce, to ensure th
1df80 61 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  at the SQL state
1df90 6d 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20  ments.** do not 
1dfa0 74 72 79 20 74 6f 20 61 63 63 65 73 73 20 64 61  try to access da
1dfb0 74 61 20 74 68 65 79 20 61 72 65 20 6e 6f 74 20  ta they are not 
1dfc0 61 6c 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c 20  allowed to see, 
1dfd0 6f 72 20 74 68 61 74 20 74 68 65 79 20 64 6f 20  or that they do 
1dfe0 6e 6f 74 0a 2a 2a 20 74 72 79 20 74 6f 20 65 78  not.** try to ex
1dff0 65 63 75 74 65 20 6d 61 6c 69 63 69 6f 75 73 20  ecute malicious 
1e000 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20  statements that 
1e010 64 61 6d 61 67 65 20 74 68 65 20 64 61 74 61 62  damage the datab
1e020 61 73 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61  ase.  For.** exa
1e030 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61  mple, an applica
1e040 74 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 61  tion may allow a
1e050 20 75 73 65 72 20 74 6f 20 65 6e 74 65 72 20 61   user to enter a
1e060 72 62 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c 20  rbitrary.** SQL 
1e070 71 75 65 72 69 65 73 20 66 6f 72 20 65 76 61 6c  queries for eval
1e080 75 61 74 69 6f 6e 20 62 79 20 61 20 64 61 74 61  uation by a data
1e090 62 61 73 65 2e 20 20 42 75 74 20 74 68 65 20 61  base.  But the a
1e0a0 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 0a  pplication does.
1e0b0 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74 68 65 20  ** not want the 
1e0c0 75 73 65 72 20 74 6f 20 62 65 20 61 62 6c 65 20  user to be able 
1e0d0 74 6f 20 6d 61 6b 65 20 61 72 62 69 74 72 61 72  to make arbitrar
1e0e0 79 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65  y changes to the
1e0f0 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 41  .** database.  A
1e100 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 75  n authorizer cou
1e110 6c 64 20 74 68 65 6e 20 62 65 20 70 75 74 20 69  ld then be put i
1e120 6e 20 70 6c 61 63 65 20 77 68 69 6c 65 20 74 68  n place while th
1e130 65 0a 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72 65  e.** user-entere
1e140 64 20 53 51 4c 20 69 73 20 62 65 69 6e 67 20 5b  d SQL is being [
1e150 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20  sqlite3_prepare 
1e160 7c 20 70 72 65 70 61 72 65 64 5d 20 74 68 61 74  | prepared] that
1e170 0a 2a 2a 20 64 69 73 61 6c 6c 6f 77 73 20 65 76  .** disallows ev
1e180 65 72 79 74 68 69 6e 67 20 65 78 63 65 70 74 20  erything except 
1e190 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
1e1a0 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69  nts..**.** Appli
1e1b0 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6e 65 65  cations that nee
1e1c0 64 20 74 6f 20 70 72 6f 63 65 73 73 20 53 51 4c  d to process SQL
1e1d0 20 66 72 6f 6d 20 75 6e 74 72 75 73 74 65 64 20   from untrusted 
1e1e0 73 6f 75 72 63 65 73 0a 2a 2a 20 6d 69 67 68 74  sources.** might
1e1f0 20 61 6c 73 6f 20 63 6f 6e 73 69 64 65 72 20 6c   also consider l
1e200 6f 77 65 72 69 6e 67 20 72 65 73 6f 75 72 63 65  owering resource
1e210 20 6c 69 6d 69 74 73 20 75 73 69 6e 67 20 5b 73   limits using [s
1e220 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a  qlite3_limit()].
1e230 2a 2a 20 61 6e 64 20 6c 69 6d 69 74 69 6e 67 20  ** and limiting 
1e240 64 61 74 61 62 61 73 65 20 73 69 7a 65 20 75 73  database size us
1e250 69 6e 67 20 74 68 65 20 5b 6d 61 78 5f 70 61 67  ing the [max_pag
1e260 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41  e_count] [PRAGMA
1e270 5d 0a 2a 2a 20 69 6e 20 61 64 64 69 74 69 6f 6e  ].** in addition
1e280 20 74 6f 20 75 73 69 6e 67 20 61 6e 20 61 75 74   to using an aut
1e290 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  horizer..**.** ^
1e2a0 28 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 61  (Only a single a
1e2b0 75 74 68 6f 72 69 7a 65 72 20 63 61 6e 20 62 65  uthorizer can be
1e2c0 20 69 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20 64   in place on a d
1e2d0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1e2e0 6f 6e 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65 2e  on.** at a time.
1e2f0 20 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 73    Each call to s
1e300 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
1e310 72 69 7a 65 72 20 6f 76 65 72 72 69 64 65 73 20  rizer overrides 
1e320 74 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20  the.** previous 
1e330 63 61 6c 6c 2e 29 5e 20 20 5e 44 69 73 61 62 6c  call.)^  ^Disabl
1e340 65 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  e the authorizer
1e350 20 62 79 20 69 6e 73 74 61 6c 6c 69 6e 67 20 61   by installing a
1e360 20 4e 55 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a   NULL callback..
1e370 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65  ** The authorize
1e380 72 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79  r is disabled by
1e390 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20   default..**.** 
1e3a0 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  The authorizer c
1e3b0 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74  allback must not
1e3c0 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61   do anything tha
1e3d0 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a  t will modify.**
1e3e0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
1e3f0 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e  nnection that in
1e400 76 6f 6b 65 64 20 74 68 65 20 61 75 74 68 6f 72  voked the author
1e410 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a  izer callback..*
1e420 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c  * Note that [sql
1e430 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1e440 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
1e450 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64  step()] both mod
1e460 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74  ify their.** dat
1e470 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1e480 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e  s for the meanin
1e490 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e  g of "modify" in
1e4a0 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e   this paragraph.
1e4b0 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 5b 73 71  .**.** ^When [sq
1e4c0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1e4d0 28 29 5d 20 69 73 20 75 73 65 64 20 74 6f 20 70  ()] is used to p
1e4e0 72 65 70 61 72 65 20 61 20 73 74 61 74 65 6d 65  repare a stateme
1e4f0 6e 74 2c 20 74 68 65 0a 2a 2a 20 73 74 61 74 65  nt, the.** state
1e500 6d 65 6e 74 20 6d 69 67 68 74 20 62 65 20 72 65  ment might be re
1e510 2d 70 72 65 70 61 72 65 64 20 64 75 72 69 6e 67  -prepared during
1e520 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
1e530 5d 20 64 75 65 20 74 6f 20 61 20 0a 2a 2a 20 73  ] due to a .** s
1e540 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 20 20 48  chema change.  H
1e550 65 6e 63 65 2c 20 74 68 65 20 61 70 70 6c 69 63  ence, the applic
1e560 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 65 6e 73  ation should ens
1e570 75 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  ure that the.** 
1e580 63 6f 72 72 65 63 74 20 61 75 74 68 6f 72 69 7a  correct authoriz
1e590 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 6d 61  er callback rema
1e5a0 69 6e 73 20 69 6e 20 70 6c 61 63 65 20 64 75 72  ins in place dur
1e5b0 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ing the [sqlite3
1e5c0 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _step()]..**.** 
1e5d0 5e 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 61  ^Note that the a
1e5e0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1e5f0 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e  ck is invoked on
1e600 6c 79 20 64 75 72 69 6e 67 0a 2a 2a 20 5b 73 71  ly during.** [sq
1e610 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
1e620 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73   or its variants
1e630 2e 20 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e  .  Authorization
1e640 20 69 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f   is not.** perfo
1e650 72 6d 65 64 20 64 75 72 69 6e 67 20 73 74 61 74  rmed during stat
1e660 65 6d 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e  ement evaluation
1e670 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   in [sqlite3_ste
1e680 70 28 29 5d 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20  p()], unless.** 
1e690 61 73 20 73 74 61 74 65 64 20 69 6e 20 74 68 65  as stated in the
1e6a0 20 70 72 65 76 69 6f 75 73 20 70 61 72 61 67 72   previous paragr
1e6b0 61 70 68 2c 20 73 71 6c 69 74 65 33 5f 73 74 65  aph, sqlite3_ste
1e6c0 70 28 29 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73  p() invokes.** s
1e6d0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1e6e0 32 28 29 20 74 6f 20 72 65 70 72 65 70 61 72 65  2() to reprepare
1e6f0 20 61 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74   a statement aft
1e700 65 72 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e  er a schema chan
1e710 67 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  ge..*/.SQLITE_AP
1e720 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 65  I int sqlite3_se
1e730 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a 20 20  t_authorizer(.  
1e740 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74 20  sqlite3*,.  int 
1e750 28 2a 78 41 75 74 68 29 28 76 6f 69 64 2a 2c 69  (*xAuth)(void*,i
1e760 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63  nt,const char*,c
1e770 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74  onst char*,const
1e780 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61   char*,const cha
1e790 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55 73  r*),.  void *pUs
1e7a0 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  erData.);../*.**
1e7b0 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f   CAPI3REF: Autho
1e7c0 72 69 7a 65 72 20 52 65 74 75 72 6e 20 43 6f 64  rizer Return Cod
1e7d0 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71  es.**.** The [sq
1e7e0 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
1e7f0 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65  izer | authorize
1e800 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  r callback funct
1e810 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74  ion] must.** ret
1e820 75 72 6e 20 65 69 74 68 65 72 20 5b 53 51 4c 49  urn either [SQLI
1e830 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66  TE_OK] or one of
1e840 20 74 68 65 73 65 20 74 77 6f 20 63 6f 6e 73 74   these two const
1e850 61 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a  ants in order.**
1e860 20 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69 74   to signal SQLit
1e870 65 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  e whether or not
1e880 20 74 68 65 20 61 63 74 69 6f 6e 20 69 73 20 70   the action is p
1e890 65 72 6d 69 74 74 65 64 2e 20 20 53 65 65 20 74  ermitted.  See t
1e8a0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  he.** [sqlite3_s
1e8b0 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20  et_authorizer | 
1e8c0 61 75 74 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d  authorizer docum
1e8d0 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64  entation] for ad
1e8e0 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f  ditional.** info
1e8f0 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 23 64 65 66  rmation..*/.#def
1e900 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e 59 20  ine SQLITE_DENY 
1e910 20 20 31 20 20 20 2f 2a 20 41 62 6f 72 74 20 74    1   /* Abort t
1e920 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
1e930 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 2a   with an error *
1e940 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1e950 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a 20 44  _IGNORE 2   /* D
1e960 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63 65 73  on't allow acces
1e970 73 2c 20 62 75 74 20 64 6f 6e 27 74 20 67 65 6e  s, but don't gen
1e980 65 72 61 74 65 20 61 6e 20 65 72 72 6f 72 20 2a  erate an error *
1e990 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
1e9a0 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 41 63  F: Authorizer Ac
1e9b0 74 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a  tion Codes.**.**
1e9c0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65   The [sqlite3_se
1e9d0 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 20  t_authorizer()] 
1e9e0 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74  interface regist
1e9f0 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66  ers a callback f
1ea00 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20  unction.** that 
1ea10 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61 75  is invoked to au
1ea20 74 68 6f 72 69 7a 65 20 63 65 72 74 61 69 6e 20  thorize certain 
1ea30 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 63  SQL statement ac
1ea40 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 73  tions.  The.** s
1ea50 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
1ea60 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  to the callback 
1ea70 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f  is an integer co
1ea80 64 65 20 74 68 61 74 20 73 70 65 63 69 66 69 65  de that specifie
1ea90 73 0a 2a 2a 20 77 68 61 74 20 61 63 74 69 6f 6e  s.** what action
1eaa0 20 69 73 20 62 65 69 6e 67 20 61 75 74 68 6f 72   is being author
1eab0 69 7a 65 64 2e 20 20 54 68 65 73 65 20 61 72 65  ized.  These are
1eac0 20 74 68 65 20 69 6e 74 65 67 65 72 20 61 63 74   the integer act
1ead0 69 6f 6e 20 63 6f 64 65 73 20 74 68 61 74 0a 2a  ion codes that.*
1eae0 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  * the authorizer
1eaf0 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62 65   callback may be
1eb00 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54   passed..**.** T
1eb10 68 65 73 65 20 61 63 74 69 6f 6e 20 63 6f 64 65  hese action code
1eb20 20 76 61 6c 75 65 73 20 73 69 67 6e 69 66 79 20   values signify 
1eb30 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70 65  what kind of ope
1eb40 72 61 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 0a  ration is to be.
1eb50 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20  ** authorized.  
1eb60 54 68 65 20 33 72 64 20 61 6e 64 20 34 74 68 20  The 3rd and 4th 
1eb70 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68  parameters to th
1eb80 65 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a  e authorization.
1eb90 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  ** callback func
1eba0 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61 72  tion will be par
1ebb0 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20  ameters or NULL 
1ebc0 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69  depending on whi
1ebd0 63 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 63  ch of these.** c
1ebe0 6f 64 65 73 20 69 73 20 75 73 65 64 20 61 73 20  odes is used as 
1ebf0 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
1ec00 65 74 65 72 2e 20 20 5e 28 54 68 65 20 35 74 68  eter.  ^(The 5th
1ec10 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
1ec20 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20  e.** authorizer 
1ec30 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20  callback is the 
1ec40 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61  name of the data
1ec50 62 61 73 65 20 28 22 6d 61 69 6e 22 2c 20 22 74  base ("main", "t
1ec60 65 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e 29 20 69  emp",.** etc.) i
1ec70 66 20 61 70 70 6c 69 63 61 62 6c 65 2e 29 5e 20  f applicable.)^ 
1ec80 20 5e 54 68 65 20 36 74 68 20 70 61 72 61 6d 65   ^The 6th parame
1ec90 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f  ter to the autho
1eca0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a  rizer callback.*
1ecb0 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  * is the name of
1ecc0 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20   the inner-most 
1ecd0 74 72 69 67 67 65 72 20 6f 72 20 76 69 65 77 20  trigger or view 
1ece0 74 68 61 74 20 69 73 20 72 65 73 70 6f 6e 73 69  that is responsi
1ecf0 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61  ble for.** the a
1ed00 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 6f 72  ccess attempt or
1ed10 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 20 61 63   NULL if this ac
1ed20 63 65 73 73 20 61 74 74 65 6d 70 74 20 69 73 20  cess attempt is 
1ed30 64 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a  directly from.**
1ed40 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63   top-level SQL c
1ed50 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a  ode..*/./*******
1ed60 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1ed70 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1ed80 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a  **** 3rd *******
1ed90 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a  ***** 4th ******
1eda0 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  *****/.#define S
1edb0 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 49 4e 44  QLITE_CREATE_IND
1edc0 45 58 20 20 20 20 20 20 20 20 20 20 31 20 20 20  EX          1   
1edd0 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
1ede0 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
1edf0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1ee00 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 41 42 4c  LITE_CREATE_TABL
1ee10 45 20 20 20 20 20 20 20 20 20 20 32 20 20 20 2f  E          2   /
1ee20 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
1ee30 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1ee40 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1ee50 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f  ITE_CREATE_TEMP_
1ee60 49 4e 44 45 58 20 20 20 20 20 33 20 20 20 2f 2a  INDEX     3   /*
1ee70 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
1ee80 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1ee90 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1eea0 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54  TE_CREATE_TEMP_T
1eeb0 41 42 4c 45 20 20 20 20 20 34 20 20 20 2f 2a 20  ABLE     4   /* 
1eec0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1eed0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1eee0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1eef0 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 52  E_CREATE_TEMP_TR
1ef00 49 47 47 45 52 20 20 20 35 20 20 20 2f 2a 20 54  IGGER   5   /* T
1ef10 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54  rigger Name    T
1ef20 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
1ef30 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1ef40 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 56 49 45  _CREATE_TEMP_VIE
1ef50 57 20 20 20 20 20 20 36 20 20 20 2f 2a 20 56 69  W      6   /* Vi
1ef60 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55  ew Name       NU
1ef70 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1ef80 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1ef90 43 52 45 41 54 45 5f 54 52 49 47 47 45 52 20 20  CREATE_TRIGGER  
1efa0 20 20 20 20 20 20 37 20 20 20 2f 2a 20 54 72 69        7   /* Tri
1efb0 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62  gger Name    Tab
1efc0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
1efd0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
1efe0 52 45 41 54 45 5f 56 49 45 57 20 20 20 20 20 20  REATE_VIEW      
1eff0 20 20 20 20 20 38 20 20 20 2f 2a 20 56 69 65 77       8   /* View
1f000 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c   Name       NULL
1f010 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1f020 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45  define SQLITE_DE
1f030 4c 45 54 45 20 20 20 20 20 20 20 20 20 20 20 20  LETE            
1f040 20 20 20 20 39 20 20 20 2f 2a 20 54 61 62 6c 65      9   /* Table
1f050 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
1f060 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1f070 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
1f080 50 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20  P_INDEX         
1f090 20 20 31 30 20 20 20 2f 2a 20 49 6e 64 65 78 20    10   /* Index 
1f0a0 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20  Name      Table 
1f0b0 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
1f0c0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
1f0d0 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20  _TABLE          
1f0e0 20 31 31 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   11   /* Table N
1f0f0 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
1f100 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1f110 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
1f120 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 20  TEMP_INDEX      
1f130 31 32 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61  12   /* Index Na
1f140 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61  me      Table Na
1f150 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
1f160 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
1f170 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 20 31  EMP_TABLE      1
1f180 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  3   /* Table Nam
1f190 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
1f1a0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1f1b0 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45  e SQLITE_DROP_TE
1f1c0 4d 50 5f 54 52 49 47 47 45 52 20 20 20 20 31 34  MP_TRIGGER    14
1f1d0 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61     /* Trigger Na
1f1e0 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  me    Table Name
1f1f0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1f200 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d   SQLITE_DROP_TEM
1f210 50 5f 56 49 45 57 20 20 20 20 20 20 20 31 35 20  P_VIEW       15 
1f220 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20    /* View Name  
1f230 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1f240 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1f250 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49 47  SQLITE_DROP_TRIG
1f260 47 45 52 20 20 20 20 20 20 20 20 20 31 36 20 20  GER         16  
1f270 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65   /* Trigger Name
1f280 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
1f290 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1f2a0 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45 57 20  QLITE_DROP_VIEW 
1f2b0 20 20 20 20 20 20 20 20 20 20 20 31 37 20 20 20             17   
1f2c0 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20  /* View Name    
1f2d0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1f2e0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1f2f0 4c 49 54 45 5f 49 4e 53 45 52 54 20 20 20 20 20  LITE_INSERT     
1f300 20 20 20 20 20 20 20 20 20 20 31 38 20 20 20 2f            18   /
1f310 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
1f320 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1f330 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1f340 49 54 45 5f 50 52 41 47 4d 41 20 20 20 20 20 20  ITE_PRAGMA      
1f350 20 20 20 20 20 20 20 20 20 31 39 20 20 20 2f 2a           19   /*
1f360 20 50 72 61 67 6d 61 20 4e 61 6d 65 20 20 20 20   Pragma Name    
1f370 20 31 73 74 20 61 72 67 20 6f 72 20 4e 55 4c 4c   1st arg or NULL
1f380 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1f390 54 45 5f 52 45 41 44 20 20 20 20 20 20 20 20 20  TE_READ         
1f3a0 20 20 20 20 20 20 20 20 32 30 20 20 20 2f 2a 20          20   /* 
1f3b0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1f3c0 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20  Column Name     
1f3d0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1f3e0 45 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 20  E_SELECT        
1f3f0 20 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4e         21   /* N
1f400 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e  ULL            N
1f410 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1f420 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1f430 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20 20 20 20  _TRANSACTION    
1f440 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20 4f 70        22   /* Op
1f450 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20 4e 55  eration       NU
1f460 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1f470 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1f480 55 50 44 41 54 45 20 20 20 20 20 20 20 20 20 20  UPDATE          
1f490 20 20 20 20 20 32 33 20 20 20 2f 2a 20 54 61 62       23   /* Tab
1f4a0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c  le Name      Col
1f4b0 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a  umn Name     */.
1f4c0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
1f4d0 54 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20  TTACH           
1f4e0 20 20 20 20 32 34 20 20 20 2f 2a 20 46 69 6c 65      24   /* File
1f4f0 6e 61 6d 65 20 20 20 20 20 20 20 20 4e 55 4c 4c  name        NULL
1f500 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1f510 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45  define SQLITE_DE
1f520 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20  TACH            
1f530 20 20 20 32 35 20 20 20 2f 2a 20 44 61 74 61 62     25   /* Datab
1f540 61 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20  ase Name   NULL 
1f550 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1f560 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c 54  efine SQLITE_ALT
1f570 45 52 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20  ER_TABLE        
1f580 20 20 32 36 20 20 20 2f 2a 20 44 61 74 61 62 61    26   /* Databa
1f590 73 65 20 4e 61 6d 65 20 20 20 54 61 62 6c 65 20  se Name   Table 
1f5a0 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
1f5b0 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 49 4e  fine SQLITE_REIN
1f5c0 44 45 58 20 20 20 20 20 20 20 20 20 20 20 20 20  DEX             
1f5d0 20 32 37 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e   27   /* Index N
1f5e0 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
1f5f0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1f600 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c 59  ine SQLITE_ANALY
1f610 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ZE              
1f620 32 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  28   /* Table Na
1f630 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
1f640 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1f650 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
1f660 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 32  _VTABLE        2
1f670 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  9   /* Table Nam
1f680 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61  e      Module Na
1f690 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  me     */.#defin
1f6a0 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 54  e SQLITE_DROP_VT
1f6b0 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 33 30  ABLE          30
1f6c0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
1f6d0 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d        Module Nam
1f6e0 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  e     */.#define
1f6f0 20 53 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f 4e   SQLITE_FUNCTION
1f700 20 20 20 20 20 20 20 20 20 20 20 20 20 33 31 20               31 
1f710 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20    /* NULL       
1f720 20 20 20 20 20 46 75 6e 63 74 69 6f 6e 20 4e 61       Function Na
1f730 6d 65 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20  me   */.#define 
1f740 53 51 4c 49 54 45 5f 53 41 56 45 50 4f 49 4e 54  SQLITE_SAVEPOINT
1f750 20 20 20 20 20 20 20 20 20 20 20 20 33 32 20 20              32  
1f760 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20   /* Operation   
1f770 20 20 20 20 53 61 76 65 70 6f 69 6e 74 20 4e 61      Savepoint Na
1f780 6d 65 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  me  */.#define S
1f790 51 4c 49 54 45 5f 43 4f 50 59 20 20 20 20 20 20  QLITE_COPY      
1f7a0 20 20 20 20 20 20 20 20 20 20 20 20 30 20 20 20              0   
1f7b0 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65  /* No longer use
1f7c0 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d */../*.** CAPI
1f7d0 33 52 45 46 3a 20 54 72 61 63 69 6e 67 20 41 6e  3REF: Tracing An
1f7e0 64 20 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63  d Profiling Func
1f7f0 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tions.**.** Thes
1f800 65 20 72 6f 75 74 69 6e 65 73 20 72 65 67 69 73  e routines regis
1f810 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  ter callback fun
1f820 63 74 69 6f 6e 73 20 74 68 61 74 20 63 61 6e 20  ctions that can 
1f830 62 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74  be used for.** t
1f840 72 61 63 69 6e 67 20 61 6e 64 20 70 72 6f 66 69  racing and profi
1f850 6c 69 6e 67 20 74 68 65 20 65 78 65 63 75 74 69  ling the executi
1f860 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d  on of SQL statem
1f870 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ents..**.** ^The
1f880 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
1f890 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79  on registered by
1f8a0 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29   sqlite3_trace()
1f8b0 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a 2a   is invoked at.*
1f8c0 2a 20 76 61 72 69 6f 75 73 20 74 69 6d 65 73 20  * various times 
1f8d0 77 68 65 6e 20 61 6e 20 53 51 4c 20 73 74 61 74  when an SQL stat
1f8e0 65 6d 65 6e 74 20 69 73 20 62 65 69 6e 67 20 72  ement is being r
1f8f0 75 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73  un by [sqlite3_s
1f900 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20  tep()]..** ^The 
1f910 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20  sqlite3_trace() 
1f920 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
1f930 6b 65 64 20 77 69 74 68 20 61 20 55 54 46 2d 38  ked with a UTF-8
1f940 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68   rendering of th
1f950 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65  e.** SQL stateme
1f960 6e 74 20 74 65 78 74 20 61 73 20 74 68 65 20 73  nt text as the s
1f970 74 61 74 65 6d 65 6e 74 20 66 69 72 73 74 20 62  tatement first b
1f980 65 67 69 6e 73 20 65 78 65 63 75 74 69 6e 67 2e  egins executing.
1f990 0a 2a 2a 20 5e 28 41 64 64 69 74 69 6f 6e 61 6c  .** ^(Additional
1f9a0 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29   sqlite3_trace()
1f9b0 20 63 61 6c 6c 62 61 63 6b 73 20 6d 69 67 68 74   callbacks might
1f9c0 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20 65 61 63   occur.** as eac
1f9d0 68 20 74 72 69 67 67 65 72 65 64 20 73 75 62 70  h triggered subp
1f9e0 72 6f 67 72 61 6d 20 69 73 20 65 6e 74 65 72 65  rogram is entere
1f9f0 64 2e 20 20 54 68 65 20 63 61 6c 6c 62 61 63 6b  d.  The callback
1fa00 73 20 66 6f 72 20 74 72 69 67 67 65 72 73 0a 2a  s for triggers.*
1fa10 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55 54 46 2d  * contain a UTF-
1fa20 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 68  8 SQL comment th
1fa30 61 74 20 69 64 65 6e 74 69 66 69 65 73 20 74 68  at identifies th
1fa40 65 20 74 72 69 67 67 65 72 2e 29 5e 0a 2a 2a 0a  e trigger.)^.**.
1fa50 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b  ** ^The callback
1fa60 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74   function regist
1fa70 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  ered by sqlite3_
1fa80 70 72 6f 66 69 6c 65 28 29 20 69 73 20 69 6e 76  profile() is inv
1fa90 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61 63 68 20  oked.** as each 
1faa0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 69  SQL statement fi
1fab0 6e 69 73 68 65 73 2e 20 20 5e 54 68 65 20 70 72  nishes.  ^The pr
1fac0 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63  ofile callback c
1fad0 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f  ontains.** the o
1fae0 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e  riginal statemen
1faf0 74 20 74 65 78 74 20 61 6e 64 20 61 6e 20 65 73  t text and an es
1fb00 74 69 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63  timate of wall-c
1fb10 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20  lock time.** of 
1fb20 68 6f 77 20 6c 6f 6e 67 20 74 68 61 74 20 73 74  how long that st
1fb30 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20  atement took to 
1fb40 72 75 6e 2e 20 20 5e 54 68 65 20 70 72 6f 66 69  run.  ^The profi
1fb50 6c 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74  le callback.** t
1fb60 69 6d 65 20 69 73 20 69 6e 20 75 6e 69 74 73 20  ime is in units 
1fb70 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c 20  of nanoseconds, 
1fb80 68 6f 77 65 76 65 72 20 74 68 65 20 63 75 72 72  however the curr
1fb90 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ent implementati
1fba0 6f 6e 0a 2a 2a 20 69 73 20 6f 6e 6c 79 20 63 61  on.** is only ca
1fbb0 70 61 62 6c 65 20 6f 66 20 6d 69 6c 6c 69 73 65  pable of millise
1fbc0 63 6f 6e 64 20 72 65 73 6f 6c 75 74 69 6f 6e 20  cond resolution 
1fbd0 73 6f 20 74 68 65 20 73 69 78 20 6c 65 61 73 74  so the six least
1fbe0 20 73 69 67 6e 69 66 69 63 61 6e 74 0a 2a 2a 20   significant.** 
1fbf0 64 69 67 69 74 73 20 69 6e 20 74 68 65 20 74 69  digits in the ti
1fc00 6d 65 20 61 72 65 20 6d 65 61 6e 69 6e 67 6c 65  me are meaningle
1fc10 73 73 2e 20 20 46 75 74 75 72 65 20 76 65 72 73  ss.  Future vers
1fc20 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a  ions of SQLite.*
1fc30 2a 20 6d 69 67 68 74 20 70 72 6f 76 69 64 65 20  * might provide 
1fc40 67 72 65 61 74 65 72 20 72 65 73 6f 6c 75 74 69  greater resoluti
1fc50 6f 6e 20 6f 6e 20 74 68 65 20 70 72 6f 66 69 6c  on on the profil
1fc60 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20 20 54 68  er callback.  Th
1fc70 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 6f  e.** sqlite3_pro
1fc80 66 69 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20  file() function 
1fc90 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 65 78  is considered ex
1fca0 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69  perimental and i
1fcb0 73 0a 2a 2a 20 73 75 62 6a 65 63 74 20 74 6f 20  s.** subject to 
1fcc0 63 68 61 6e 67 65 20 69 6e 20 66 75 74 75 72 65  change in future
1fcd0 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
1fce0 69 74 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ite..*/.SQLITE_A
1fcf0 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  PI void *sqlite3
1fd00 5f 74 72 61 63 65 28 73 71 6c 69 74 65 33 2a 2c  _trace(sqlite3*,
1fd10 20 76 6f 69 64 28 2a 78 54 72 61 63 65 29 28 76   void(*xTrace)(v
1fd20 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  oid*,const char*
1fd30 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54  ), void*);.SQLIT
1fd40 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 45 58 50  E_API SQLITE_EXP
1fd50 45 52 49 4d 45 4e 54 41 4c 20 76 6f 69 64 20 2a  ERIMENTAL void *
1fd60 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28  sqlite3_profile(
1fd70 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69  sqlite3*,.   voi
1fd80 64 28 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f 69  d(*xProfile)(voi
1fd90 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73  d*,const char*,s
1fda0 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 2c 20  qlite3_uint64), 
1fdb0 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  void*);../*.** C
1fdc0 41 50 49 33 52 45 46 3a 20 51 75 65 72 79 20 50  API3REF: Query P
1fdd0 72 6f 67 72 65 73 73 20 43 61 6c 6c 62 61 63 6b  rogress Callback
1fde0 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
1fdf0 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61  ite3_progress_ha
1fe00 6e 64 6c 65 72 28 44 2c 4e 2c 58 2c 50 29 20 69  ndler(D,N,X,P) i
1fe10 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20  nterface causes 
1fe20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  the callback.** 
1fe30 66 75 6e 63 74 69 6f 6e 20 58 20 74 6f 20 62 65  function X to be
1fe40 20 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 69   invoked periodi
1fe50 63 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e  cally during lon
1fe60 67 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20  g running calls 
1fe70 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  to.** [sqlite3_e
1fe80 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  xec()], [sqlite3
1fe90 5f 73 74 65 70 28 29 5d 20 61 6e 64 20 5b 73 71  _step()] and [sq
1fea0 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
1feb0 29 5d 20 66 6f 72 0a 2a 2a 20 64 61 74 61 62 61  )] for.** databa
1fec0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e  se connection D.
1fed0 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 75 73 65    An example use
1fee0 20 66 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74   for this.** int
1fef0 65 72 66 61 63 65 20 69 73 20 74 6f 20 6b 65 65  erface is to kee
1ff00 70 20 61 20 47 55 49 20 75 70 64 61 74 65 64 20  p a GUI updated 
1ff10 64 75 72 69 6e 67 20 61 20 6c 61 72 67 65 20 71  during a large q
1ff20 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  uery..**.** ^The
1ff30 20 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20   parameter P is 
1ff40 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 61  passed through a
1ff50 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d  s the only param
1ff60 65 74 65 72 20 74 6f 20 74 68 65 20 0a 2a 2a 20  eter to the .** 
1ff70 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
1ff80 6e 20 58 2e 20 20 5e 54 68 65 20 70 61 72 61 6d  n X.  ^The param
1ff90 65 74 65 72 20 4e 20 69 73 20 74 68 65 20 6e 75  eter N is the nu
1ffa0 6d 62 65 72 20 6f 66 20 0a 2a 2a 20 5b 76 69 72  mber of .** [vir
1ffb0 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 69 6e 73  tual machine ins
1ffc0 74 72 75 63 74 69 6f 6e 73 5d 20 74 68 61 74 20  tructions] that 
1ffd0 61 72 65 20 65 76 61 6c 75 61 74 65 64 20 62 65  are evaluated be
1ffe0 74 77 65 65 6e 20 73 75 63 63 65 73 73 69 76 65  tween successive
1fff0 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20  .** invocations 
20000 6f 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  of the callback 
20010 58 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 61  X..**.** ^Only a
20020 20 73 69 6e 67 6c 65 20 70 72 6f 67 72 65 73 73   single progress
20030 20 68 61 6e 64 6c 65 72 20 6d 61 79 20 62 65 20   handler may be 
20040 64 65 66 69 6e 65 64 20 61 74 20 6f 6e 65 20 74  defined at one t
20050 69 6d 65 20 70 65 72 0a 2a 2a 20 5b 64 61 74 61  ime per.** [data
20060 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
20070 3b 20 73 65 74 74 69 6e 67 20 61 20 6e 65 77 20  ; setting a new 
20080 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
20090 20 63 61 6e 63 65 6c 73 20 74 68 65 0a 2a 2a 20   cancels the.** 
200a0 6f 6c 64 20 6f 6e 65 2e 20 20 5e 53 65 74 74 69  old one.  ^Setti
200b0 6e 67 20 70 61 72 61 6d 65 74 65 72 20 58 20 74  ng parameter X t
200c0 6f 20 4e 55 4c 4c 20 64 69 73 61 62 6c 65 73 20  o NULL disables 
200d0 74 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e  the progress han
200e0 64 6c 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 70 72  dler..** ^The pr
200f0 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 69  ogress handler i
20100 73 20 61 6c 73 6f 20 64 69 73 61 62 6c 65 64 20  s also disabled 
20110 62 79 20 73 65 74 74 69 6e 67 20 4e 20 74 6f 20  by setting N to 
20120 61 20 76 61 6c 75 65 20 6c 65 73 73 0a 2a 2a 20  a value less.** 
20130 74 68 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49  than 1..**.** ^I
20140 66 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 63  f the progress c
20150 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
20160 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70  non-zero, the op
20170 65 72 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e  eration is.** in
20180 74 65 72 72 75 70 74 65 64 2e 20 20 54 68 69 73  terrupted.  This
20190 20 66 65 61 74 75 72 65 20 63 61 6e 20 62 65 20   feature can be 
201a0 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  used to implemen
201b0 74 20 61 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20  t a.** "Cancel" 
201c0 62 75 74 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20  button on a GUI 
201d0 70 72 6f 67 72 65 73 73 20 64 69 61 6c 6f 67 20  progress dialog 
201e0 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70  box..**.** The p
201f0 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20  rogress handler 
20200 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f  callback must no
20210 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68  t do anything th
20220 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a  at will modify.*
20230 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  * the database c
20240 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69  onnection that i
20250 6e 76 6f 6b 65 64 20 74 68 65 20 70 72 6f 67 72  nvoked the progr
20260 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20  ess handler..** 
20270 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74  Note that [sqlit
20280 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
20290 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74   and [sqlite3_st
202a0 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66  ep()] both modif
202b0 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62  y their.** datab
202c0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20  ase connections 
202d0 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20  for the meaning 
202e0 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74  of "modify" in t
202f0 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a  his paragraph..*
20300 2a 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  *.*/.SQLITE_API 
20310 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 70 72 6f  void sqlite3_pro
20320 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 73 71  gress_handler(sq
20330 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74  lite3*, int, int
20340 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64  (*)(void*), void
20350 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
20360 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e  REF: Opening A N
20370 65 77 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e  ew Database Conn
20380 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ection.**.** ^Th
20390 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 70 65  ese routines ope
203a0 6e 20 61 6e 20 53 51 4c 69 74 65 20 64 61 74 61  n an SQLite data
203b0 62 61 73 65 20 66 69 6c 65 20 77 68 6f 73 65 20  base file whose 
203c0 6e 61 6d 65 20 69 73 20 67 69 76 65 6e 20 62 79  name is given by
203d0 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65   the.** filename
203e0 20 61 72 67 75 6d 65 6e 74 2e 20 5e 54 68 65 20   argument. ^The 
203f0 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e  filename argumen
20400 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64  t is interpreted
20410 20 61 73 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a   as UTF-8 for.**
20420 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
20430 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  and sqlite3_open
20440 5f 76 32 28 29 20 61 6e 64 20 61 73 20 55 54 46  _v2() and as UTF
20450 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76  -16 in the nativ
20460 65 20 62 79 74 65 0a 2a 2a 20 6f 72 64 65 72 20  e byte.** order 
20470 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
20480 31 36 28 29 2e 20 5e 28 41 20 5b 64 61 74 61 62  16(). ^(A [datab
20490 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
204a0 68 61 6e 64 6c 65 20 69 73 20 75 73 75 61 6c 6c  handle is usuall
204b0 79 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 6e  y.** returned in
204c0 20 2a 70 70 44 62 2c 20 65 76 65 6e 20 69 66 20   *ppDb, even if 
204d0 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e  an error occurs.
204e0 20 20 54 68 65 20 6f 6e 6c 79 20 65 78 63 65 70    The only excep
204f0 74 69 6f 6e 20 69 73 20 74 68 61 74 0a 2a 2a 20  tion is that.** 
20500 69 66 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61  if SQLite is una
20510 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20  ble to allocate 
20520 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74  memory to hold t
20530 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a  he [sqlite3] obj
20540 65 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77  ect,.** a NULL w
20550 69 6c 6c 20 62 65 20 77 72 69 74 74 65 6e 20 69  ill be written i
20560 6e 74 6f 20 2a 70 70 44 62 20 69 6e 73 74 65 61  nto *ppDb instea
20570 64 20 6f 66 20 61 20 70 6f 69 6e 74 65 72 20 74  d of a pointer t
20580 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 0a  o the [sqlite3].
20590 2a 2a 20 6f 62 6a 65 63 74 2e 29 5e 20 5e 28 49  ** object.)^ ^(I
205a0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  f the database i
205b0 73 20 6f 70 65 6e 65 64 20 28 61 6e 64 2f 6f 72  s opened (and/or
205c0 20 63 72 65 61 74 65 64 29 20 73 75 63 63 65 73   created) succes
205d0 73 66 75 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20  sfully, then.** 
205e0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72  [SQLITE_OK] is r
205f0 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77  eturned.  Otherw
20600 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f  ise an [error co
20610 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  de] is returned.
20620 29 5e 20 5e 54 68 65 0a 2a 2a 20 5b 73 71 6c 69  )^ ^The.** [sqli
20630 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72  te3_errmsg()] or
20640 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
20650 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 63  16()] routines c
20660 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62  an be used to ob
20670 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69  tain.** an Engli
20680 73 68 20 6c 61 6e 67 75 61 67 65 20 64 65 73 63  sh language desc
20690 72 69 70 74 69 6f 6e 20 6f 66 20 74 68 65 20 65  ription of the e
206a0 72 72 6f 72 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  rror following a
206b0 20 66 61 69 6c 75 72 65 20 6f 66 20 61 6e 79 0a   failure of any.
206c0 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  ** of the sqlite
206d0 33 5f 6f 70 65 6e 28 29 20 72 6f 75 74 69 6e 65  3_open() routine
206e0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65  s..**.** ^The de
206f0 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 66  fault encoding f
20700 6f 72 20 74 68 65 20 64 61 74 61 62 61 73 65 20  or the database 
20710 77 69 6c 6c 20 62 65 20 55 54 46 2d 38 20 69 66  will be UTF-8 if
20720 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  .** sqlite3_open
20730 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  () or sqlite3_op
20740 65 6e 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65  en_v2() is calle
20750 64 20 61 6e 64 0a 2a 2a 20 55 54 46 2d 31 36 20  d and.** UTF-16 
20760 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79  in the native by
20770 74 65 20 6f 72 64 65 72 20 69 66 20 73 71 6c 69  te order if sqli
20780 74 65 33 5f 6f 70 65 6e 31 36 28 29 20 69 73 20  te3_open16() is 
20790 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74  used..**.** Whet
207a0 68 65 72 20 6f 72 20 6e 6f 74 20 61 6e 20 65 72  her or not an er
207b0 72 6f 72 20 6f 63 63 75 72 73 20 77 68 65 6e 20  ror occurs when 
207c0 69 74 20 69 73 20 6f 70 65 6e 65 64 2c 20 72 65  it is opened, re
207d0 73 6f 75 72 63 65 73 0a 2a 2a 20 61 73 73 6f 63  sources.** assoc
207e0 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 5b  iated with the [
207f0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
20800 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 73 68 6f 75  ion] handle shou
20810 6c 64 20 62 65 20 72 65 6c 65 61 73 65 64 20 62  ld be released b
20820 79 0a 2a 2a 20 70 61 73 73 69 6e 67 20 69 74 20  y.** passing it 
20830 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73  to [sqlite3_clos
20840 65 28 29 5d 20 77 68 65 6e 20 69 74 20 69 73 20  e()] when it is 
20850 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71 75 69 72  no longer requir
20860 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ed..**.** The sq
20870 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
20880 69 6e 74 65 72 66 61 63 65 20 77 6f 72 6b 73 20  interface works 
20890 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 6f 70 65  like sqlite3_ope
208a0 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74 20 74 68  n().** except th
208b0 61 74 20 69 74 20 61 63 63 65 70 74 73 20 74 77  at it accepts tw
208c0 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 70 61 72  o additional par
208d0 61 6d 65 74 65 72 73 20 66 6f 72 20 61 64 64 69  ameters for addi
208e0 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a  tional control.*
208f0 2a 20 6f 76 65 72 20 74 68 65 20 6e 65 77 20 64  * over the new d
20900 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
20910 6f 6e 2e 20 20 5e 28 54 68 65 20 66 6c 61 67 73  on.  ^(The flags
20920 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
20930 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
20940 28 29 20 63 61 6e 20 74 61 6b 65 20 6f 6e 65 20  () can take one 
20950 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77  of.** the follow
20960 69 6e 67 20 74 68 72 65 65 20 76 61 6c 75 65 73  ing three values
20970 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d  , optionally com
20980 62 69 6e 65 64 20 77 69 74 68 20 74 68 65 20 0a  bined with the .
20990 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
209a0 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54  NOMUTEX], [SQLIT
209b0 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58  E_OPEN_FULLMUTEX
209c0 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ], [SQLITE_OPEN_
209d0 53 48 41 52 45 44 43 41 43 48 45 5d 2c 0a 2a 2a  SHAREDCACHE],.**
209e0 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f   and/or [SQLITE_
209f0 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48  OPEN_PRIVATECACH
20a00 45 5d 20 66 6c 61 67 73 3a 29 5e 0a 2a 2a 0a 2a  E] flags:)^.**.*
20a10 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e  * <dl>.** ^(<dt>
20a20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
20a30 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c  DONLY]</dt>.** <
20a40 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20  dd>The database 
20a50 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 72 65 61  is opened in rea
20a60 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20 49 66  d-only mode.  If
20a70 20 74 68 65 20 64 61 74 61 62 61 73 65 20 64 6f   the database do
20a80 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61 64  es not.** alread
20a90 79 20 65 78 69 73 74 2c 20 61 6e 20 65 72 72 6f  y exist, an erro
20aa0 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f  r is returned.</
20ab0 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64  dd>)^.**.** ^(<d
20ac0 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  t>[SQLITE_OPEN_R
20ad0 45 41 44 57 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a  EADWRITE]</dt>.*
20ae0 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61  * <dd>The databa
20af0 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72  se is opened for
20b00 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69   reading and wri
20b10 74 69 6e 67 20 69 66 20 70 6f 73 73 69 62 6c 65  ting if possible
20b20 2c 20 6f 72 20 72 65 61 64 69 6e 67 0a 2a 2a 20  , or reading.** 
20b30 6f 6e 6c 79 20 69 66 20 74 68 65 20 66 69 6c 65  only if the file
20b40 20 69 73 20 77 72 69 74 65 20 70 72 6f 74 65 63   is write protec
20b50 74 65 64 20 62 79 20 74 68 65 20 6f 70 65 72 61  ted by the opera
20b60 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 49 6e  ting system.  In
20b70 20 65 69 74 68 65 72 0a 2a 2a 20 63 61 73 65 20   either.** case 
20b80 74 68 65 20 64 61 74 61 62 61 73 65 20 6d 75 73  the database mus
20b90 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c  t already exist,
20ba0 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 65 72   otherwise an er
20bb0 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ror is returned.
20bc0 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28  </dd>)^.**.** ^(
20bd0 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  <dt>[SQLITE_OPEN
20be0 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53  _READWRITE] | [S
20bf0 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
20c00 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  E]</dt>.** <dd>T
20c10 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
20c20 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e  pened for readin
20c30 67 20 61 6e 64 20 77 72 69 74 69 6e 67 2c 20 61  g and writing, a
20c40 6e 64 20 69 73 20 63 72 65 61 74 65 64 20 69 66  nd is created if
20c50 0a 2a 2a 20 69 74 20 64 6f 65 73 20 6e 6f 74 20  .** it does not 
20c60 61 6c 72 65 61 64 79 20 65 78 69 73 74 2e 20 54  already exist. T
20c70 68 69 73 20 69 73 20 74 68 65 20 62 65 68 61 76  his is the behav
20c80 69 6f 72 20 74 68 61 74 20 69 73 20 61 6c 77 61  ior that is alwa
20c90 79 73 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 73  ys used for.** s
20ca0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e  qlite3_open() an
20cb0 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36  d sqlite3_open16
20cc0 28 29 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f  ().</dd>)^.** </
20cd0 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  dl>.**.** If the
20ce0 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74   3rd parameter t
20cf0 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
20d00 32 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f  2() is not one o
20d10 66 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61  f the.** combina
20d20 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76  tions shown abov
20d30 65 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 20  e or one of the 
20d40 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f  combinations sho
20d50 77 6e 20 61 62 6f 76 65 20 63 6f 6d 62 69 6e 65  wn above combine
20d60 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 53  d.** with the [S
20d70 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54  QLITE_OPEN_NOMUT
20d80 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45  EX], [SQLITE_OPE
20d90 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c 0a 2a 2a  N_FULLMUTEX],.**
20da0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48   [SQLITE_OPEN_SH
20db0 41 52 45 44 43 41 43 48 45 5d 20 61 6e 64 2f 6f  AREDCACHE] and/o
20dc0 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50  r [SQLITE_OPEN_P
20dd0 52 49 56 41 54 45 43 41 43 48 45 5d 20 66 6c 61  RIVATECACHE] fla
20de0 67 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  gs,.** then the 
20df0 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65  behavior is unde
20e00 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  fined..**.** ^If
20e10 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   the [SQLITE_OPE
20e20 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c 61 67 20  N_NOMUTEX] flag 
20e30 69 73 20 73 65 74 2c 20 74 68 65 6e 20 74 68 65  is set, then the
20e40 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
20e50 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e  tion.** opens in
20e60 20 74 68 65 20 6d 75 6c 74 69 2d 74 68 72 65 61   the multi-threa
20e70 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  d [threading mod
20e80 65 5d 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68  e] as long as th
20e90 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 0a  e single-thread.
20ea0 2a 2a 20 6d 6f 64 65 20 68 61 73 20 6e 6f 74 20  ** mode has not 
20eb0 62 65 65 6e 20 73 65 74 20 61 74 20 63 6f 6d 70  been set at comp
20ec0 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72  ile-time or star
20ed0 74 2d 74 69 6d 65 2e 20 20 5e 49 66 20 74 68 65  t-time.  ^If the
20ee0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
20ef0 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66 6c 61 67  _FULLMUTEX] flag
20f00 20 69 73 20 73 65 74 20 74 68 65 6e 20 74 68 65   is set then the
20f10 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
20f20 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e  tion opens.** in
20f30 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20   the serialized 
20f40 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
20f50 20 75 6e 6c 65 73 73 20 73 69 6e 67 6c 65 2d 74   unless single-t
20f60 68 72 65 61 64 20 77 61 73 0a 2a 2a 20 70 72 65  hread was.** pre
20f70 76 69 6f 75 73 6c 79 20 73 65 6c 65 63 74 65 64  viously selected
20f80 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65   at compile-time
20f90 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 0a   or start-time..
20fa0 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
20fb0 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45  OPEN_SHAREDCACHE
20fc0 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20 74 68  ] flag causes th
20fd0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
20fe0 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 65  ction to be.** e
20ff0 6c 69 67 69 62 6c 65 20 74 6f 20 75 73 65 20 5b  ligible to use [
21000 73 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64  shared cache mod
21010 65 5d 2c 20 72 65 67 61 72 64 6c 65 73 73 20 6f  e], regardless o
21020 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
21030 20 73 68 61 72 65 64 0a 2a 2a 20 63 61 63 68 65   shared.** cache
21040 20 69 73 20 65 6e 61 62 6c 65 64 20 75 73 69 6e   is enabled usin
21050 67 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c  g [sqlite3_enabl
21060 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28 29  e_shared_cache()
21070 5d 2e 20 20 5e 54 68 65 0a 2a 2a 20 5b 53 51 4c  ].  ^The.** [SQL
21080 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45  ITE_OPEN_PRIVATE
21090 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73  CACHE] flag caus
210a0 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  es the database 
210b0 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 6e 6f  connection to no
210c0 74 0a 2a 2a 20 70 61 72 74 69 63 69 70 61 74 65  t.** participate
210d0 20 69 6e 20 5b 73 68 61 72 65 64 20 63 61 63 68   in [shared cach
210e0 65 20 6d 6f 64 65 5d 20 65 76 65 6e 20 69 66 20  e mode] even if 
210f0 69 74 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a  it is enabled..*
21100 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c  *.** ^If the fil
21110 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72  ename is ":memor
21120 79 3a 22 2c 20 74 68 65 6e 20 61 20 70 72 69 76  y:", then a priv
21130 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 20 69  ate, temporary i
21140 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73  n-memory databas
21150 65 0a 2a 2a 20 69 73 20 63 72 65 61 74 65 64 20  e.** is created 
21160 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 69  for the connecti
21170 6f 6e 2e 20 20 5e 54 68 69 73 20 69 6e 2d 6d 65  on.  ^This in-me
21180 6d 6f 72 79 20 64 61 74 61 62 61 73 65 20 77 69  mory database wi
21190 6c 6c 20 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a  ll vanish when.*
211a0 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  * the database c
211b0 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f  onnection is clo
211c0 73 65 64 2e 20 20 46 75 74 75 72 65 20 76 65 72  sed.  Future ver
211d0 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20  sions of SQLite 
211e0 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73  might.** make us
211f0 65 20 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c 20  e of additional 
21200 73 70 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65  special filename
21210 73 20 74 68 61 74 20 62 65 67 69 6e 20 77 69 74  s that begin wit
21220 68 20 74 68 65 20 22 3a 22 20 63 68 61 72 61 63  h the ":" charac
21230 74 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65  ter..** It is re
21240 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 77  commended that w
21250 68 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 66  hen a database f
21260 69 6c 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79  ilename actually
21270 20 64 6f 65 73 20 62 65 67 69 6e 20 77 69 74 68   does begin with
21280 0a 2a 2a 20 61 20 22 3a 22 20 63 68 61 72 61 63  .** a ":" charac
21290 74 65 72 20 79 6f 75 20 73 68 6f 75 6c 64 20 70  ter you should p
212a0 72 65 66 69 78 20 74 68 65 20 66 69 6c 65 6e 61  refix the filena
212b0 6d 65 20 77 69 74 68 20 61 20 70 61 74 68 6e 61  me with a pathna
212c0 6d 65 20 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e  me such as.** ".
212d0 2f 22 20 74 6f 20 61 76 6f 69 64 20 61 6d 62 69  /" to avoid ambi
212e0 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  guity..**.** ^If
212f0 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73   the filename is
21300 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
21310 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65  , then a private
21320 2c 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f  , temporary.** o
21330 6e 2d 64 69 73 6b 20 64 61 74 61 62 61 73 65 20  n-disk database 
21340 77 69 6c 6c 20 62 65 20 63 72 65 61 74 65 64 2e  will be created.
21350 20 20 5e 54 68 69 73 20 70 72 69 76 61 74 65 20    ^This private 
21360 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65  database will be
21370 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  .** automaticall
21380 79 20 64 65 6c 65 74 65 64 20 61 73 20 73 6f 6f  y deleted as soo
21390 6e 20 61 73 20 74 68 65 20 64 61 74 61 62 61 73  n as the databas
213a0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
213b0 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  closed..**.** ^T
213c0 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
213d0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f  ter to sqlite3_o
213e0 70 65 6e 5f 76 32 28 29 20 69 73 20 74 68 65 20  pen_v2() is the 
213f0 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b  name of the.** [
21400 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
21410 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 73  ect that defines
21420 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73   the operating s
21430 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20  ystem interface 
21440 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20  that.** the new 
21450 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
21460 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e 20  ion should use. 
21470 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68 20   ^If the fourth 
21480 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20  parameter is.** 
21490 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  a NULL pointer t
214a0 68 65 6e 20 74 68 65 20 64 65 66 61 75 6c 74 20  hen the default 
214b0 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
214c0 6a 65 63 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a  ject is used..**
214d0 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57  .** <b>Note to W
214e0 69 6e 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62  indows users:</b
214f0 3e 20 20 54 68 65 20 65 6e 63 6f 64 69 6e 67 20  >  The encoding 
21500 75 73 65 64 20 66 6f 72 20 74 68 65 20 66 69 6c  used for the fil
21510 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a  ename argument.*
21520 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 70 65  * of sqlite3_ope
21530 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  n() and sqlite3_
21540 6f 70 65 6e 5f 76 32 28 29 20 6d 75 73 74 20 62  open_v2() must b
21550 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61  e UTF-8, not wha
21560 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67  tever.** codepag
21570 65 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 64  e is currently d
21580 65 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d  efined.  Filenam
21590 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e  es containing in
215a0 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63  ternational.** c
215b0 68 61 72 61 63 74 65 72 73 20 6d 75 73 74 20 62  haracters must b
215c0 65 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 55  e converted to U
215d0 54 46 2d 38 20 70 72 69 6f 72 20 74 6f 20 70 61  TF-8 prior to pa
215e0 73 73 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a  ssing them into.
215f0 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ** sqlite3_open(
21600 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65  ) or sqlite3_ope
21610 6e 5f 76 32 28 29 2e 0a 2a 2f 0a 53 51 4c 49 54  n_v2()..*/.SQLIT
21620 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
21630 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 74 20  3_open(.  const 
21640 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20  char *filename, 
21650 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69    /* Database fi
21660 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a  lename (UTF-8) *
21670 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70  /.  sqlite3 **pp
21680 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f  Db          /* O
21690 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61  UT: SQLite db ha
216a0 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54  ndle */.);.SQLIT
216b0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
216c0 33 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73  3_open16(.  cons
216d0 74 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65  t void *filename
216e0 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  ,   /* Database 
216f0 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31 36  filename (UTF-16
21700 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a  ) */.  sqlite3 *
21710 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f  *ppDb          /
21720 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62  * OUT: SQLite db
21730 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 53 51   handle */.);.SQ
21740 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
21750 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 0a 20 20  ite3_open_v2(.  
21760 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65  const char *file
21770 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62  name,   /* Datab
21780 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54  ase filename (UT
21790 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65  F-8) */.  sqlite
217a0 33 20 2a 2a 70 70 44 62 2c 20 20 20 20 20 20 20  3 **ppDb,       
217b0 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65    /* OUT: SQLite
217c0 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20   db handle */.  
217d0 69 6e 74 20 66 6c 61 67 73 2c 20 20 20 20 20 20  int flags,      
217e0 20 20 20 20 20 20 20 20 2f 2a 20 46 6c 61 67 73          /* Flags
217f0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
21800 20 2a 7a 56 66 73 20 20 20 20 20 20 20 20 2f 2a   *zVfs        /*
21810 20 4e 61 6d 65 20 6f 66 20 56 46 53 20 6d 6f 64   Name of VFS mod
21820 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f 0a 29 3b  ule to use */.);
21830 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
21840 3a 20 45 72 72 6f 72 20 43 6f 64 65 73 20 41 6e  : Error Codes An
21850 64 20 4d 65 73 73 61 67 65 73 0a 2a 2a 0a 2a 2a  d Messages.**.**
21860 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72   ^The sqlite3_er
21870 72 63 6f 64 65 28 29 20 69 6e 74 65 72 66 61 63  rcode() interfac
21880 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  e returns the nu
21890 6d 65 72 69 63 20 5b 72 65 73 75 6c 74 20 63 6f  meric [result co
218a0 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e  de] or.** [exten
218b0 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d  ded result code]
218c0 20 66 6f 72 20 74 68 65 20 6d 6f 73 74 20 72 65   for the most re
218d0 63 65 6e 74 20 66 61 69 6c 65 64 20 73 71 6c 69  cent failed sqli
218e0 74 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c 0a 2a  te3_* API call.*
218f0 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  * associated wit
21900 68 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  h a [database co
21910 6e 6e 65 63 74 69 6f 6e 5d 2e 20 49 66 20 61 20  nnection]. If a 
21920 70 72 69 6f 72 20 41 50 49 20 63 61 6c 6c 20 66  prior API call f
21930 61 69 6c 65 64 0a 2a 2a 20 62 75 74 20 74 68 65  ailed.** but the
21940 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 41 50 49   most recent API
21950 20 63 61 6c 6c 20 73 75 63 63 65 65 64 65 64 2c   call succeeded,
21960 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
21970 65 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65  e from.** sqlite
21980 33 5f 65 72 72 63 6f 64 65 28 29 20 69 73 20 75  3_errcode() is u
21990 6e 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 20  ndefined.  ^The 
219a0 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
219b0 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20 69 6e  _errcode().** in
219c0 74 65 72 66 61 63 65 20 69 73 20 74 68 65 20 73  terface is the s
219d0 61 6d 65 20 65 78 63 65 70 74 20 74 68 61 74 20  ame except that 
219e0 69 74 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e  it always return
219f0 73 20 74 68 65 20 0a 2a 2a 20 5b 65 78 74 65 6e  s the .** [exten
21a00 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d  ded result code]
21a10 20 65 76 65 6e 20 77 68 65 6e 20 65 78 74 65 6e   even when exten
21a20 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
21a30 20 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64   are.** disabled
21a40 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
21a50 69 74 65 33 5f 65 72 72 6d 73 67 28 29 20 61 6e  ite3_errmsg() an
21a60 64 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67  d sqlite3_errmsg
21a70 31 36 28 29 20 72 65 74 75 72 6e 20 45 6e 67 6c  16() return Engl
21a80 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a 20  ish-language.** 
21a90 74 65 78 74 20 74 68 61 74 20 64 65 73 63 72 69  text that descri
21aa0 62 65 73 20 74 68 65 20 65 72 72 6f 72 2c 20 61  bes the error, a
21ab0 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f  s either UTF-8 o
21ac0 72 20 55 54 46 2d 31 36 20 72 65 73 70 65 63 74  r UTF-16 respect
21ad0 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f  ively..** ^(Memo
21ae0 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65  ry to hold the e
21af0 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72  rror message str
21b00 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69  ing is managed i
21b10 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68  nternally..** Th
21b20 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f  e application do
21b30 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 77  es not need to w
21b40 6f 72 72 79 20 61 62 6f 75 74 20 66 72 65 65 69  orry about freei
21b50 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a  ng the result..*
21b60 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20 65  * However, the e
21b70 72 72 6f 72 20 73 74 72 69 6e 67 20 6d 69 67 68  rror string migh
21b80 74 20 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e  t be overwritten
21b90 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   or deallocated 
21ba0 62 79 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74  by.** subsequent
21bb0 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65 72 20   calls to other 
21bc0 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
21bd0 20 66 75 6e 63 74 69 6f 6e 73 2e 29 5e 0a 2a 2a   functions.)^.**
21be0 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 73 65 72  .** When the ser
21bf0 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69  ialized [threadi
21c00 6e 67 20 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75  ng mode] is in u
21c10 73 65 2c 20 69 74 20 6d 69 67 68 74 20 62 65 20  se, it might be 
21c20 74 68 65 0a 2a 2a 20 63 61 73 65 20 74 68 61 74  the.** case that
21c30 20 61 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20   a second error 
21c40 6f 63 63 75 72 73 20 6f 6e 20 61 20 73 65 70 61  occurs on a sepa
21c50 72 61 74 65 20 74 68 72 65 61 64 20 69 6e 20 62  rate thread in b
21c60 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69  etween.** the ti
21c70 6d 65 20 6f 66 20 74 68 65 20 66 69 72 73 74 20  me of the first 
21c80 65 72 72 6f 72 20 61 6e 64 20 74 68 65 20 63 61  error and the ca
21c90 6c 6c 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65  ll to these inte
21ca0 72 66 61 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20  rfaces..** When 
21cb0 74 68 61 74 20 68 61 70 70 65 6e 73 2c 20 74 68  that happens, th
21cc0 65 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 77  e second error w
21cd0 69 6c 6c 20 62 65 20 72 65 70 6f 72 74 65 64 20  ill be reported 
21ce0 73 69 6e 63 65 20 74 68 65 73 65 0a 2a 2a 20 69  since these.** i
21cf0 6e 74 65 72 66 61 63 65 73 20 61 6c 77 61 79 73  nterfaces always
21d00 20 72 65 70 6f 72 74 20 74 68 65 20 6d 6f 73 74   report the most
21d10 20 72 65 63 65 6e 74 20 72 65 73 75 6c 74 2e 20   recent result. 
21d20 20 54 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69   To avoid.** thi
21d30 73 2c 20 65 61 63 68 20 74 68 72 65 61 64 20 63  s, each thread c
21d40 61 6e 20 6f 62 74 61 69 6e 20 65 78 63 6c 75 73  an obtain exclus
21d50 69 76 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b  ive use of the [
21d60 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
21d70 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76  ion] D.** by inv
21d80 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d  oking [sqlite3_m
21d90 75 74 65 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c  utex_enter]([sql
21da0 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44  ite3_db_mutex](D
21db0 29 29 20 62 65 66 6f 72 65 20 62 65 67 69 6e 6e  )) before beginn
21dc0 69 6e 67 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20  ing.** to use D 
21dd0 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71  and invoking [sq
21de0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76  lite3_mutex_leav
21df0 65 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d  e]([sqlite3_db_m
21e00 75 74 65 78 5d 28 44 29 29 20 61 66 74 65 72 0a  utex](D)) after.
21e10 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20  ** all calls to 
21e20 74 68 65 20 69 6e 74 65 72 66 61 63 65 73 20 6c  the interfaces l
21e30 69 73 74 65 64 20 68 65 72 65 20 61 72 65 20 63  isted here are c
21e40 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20  ompleted..**.** 
21e50 49 66 20 61 6e 20 69 6e 74 65 72 66 61 63 65 20  If an interface 
21e60 66 61 69 6c 73 20 77 69 74 68 20 53 51 4c 49 54  fails with SQLIT
21e70 45 5f 4d 49 53 55 53 45 2c 20 74 68 61 74 20 6d  E_MISUSE, that m
21e80 65 61 6e 73 20 74 68 65 20 69 6e 74 65 72 66 61  eans the interfa
21e90 63 65 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65  ce.** was invoke
21ea0 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 62 79  d incorrectly by
21eb0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
21ec0 2e 20 20 49 6e 20 74 68 61 74 20 63 61 73 65 2c  .  In that case,
21ed0 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f   the.** error co
21ee0 64 65 20 61 6e 64 20 6d 65 73 73 61 67 65 20 6d  de and message m
21ef0 61 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65  ay or may not be
21f00 20 73 65 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f   set..*/.SQLITE_
21f10 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
21f20 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20  errcode(sqlite3 
21f30 2a 64 62 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  *db);.SQLITE_API
21f40 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74   int sqlite3_ext
21f50 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 73 71  ended_errcode(sq
21f60 6c 69 74 65 33 20 2a 64 62 29 3b 0a 53 51 4c 49  lite3 *db);.SQLI
21f70 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61  TE_API const cha
21f80 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  r *sqlite3_errms
21f90 67 28 73 71 6c 69 74 65 33 2a 29 3b 0a 53 51 4c  g(sqlite3*);.SQL
21fa0 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f  ITE_API const vo
21fb0 69 64 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d  id *sqlite3_errm
21fc0 73 67 31 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a  sg16(sqlite3*);.
21fd0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
21fe0 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 4f   SQL Statement O
21ff0 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44  bject.** KEYWORD
22000 53 3a 20 7b 70 72 65 70 61 72 65 64 20 73 74 61  S: {prepared sta
22010 74 65 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72 65  tement} {prepare
22020 64 20 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a  d statements}.**
22030 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20  .** An instance 
22040 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 72  of this object r
22050 65 70 72 65 73 65 6e 74 73 20 61 20 73 69 6e 67  epresents a sing
22060 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  le SQL statement
22070 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74  ..** This object
22080 20 69 73 20 76 61 72 69 6f 75 73 6c 79 20 6b 6e   is variously kn
22090 6f 77 6e 20 61 73 20 61 20 22 70 72 65 70 61 72  own as a "prepar
220a0 65 64 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72  ed statement" or
220b0 20 61 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65 64 20   a.** "compiled 
220c0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 22 20 6f  SQL statement" o
220d0 72 20 73 69 6d 70 6c 79 20 61 73 20 61 20 22 73  r simply as a "s
220e0 74 61 74 65 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a  tatement"..**.**
220f0 20 54 68 65 20 6c 69 66 65 20 6f 66 20 61 20 73   The life of a s
22100 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20  tatement object 
22110 67 6f 65 73 20 73 6f 6d 65 74 68 69 6e 67 20 6c  goes something l
22120 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20  ike this:.**.** 
22130 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65  <ol>.** <li> Cre
22140 61 74 65 20 74 68 65 20 6f 62 6a 65 63 74 20 75  ate the object u
22150 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72  sing [sqlite3_pr
22160 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 61  epare_v2()] or a
22170 20 72 65 6c 61 74 65 64 0a 2a 2a 20 20 20 20 20   related.**     
22180 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c   function..** <l
22190 69 3e 20 42 69 6e 64 20 76 61 6c 75 65 73 20 74  i> Bind values t
221a0 6f 20 5b 68 6f 73 74 20 70 61 72 61 6d 65 74 65  o [host paramete
221b0 72 73 5d 20 75 73 69 6e 67 20 74 68 65 20 73 71  rs] using the sq
221c0 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a  lite3_bind_*().*
221d0 2a 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65  *      interface
221e0 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74  s..** <li> Run t
221f0 68 65 20 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e  he SQL by callin
22200 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  g [sqlite3_step(
22210 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74  )] one or more t
22220 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65  imes..** <li> Re
22230 73 65 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e  set the statemen
22240 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
22250 5f 72 65 73 65 74 28 29 5d 20 74 68 65 6e 20 67  _reset()] then g
22260 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74  o back.**      t
22270 6f 20 73 74 65 70 20 32 2e 20 20 44 6f 20 74 68  o step 2.  Do th
22280 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20  is zero or more 
22290 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44  times..** <li> D
222a0 65 73 74 72 6f 79 20 74 68 65 20 6f 62 6a 65 63  estroy the objec
222b0 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
222c0 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a  _finalize()]..**
222d0 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66   </ol>.**.** Ref
222e0 65 72 20 74 6f 20 64 6f 63 75 6d 65 6e 74 61 74  er to documentat
222f0 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61  ion on individua
22300 6c 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  l methods above 
22310 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  for additional.*
22320 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  * information..*
22330 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
22340 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71   sqlite3_stmt sq
22350 6c 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a  lite3_stmt;../*.
22360 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e  ** CAPI3REF: Run
22370 2d 74 69 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 0a  -time Limits.**.
22380 2a 2a 20 5e 28 54 68 69 73 20 69 6e 74 65 72 66  ** ^(This interf
22390 61 63 65 20 61 6c 6c 6f 77 73 20 74 68 65 20 73  ace allows the s
223a0 69 7a 65 20 6f 66 20 76 61 72 69 6f 75 73 20 63  ize of various c
223b0 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20  onstructs to be 
223c0 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20  limited.** on a 
223d0 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f  connection by co
223e0 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 2e 20  nnection basis. 
223f0 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   The first param
22400 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b  eter is the.** [
22410 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
22420 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74  ion] whose limit
22430 20 69 73 20 74 6f 20 62 65 20 73 65 74 20 6f 72   is to be set or
22440 20 71 75 65 72 69 65 64 2e 20 20 54 68 65 0a 2a   queried.  The.*
22450 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  * second paramet
22460 65 72 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65  er is one of the
22470 20 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69   [limit categori
22480 65 73 5d 20 74 68 61 74 20 64 65 66 69 6e 65 20  es] that define 
22490 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f  a.** class of co
224a0 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 73  nstructs to be s
224b0 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20 54 68  ize limited.  Th
224c0 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
224d0 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20  r is the.** new 
224e0 6c 69 6d 69 74 20 66 6f 72 20 74 68 61 74 20 63  limit for that c
224f0 6f 6e 73 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a  onstruct.)^.**.*
22500 2a 20 5e 49 66 20 74 68 65 20 6e 65 77 20 6c 69  * ^If the new li
22510 6d 69 74 20 69 73 20 61 20 6e 65 67 61 74 69 76  mit is a negativ
22520 65 20 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c 69  e number, the li
22530 6d 69 74 20 69 73 20 75 6e 63 68 61 6e 67 65 64  mit is unchanged
22540 2e 0a 2a 2a 20 5e 28 46 6f 72 20 65 61 63 68 20  ..** ^(For each 
22550 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 20 53  limit category S
22560 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e  QLITE_LIMIT_<i>N
22570 41 4d 45 3c 2f 69 3e 20 74 68 65 72 65 20 69 73  AME</i> there is
22580 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c   a .** [limits |
22590 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e   hard upper boun
225a0 64 5d 0a 2a 2a 20 73 65 74 20 61 74 20 63 6f 6d  d].** set at com
225b0 70 69 6c 65 2d 74 69 6d 65 20 62 79 20 61 20 43  pile-time by a C
225c0 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61   preprocessor ma
225d0 63 72 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c  cro called.** [l
225e0 69 6d 69 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d  imits | SQLITE_M
225f0 41 58 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e  AX_<i>NAME</i>].
22600 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49 54  .** (The "_LIMIT
22610 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 69  _" in the name i
22620 73 20 63 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d  s changed to "_M
22630 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74  AX_".))^.** ^Att
22640 65 6d 70 74 73 20 74 6f 20 69 6e 63 72 65 61 73  empts to increas
22650 65 20 61 20 6c 69 6d 69 74 20 61 62 6f 76 65 20  e a limit above 
22660 69 74 73 20 68 61 72 64 20 75 70 70 65 72 20 62  its hard upper b
22670 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65  ound are.** sile
22680 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20 74  ntly truncated t
22690 6f 20 74 68 65 20 68 61 72 64 20 75 70 70 65 72  o the hard upper
226a0 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52   bound..**.** ^R
226b0 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65  egardless of whe
226c0 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20  ther or not the 
226d0 6c 69 6d 69 74 20 77 61 73 20 63 68 61 6e 67 65  limit was change
226e0 64 2c 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69  d, the .** [sqli
226f0 74 65 33 5f 6c 69 6d 69 74 28 29 5d 20 69 6e 74  te3_limit()] int
22700 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
22710 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f  he prior value o
22720 66 20 74 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20  f the limit..** 
22730 5e 48 65 6e 63 65 2c 20 74 6f 20 66 69 6e 64 20  ^Hence, to find 
22740 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75  the current valu
22750 65 20 6f 66 20 61 20 6c 69 6d 69 74 20 77 69 74  e of a limit wit
22760 68 6f 75 74 20 63 68 61 6e 67 69 6e 67 20 69 74  hout changing it
22770 2c 0a 2a 2a 20 73 69 6d 70 6c 79 20 69 6e 76 6f  ,.** simply invo
22780 6b 65 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  ke this interfac
22790 65 20 77 69 74 68 20 74 68 65 20 74 68 69 72 64  e with the third
227a0 20 70 61 72 61 6d 65 74 65 72 20 73 65 74 20 74   parameter set t
227b0 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d  o -1..**.** Run-
227c0 74 69 6d 65 20 6c 69 6d 69 74 73 20 61 72 65 20  time limits are 
227d0 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65  intended for use
227e0 20 69 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73   in applications
227f0 20 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20   that manage.** 
22800 62 6f 74 68 20 74 68 65 69 72 20 6f 77 6e 20 69  both their own i
22810 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65  nternal database
22820 20 61 6e 64 20 61 6c 73 6f 20 64 61 74 61 62 61   and also databa
22830 73 65 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e  ses that are con
22840 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e  trolled.** by un
22850 74 72 75 73 74 65 64 20 65 78 74 65 72 6e 61 6c  trusted external
22860 20 73 6f 75 72 63 65 73 2e 20 20 41 6e 20 65 78   sources.  An ex
22870 61 6d 70 6c 65 20 61 70 70 6c 69 63 61 74 69 6f  ample applicatio
22880 6e 20 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a 20  n might be a.** 
22890 77 65 62 20 62 72 6f 77 73 65 72 20 74 68 61 74  web browser that
228a0 20 68 61 73 20 69 74 73 20 6f 77 6e 20 64 61 74   has its own dat
228b0 61 62 61 73 65 73 20 66 6f 72 20 73 74 6f 72 69  abases for stori
228c0 6e 67 20 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a  ng history and.*
228d0 2a 20 73 65 70 61 72 61 74 65 20 64 61 74 61 62  * separate datab
228e0 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20  ases controlled 
228f0 62 79 20 4a 61 76 61 53 63 72 69 70 74 20 61 70  by JavaScript ap
22900 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c  plications downl
22910 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65  oaded.** off the
22920 20 49 6e 74 65 72 6e 65 74 2e 20 20 54 68 65 20   Internet.  The 
22930 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73  internal databas
22940 65 73 20 63 61 6e 20 62 65 20 67 69 76 65 6e 20  es can be given 
22950 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65  the.** large, de
22960 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44  fault limits.  D
22970 61 74 61 62 61 73 65 73 20 6d 61 6e 61 67 65 64  atabases managed
22980 20 62 79 20 65 78 74 65 72 6e 61 6c 20 73 6f 75   by external sou
22990 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67  rces can.** be g
229a0 69 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65  iven much smalle
229b0 72 20 6c 69 6d 69 74 73 20 64 65 73 69 67 6e 65  r limits designe
229c0 64 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 64  d to prevent a d
229d0 65 6e 69 61 6c 20 6f 66 20 73 65 72 76 69 63 65  enial of service
229e0 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44 65 76  .** attack.  Dev
229f0 65 6c 6f 70 65 72 73 20 6d 69 67 68 74 20 61 6c  elopers might al
22a00 73 6f 20 77 61 6e 74 20 74 6f 20 75 73 65 20 74  so want to use t
22a10 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  he [sqlite3_set_
22a20 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a  authorizer()].**
22a30 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 66 75   interface to fu
22a40 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e  rther control un
22a50 74 72 75 73 74 65 64 20 53 51 4c 2e 20 20 54 68  trusted SQL.  Th
22a60 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 64 61  e size of the da
22a70 74 61 62 61 73 65 0a 2a 2a 20 63 72 65 61 74 65  tabase.** create
22a80 64 20 62 79 20 61 6e 20 75 6e 74 72 75 73 74 65  d by an untruste
22a90 64 20 73 63 72 69 70 74 20 63 61 6e 20 62 65 20  d script can be 
22aa0 63 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e 67 20  contained using 
22ab0 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65  the.** [max_page
22ac0 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d  _count] [PRAGMA]
22ad0 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d  ..**.** New run-
22ae0 74 69 6d 65 20 6c 69 6d 69 74 20 63 61 74 65 67  time limit categ
22af0 6f 72 69 65 73 20 6d 61 79 20 62 65 20 61 64 64  ories may be add
22b00 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ed in future rel
22b10 65 61 73 65 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45  eases..*/.SQLITE
22b20 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
22b30 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c  _limit(sqlite3*,
22b40 20 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65 77   int id, int new
22b50 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  Val);../*.** CAP
22b60 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20  I3REF: Run-Time 
22b70 4c 69 6d 69 74 20 43 61 74 65 67 6f 72 69 65 73  Limit Categories
22b80 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 6c  .** KEYWORDS: {l
22b90 69 6d 69 74 20 63 61 74 65 67 6f 72 79 7d 20 7b  imit category} {
22ba0 2a 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65  *limit categorie
22bb0 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  s}.**.** These c
22bc0 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20  onstants define 
22bd0 76 61 72 69 6f 75 73 20 70 65 72 66 6f 72 6d 61  various performa
22be0 6e 63 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74 68  nce limits.** th
22bf0 61 74 20 63 61 6e 20 62 65 20 6c 6f 77 65 72 65  at can be lowere
22c00 64 20 61 74 20 72 75 6e 2d 74 69 6d 65 20 75 73  d at run-time us
22c10 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d  ing [sqlite3_lim
22c20 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 79  it()]..** The sy
22c30 6e 6f 70 73 69 73 20 6f 66 20 74 68 65 20 6d 65  nopsis of the me
22c40 61 6e 69 6e 67 73 20 6f 66 20 74 68 65 20 76 61  anings of the va
22c50 72 69 6f 75 73 20 6c 69 6d 69 74 73 20 69 73 20  rious limits is 
22c60 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20  shown below..** 
22c70 41 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  Additional infor
22c80 6d 61 74 69 6f 6e 20 69 73 20 61 76 61 69 6c 61  mation is availa
22c90 62 6c 65 20 61 74 20 5b 6c 69 6d 69 74 73 20 7c  ble at [limits |
22ca0 20 4c 69 6d 69 74 73 20 69 6e 20 53 51 4c 69 74   Limits in SQLit
22cb0 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a  e]..**.** <dl>.*
22cc0 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  * ^(<dt>SQLITE_L
22cd0 49 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e  IMIT_LENGTH</dt>
22ce0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
22cf0 6d 75 6d 20 73 69 7a 65 20 6f 66 20 61 6e 79 20  mum size of any 
22d00 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 6f  string or BLOB o
22d10 72 20 74 61 62 6c 65 20 72 6f 77 2c 20 69 6e 20  r table row, in 
22d20 62 79 74 65 73 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a  bytes.<dd>)^.**.
22d30 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ** ^(<dt>SQLITE_
22d40 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48  LIMIT_SQL_LENGTH
22d50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
22d60 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   maximum length 
22d70 6f 66 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  of an SQL statem
22d80 65 6e 74 2c 20 69 6e 20 62 79 74 65 73 2e 3c 2f  ent, in bytes.</
22d90 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64  dd>)^.**.** ^(<d
22da0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  t>SQLITE_LIMIT_C
22db0 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  OLUMN</dt>.** <d
22dc0 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
22dd0 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
22de0 69 6e 20 61 20 74 61 62 6c 65 20 64 65 66 69 6e  in a table defin
22df0 69 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68 65 0a  ition or in the.
22e00 2a 2a 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66  ** result set of
22e10 20 61 20 5b 53 45 4c 45 43 54 5d 20 6f 72 20 74   a [SELECT] or t
22e20 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
22e30 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
22e40 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 69  an index.** or i
22e50 6e 20 61 6e 20 4f 52 44 45 52 20 42 59 20 6f 72  n an ORDER BY or
22e60 20 47 52 4f 55 50 20 42 59 20 63 6c 61 75 73 65   GROUP BY clause
22e70 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  .</dd>)^.**.** ^
22e80 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
22e90 54 5f 45 58 50 52 5f 44 45 50 54 48 3c 2f 64 74  T_EXPR_DEPTH</dt
22ea0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
22eb0 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 74 68  imum depth of th
22ec0 65 20 70 61 72 73 65 20 74 72 65 65 20 6f 6e 20  e parse tree on 
22ed0 61 6e 79 20 65 78 70 72 65 73 73 69 6f 6e 2e 3c  any expression.<
22ee0 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c  /dd>)^.**.** ^(<
22ef0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
22f00 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 3c  COMPOUND_SELECT<
22f10 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
22f20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
22f30 66 20 74 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d  f terms in a com
22f40 70 6f 75 6e 64 20 53 45 4c 45 43 54 20 73 74 61  pound SELECT sta
22f50 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a  tement.</dd>)^.*
22f60 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54  *.** ^(<dt>SQLIT
22f70 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 3c  E_LIMIT_VDBE_OP<
22f80 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
22f90 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
22fa0 66 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 20 69  f instructions i
22fb0 6e 20 61 20 76 69 72 74 75 61 6c 20 6d 61 63 68  n a virtual mach
22fc0 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a 20 75  ine program.** u
22fd0 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  sed to implement
22fe0 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
22ff0 74 2e 20 20 54 68 69 73 20 6c 69 6d 69 74 20 69  t.  This limit i
23000 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 0a  s not currently.
23010 2a 2a 20 65 6e 66 6f 72 63 65 64 2c 20 74 68 6f  ** enforced, tho
23020 75 67 68 20 74 68 61 74 20 6d 69 67 68 74 20 62  ugh that might b
23030 65 20 61 64 64 65 64 20 69 6e 20 73 6f 6d 65 20  e added in some 
23040 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f  future release o
23050 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 3c 2f 64 64  f.** SQLite.</dd
23060 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e  >)^.**.** ^(<dt>
23070 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e  SQLITE_LIMIT_FUN
23080 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a  CTION_ARG</dt>.*
23090 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
230a0 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75  m number of argu
230b0 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63 74  ments on a funct
230c0 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ion.</dd>)^.**.*
230d0 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  * ^(<dt>SQLITE_L
230e0 49 4d 49 54 5f 41 54 54 41 43 48 45 44 3c 2f 64  IMIT_ATTACHED</d
230f0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
23100 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
23110 5b 41 54 54 41 43 48 20 7c 20 61 74 74 61 63 68  [ATTACH | attach
23120 65 64 20 64 61 74 61 62 61 73 65 73 5d 2e 29 5e  ed databases].)^
23130 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64  </dd>.**.** ^(<d
23140 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  t>SQLITE_LIMIT_L
23150 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47  IKE_PATTERN_LENG
23160 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
23170 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  he maximum lengt
23180 68 20 6f 66 20 74 68 65 20 70 61 74 74 65 72 6e  h of the pattern
23190 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
231a0 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47   [LIKE] or.** [G
231b0 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 73 2e 3c  LOB] operators.<
231c0 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c  /dd>)^.**.** ^(<
231d0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
231e0 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 3c  VARIABLE_NUMBER<
231f0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
23200 6d 61 78 69 6d 75 6d 20 69 6e 64 65 78 20 6e 75  maximum index nu
23210 6d 62 65 72 20 6f 66 20 61 6e 79 20 5b 70 61 72  mber of any [par
23220 61 6d 65 74 65 72 5d 20 69 6e 20 61 6e 20 53 51  ameter] in an SQ
23230 4c 20 73 74 61 74 65 6d 65 6e 74 2e 29 5e 0a 2a  L statement.)^.*
23240 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54  *.** ^(<dt>SQLIT
23250 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f  E_LIMIT_TRIGGER_
23260 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  DEPTH</dt>.** <d
23270 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65  d>The maximum de
23280 70 74 68 20 6f 66 20 72 65 63 75 72 73 69 6f 6e  pth of recursion
23290 20 66 6f 72 20 74 72 69 67 67 65 72 73 2e 3c 2f   for triggers.</
232a0 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  dd>)^.** </dl>.*
232b0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
232c0 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20 20  _LIMIT_LENGTH   
232d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
232e0 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   0.#define SQLIT
232f0 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47  E_LIMIT_SQL_LENG
23300 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TH              
23310 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
23320 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20  TE_LIMIT_COLUMN 
23330 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
23340 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
23350 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44  ITE_LIMIT_EXPR_D
23360 45 50 54 48 20 20 20 20 20 20 20 20 20 20 20 20  EPTH            
23370 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51      3.#define SQ
23380 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f  LITE_LIMIT_COMPO
23390 55 4e 44 5f 53 45 4c 45 43 54 20 20 20 20 20 20  UND_SELECT      
233a0 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53       4.#define S
233b0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45  QLITE_LIMIT_VDBE
233c0 5f 4f 50 20 20 20 20 20 20 20 20 20 20 20 20 20  _OP             
233d0 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20        5.#define 
233e0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e  SQLITE_LIMIT_FUN
233f0 43 54 49 4f 4e 5f 41 52 47 20 20 20 20 20 20 20  CTION_ARG       
23400 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65         6.#define
23410 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54   SQLITE_LIMIT_AT
23420 54 41 43 48 45 44 20 20 20 20 20 20 20 20 20 20  TACHED          
23430 20 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e          7.#defin
23440 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  e SQLITE_LIMIT_L
23450 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47  IKE_PATTERN_LENG
23460 54 48 20 20 20 20 20 20 20 38 0a 23 64 65 66 69  TH       8.#defi
23470 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
23480 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20  VARIABLE_NUMBER 
23490 20 20 20 20 20 20 20 20 20 20 39 0a 23 64 65 66            9.#def
234a0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
234b0 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 20 20  _TRIGGER_DEPTH  
234c0 20 20 20 20 20 20 20 20 20 20 31 30 0a 0a 2f 2a            10../*
234d0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
234e0 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20 53  mpiling An SQL S
234f0 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b 45 59 57  tatement.** KEYW
23500 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74 61 74 65  ORDS: {SQL state
23510 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d 0a 2a  ment compiler}.*
23520 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74 65 20  *.** To execute 
23530 61 6e 20 53 51 4c 20 71 75 65 72 79 2c 20 69 74  an SQL query, it
23540 20 6d 75 73 74 20 66 69 72 73 74 20 62 65 20 63   must first be c
23550 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61 20 62  ompiled into a b
23560 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f 67  yte-code.** prog
23570 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66  ram using one of
23580 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e   these routines.
23590 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
235a0 20 61 72 67 75 6d 65 6e 74 2c 20 22 64 62 22 2c   argument, "db",
235b0 20 69 73 20 61 20 5b 64 61 74 61 62 61 73 65 20   is a [database 
235c0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 74 61  connection] obta
235d0 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 70  ined from a.** p
235e0 72 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20  rior successful 
235f0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
23600 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
23610 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 6f 72  e3_open_v2()] or
23620 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  .** [sqlite3_ope
23630 6e 31 36 28 29 5d 2e 20 20 54 68 65 20 64 61 74  n16()].  The dat
23640 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
23650 20 6d 75 73 74 20 6e 6f 74 20 68 61 76 65 20 62   must not have b
23660 65 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a  een closed..**.*
23670 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67  * The second arg
23680 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c 20 69  ument, "zSql", i
23690 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  s the statement 
236a0 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c 20  to be compiled, 
236b0 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65 69  encoded.** as ei
236c0 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54  ther UTF-8 or UT
236d0 46 2d 31 36 2e 20 20 54 68 65 20 73 71 6c 69 74  F-16.  The sqlit
236e0 65 33 5f 70 72 65 70 61 72 65 28 29 20 61 6e 64  e3_prepare() and
236f0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
23700 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  _v2().** interfa
23710 63 65 73 20 75 73 65 20 55 54 46 2d 38 2c 20 61  ces use UTF-8, a
23720 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nd sqlite3_prepa
23730 72 65 31 36 28 29 20 61 6e 64 20 73 71 6c 69 74  re16() and sqlit
23740 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
23750 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31 36 2e  ).** use UTF-16.
23760 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e  .**.** ^If the n
23770 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20 69 73  Byte argument is
23780 20 6c 65 73 73 20 74 68 61 6e 20 7a 65 72 6f 2c   less than zero,
23790 20 74 68 65 6e 20 7a 53 71 6c 20 69 73 20 72 65   then zSql is re
237a0 61 64 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20  ad up to the.** 
237b0 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69  first zero termi
237c0 6e 61 74 6f 72 2e 20 5e 49 66 20 6e 42 79 74 65  nator. ^If nByte
237d0 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65   is non-negative
237e0 2c 20 74 68 65 6e 20 69 74 20 69 73 20 74 68 65  , then it is the
237f0 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 6e 75 6d 62   maximum.** numb
23800 65 72 20 6f 66 20 20 62 79 74 65 73 20 72 65 61  er of  bytes rea
23810 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 5e 57  d from zSql.  ^W
23820 68 65 6e 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e  hen nByte is non
23830 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 0a 2a  -negative, the.*
23840 2a 20 7a 53 71 6c 20 73 74 72 69 6e 67 20 65 6e  * zSql string en
23850 64 73 20 61 74 20 65 69 74 68 65 72 20 74 68 65  ds at either the
23860 20 66 69 72 73 74 20 27 5c 30 30 30 27 20 6f 72   first '\000' or
23870 20 27 5c 75 30 30 30 30 27 20 63 68 61 72 61 63   '\u0000' charac
23880 74 65 72 20 6f 72 0a 2a 2a 20 74 68 65 20 6e 42  ter or.** the nB
23890 79 74 65 2d 74 68 20 62 79 74 65 2c 20 77 68 69  yte-th byte, whi
238a0 63 68 65 76 65 72 20 63 6f 6d 65 73 20 66 69 72  chever comes fir
238b0 73 74 2e 20 49 66 20 74 68 65 20 63 61 6c 6c 65  st. If the calle
238c0 72 20 6b 6e 6f 77 73 0a 2a 2a 20 74 68 61 74 20  r knows.** that 
238d0 74 68 65 20 73 75 70 70 6c 69 65 64 20 73 74 72  the supplied str
238e0 69 6e 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d 69  ing is nul-termi
238f0 6e 61 74 65 64 2c 20 74 68 65 6e 20 74 68 65 72  nated, then ther
23900 65 20 69 73 20 61 20 73 6d 61 6c 6c 0a 2a 2a 20  e is a small.** 
23910 70 65 72 66 6f 72 6d 61 6e 63 65 20 61 64 76 61  performance adva
23920 6e 74 61 67 65 20 74 6f 20 62 65 20 67 61 69 6e  ntage to be gain
23930 65 64 20 62 79 20 70 61 73 73 69 6e 67 20 61 6e  ed by passing an
23940 20 6e 42 79 74 65 20 70 61 72 61 6d 65 74 65 72   nByte parameter
23950 20 74 68 61 74 0a 2a 2a 20 69 73 20 65 71 75 61   that.** is equa
23960 6c 20 74 6f 20 74 68 65 20 6e 75 6d 62 65 72 20  l to the number 
23970 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  of bytes in the 
23980 69 6e 70 75 74 20 73 74 72 69 6e 67 20 3c 69 3e  input string <i>
23990 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a  including</i>.**
239a0 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69 6e 61   the nul-termina
239b0 74 6f 72 20 62 79 74 65 73 2e 0a 2a 2a 0a 2a 2a  tor bytes..**.**
239c0 20 5e 49 66 20 70 7a 54 61 69 6c 20 69 73 20 6e   ^If pzTail is n
239d0 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 2a 70 7a  ot NULL then *pz
239e0 54 61 69 6c 20 69 73 20 6d 61 64 65 20 74 6f 20  Tail is made to 
239f0 70 6f 69 6e 74 20 74 6f 20 74 68 65 20 66 69 72  point to the fir
23a00 73 74 20 62 79 74 65 0a 2a 2a 20 70 61 73 74 20  st byte.** past 
23a10 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 66  the end of the f
23a20 69 72 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65  irst SQL stateme
23a30 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65  nt in zSql.  The
23a40 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79  se routines only
23a50 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 68 65 20  .** compile the 
23a60 66 69 72 73 74 20 73 74 61 74 65 6d 65 6e 74 20  first statement 
23a70 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54  in zSql, so *pzT
23a80 61 69 6c 20 69 73 20 6c 65 66 74 20 70 6f 69 6e  ail is left poin
23a90 74 69 6e 67 20 74 6f 0a 2a 2a 20 77 68 61 74 20  ting to.** what 
23aa0 72 65 6d 61 69 6e 73 20 75 6e 63 6f 6d 70 69 6c  remains uncompil
23ab0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70 53 74  ed..**.** ^*ppSt
23ac0 6d 74 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74  mt is left point
23ad0 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65  ing to a compile
23ae0 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
23af0 65 6d 65 6e 74 5d 20 74 68 61 74 20 63 61 6e 20  ement] that can 
23b00 62 65 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 75  be.** executed u
23b10 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74  sing [sqlite3_st
23b20 65 70 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 72  ep()].  ^If ther
23b30 65 20 69 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a  e is an error, *
23b40 70 70 53 74 6d 74 20 69 73 20 73 65 74 0a 2a 2a  ppStmt is set.**
23b50 20 74 6f 20 4e 55 4c 4c 2e 20 20 5e 49 66 20 74   to NULL.  ^If t
23b60 68 65 20 69 6e 70 75 74 20 74 65 78 74 20 63 6f  he input text co
23b70 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20 28 69  ntains no SQL (i
23b80 66 20 74 68 65 20 69 6e 70 75 74 20 69 73 20 61  f the input is a
23b90 6e 20 65 6d 70 74 79 0a 2a 2a 20 73 74 72 69 6e  n empty.** strin
23ba0 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20  g or a comment) 
23bb0 74 68 65 6e 20 2a 70 70 53 74 6d 74 20 69 73 20  then *ppStmt is 
23bc0 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20  set to NULL..** 
23bd0 54 68 65 20 63 61 6c 6c 69 6e 67 20 70 72 6f 63  The calling proc
23be0 65 64 75 72 65 20 69 73 20 72 65 73 70 6f 6e 73  edure is respons
23bf0 69 62 6c 65 20 66 6f 72 20 64 65 6c 65 74 69 6e  ible for deletin
23c00 67 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 0a 2a  g the compiled.*
23c10 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  * SQL statement 
23c20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66  using [sqlite3_f
23c30 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66 74 65 72  inalize()] after
23c40 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65 64   it has finished
23c50 20 77 69 74 68 20 69 74 2e 0a 2a 2a 20 70 70 53   with it..** ppS
23c60 74 6d 74 20 6d 61 79 20 6e 6f 74 20 62 65 20 4e  tmt may not be N
23c70 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73  ULL..**.** ^On s
23c80 75 63 63 65 73 73 2c 20 74 68 65 20 73 71 6c 69  uccess, the sqli
23c90 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 66 61  te3_prepare() fa
23ca0 6d 69 6c 79 20 6f 66 20 72 6f 75 74 69 6e 65 73  mily of routines
23cb0 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
23cc0 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68 65 72 77 69 73  OK];.** otherwis
23cd0 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65  e an [error code
23ce0 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  ] is returned..*
23cf0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
23d00 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 61 6e  _prepare_v2() an
23d10 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  d sqlite3_prepar
23d20 65 31 36 5f 76 32 28 29 20 69 6e 74 65 72 66 61  e16_v2() interfa
23d30 63 65 73 20 61 72 65 0a 2a 2a 20 72 65 63 6f 6d  ces are.** recom
23d40 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e  mended for all n
23d50 65 77 20 70 72 6f 67 72 61 6d 73 2e 20 54 68 65  ew programs. The
23d60 20 74 77 6f 20 6f 6c 64 65 72 20 69 6e 74 65 72   two older inter
23d70 66 61 63 65 73 20 61 72 65 20 72 65 74 61 69 6e  faces are retain
23d80 65 64 0a 2a 2a 20 66 6f 72 20 62 61 63 6b 77 61  ed.** for backwa
23d90 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
23da0 79 2c 20 62 75 74 20 74 68 65 69 72 20 75 73 65  y, but their use
23db0 20 69 73 20 64 69 73 63 6f 75 72 61 67 65 64 2e   is discouraged.
23dc0 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 22 76 32 22  .** ^In the "v2"
23dd0 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65   interfaces, the
23de0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
23df0 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73 20 72  ent.** that is r
23e00 65 74 75 72 6e 65 64 20 28 74 68 65 20 5b 73 71  eturned (the [sq
23e10 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65  lite3_stmt] obje
23e20 63 74 29 20 63 6f 6e 74 61 69 6e 73 20 61 20 63  ct) contains a c
23e30 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 72  opy of the.** or
23e40 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e  iginal SQL text.
23e50 20 54 68 69 73 20 63 61 75 73 65 73 20 74 68 65   This causes the
23e60 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
23e70 5d 20 69 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a  ] interface to.*
23e80 2a 20 62 65 68 61 76 65 20 64 69 66 66 65 72 65  * behave differe
23e90 6e 74 6c 79 20 69 6e 20 74 68 72 65 65 20 77 61  ntly in three wa
23ea0 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a  ys:.**.** <ol>.*
23eb0 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68  * <li>.** ^If th
23ec0 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d  e database schem
23ed0 61 20 63 68 61 6e 67 65 73 2c 20 69 6e 73 74 65  a changes, inste
23ee0 61 64 20 6f 66 20 72 65 74 75 72 6e 69 6e 67 20  ad of returning 
23ef0 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20  [SQLITE_SCHEMA] 
23f00 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20  as it.** always 
23f10 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c  used to do, [sql
23f20 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c  ite3_step()] wil
23f30 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  l automatically 
23f40 72 65 63 6f 6d 70 69 6c 65 20 74 68 65 20 53 51  recompile the SQ
23f50 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61  L.** statement a
23f60 6e 64 20 74 72 79 20 74 6f 20 72 75 6e 20 69 74  nd try to run it
23f70 20 61 67 61 69 6e 2e 0a 2a 2a 20 3c 2f 6c 69 3e   again..** </li>
23f80 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e  .**.** <li>.** ^
23f90 57 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63  When an error oc
23fa0 63 75 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f 73  curs, [sqlite3_s
23fb0 74 65 70 28 29 5d 20 77 69 6c 6c 20 72 65 74 75  tep()] will retu
23fc0 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 65  rn one of the de
23fd0 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f 72  tailed.** [error
23fe0 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74 65   codes] or [exte
23ff0 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 73  nded error codes
24000 5d 2e 20 20 5e 54 68 65 20 6c 65 67 61 63 79 20  ].  ^The legacy 
24010 62 65 68 61 76 69 6f 72 20 77 61 73 20 74 68 61  behavior was tha
24020 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74  t.** [sqlite3_st
24030 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79  ep()] would only
24040 20 72 65 74 75 72 6e 20 61 20 67 65 6e 65 72 69   return a generi
24050 63 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  c [SQLITE_ERROR]
24060 20 72 65 73 75 6c 74 20 63 6f 64 65 0a 2a 2a 20   result code.** 
24070 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 74  and the applicat
24080 69 6f 6e 20 77 6f 75 6c 64 20 68 61 76 65 20 74  ion would have t
24090 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64 20  o make a second 
240a0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
240b0 5f 72 65 73 65 74 28 29 5d 0a 2a 2a 20 69 6e 20  _reset()].** in 
240c0 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 74 68  order to find th
240d0 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 63 61 75  e underlying cau
240e0 73 65 20 6f 66 20 74 68 65 20 70 72 6f 62 6c 65  se of the proble
240f0 6d 2e 20 57 69 74 68 20 74 68 65 20 22 76 32 22  m. With the "v2"
24100 20 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e 74 65   prepare.** inte
24110 72 66 61 63 65 73 2c 20 74 68 65 20 75 6e 64 65  rfaces, the unde
24120 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20 66 6f  rlying reason fo
24130 72 20 74 68 65 20 65 72 72 6f 72 20 69 73 20 72  r the error is r
24140 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74  eturned immediat
24150 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a  ely..** </li>.**
24160 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20  .** <li>.** ^If 
24170 74 68 65 20 73 70 65 63 69 66 69 63 20 76 61 6c  the specific val
24180 75 65 20 62 6f 75 6e 64 20 74 6f 20 5b 70 61 72  ue bound to [par
24190 61 6d 65 74 65 72 20 7c 20 68 6f 73 74 20 70 61  ameter | host pa
241a0 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20  rameter] in the 
241b0 0a 2a 2a 20 57 48 45 52 45 20 63 6c 61 75 73 65  .** WHERE clause
241c0 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65   might influence
241d0 20 74 68 65 20 63 68 6f 69 63 65 20 6f 66 20 71   the choice of q
241e0 75 65 72 79 20 70 6c 61 6e 20 66 6f 72 20 61 20  uery plan for a 
241f0 73 74 61 74 65 6d 65 6e 74 2c 0a 2a 2a 20 74 68  statement,.** th
24200 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  en the statement
24210 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74   will be automat
24220 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65  ically recompile
24230 64 2c 20 61 73 20 69 66 20 74 68 65 72 65 20 68  d, as if there h
24240 61 64 20 62 65 65 6e 20 0a 2a 2a 20 61 20 73 63  ad been .** a sc
24250 68 65 6d 61 20 63 68 61 6e 67 65 2c 20 6f 6e 20  hema change, on 
24260 74 68 65 20 66 69 72 73 74 20 20 5b 73 71 6c 69  the first  [sqli
24270 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c  te3_step()] call
24280 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 20 63   following any c
24290 68 61 6e 67 65 0a 2a 2a 20 74 6f 20 74 68 65 20  hange.** to the 
242a0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65  [sqlite3_bind_te
242b0 78 74 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f  xt | bindings] o
242c0 66 20 74 68 61 74 20 5b 70 61 72 61 6d 65 74 65  f that [paramete
242d0 72 5d 2e 20 0a 2a 2a 20 5e 54 68 65 20 73 70 65  r]. .** ^The spe
242e0 63 69 66 69 63 20 76 61 6c 75 65 20 6f 66 20 57  cific value of W
242f0 48 45 52 45 2d 63 6c 61 75 73 65 20 5b 70 61 72  HERE-clause [par
24300 61 6d 65 74 65 72 5d 20 6d 69 67 68 74 20 69 6e  ameter] might in
24310 66 6c 75 65 6e 63 65 20 74 68 65 20 0a 2a 2a 20  fluence the .** 
24320 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20  choice of query 
24330 70 6c 61 6e 20 69 66 20 74 68 65 20 70 61 72 61  plan if the para
24340 6d 65 74 65 72 20 69 73 20 74 68 65 20 6c 65 66  meter is the lef
24350 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20 61  t-hand side of a
24360 20 5b 4c 49 4b 45 5d 0a 2a 2a 20 6f 72 20 5b 47   [LIKE].** or [G
24370 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 20 6f 72  LOB] operator or
24380 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   if the paramete
24390 72 20 69 73 20 63 6f 6d 70 61 72 65 64 20 74 6f  r is compared to
243a0 20 61 6e 20 69 6e 64 65 78 65 64 20 63 6f 6c 75   an indexed colu
243b0 6d 6e 0a 2a 2a 20 61 6e 64 20 74 68 65 20 5b 53  mn.** and the [S
243c0 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 54 41  QLITE_ENABLE_STA
243d0 54 32 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  T2] compile-time
243e0 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c   option is enabl
243f0 65 64 2e 0a 2a 2a 20 74 68 65 20 0a 2a 2a 20 3c  ed..** the .** <
24400 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f  /li>.** </ol>.*/
24410 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
24420 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
24430 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
24440 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
24450 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f  tabase handle */
24460 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
24470 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51  Sql,       /* SQ
24480 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46  L statement, UTF
24490 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20  -8 encoded */.  
244a0 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20  int nByte,      
244b0 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
244c0 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71  um length of zSq
244d0 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20  l in bytes. */. 
244e0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a   sqlite3_stmt **
244f0 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a  ppStmt,  /* OUT:
24500 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   Statement handl
24510 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
24520 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f  r **pzTail     /
24530 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74  * OUT: Pointer t
24540 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e  o unused portion
24550 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53   of zSql */.);.S
24560 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
24570 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
24580 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
24590 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
245a0 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a  atabase handle *
245b0 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
245c0 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53  zSql,       /* S
245d0 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54  QL statement, UT
245e0 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20  F-8 encoded */. 
245f0 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20   int nByte,     
24600 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
24610 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53  mum length of zS
24620 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a  ql in bytes. */.
24630 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a    sqlite3_stmt *
24640 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54  *ppStmt,  /* OUT
24650 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  : Statement hand
24660 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  le */.  const ch
24670 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20  ar **pzTail     
24680 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20  /* OUT: Pointer 
24690 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f  to unused portio
246a0 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a  n of zSql */.);.
246b0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
246c0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
246d0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
246e0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
246f0 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a  atabase handle *
24700 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
24710 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53  zSql,       /* S
24720 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54  QL statement, UT
24730 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a  F-16 encoded */.
24740 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20    int nByte,    
24750 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
24760 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a  imum length of z
24770 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f  Sql in bytes. */
24780 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  .  sqlite3_stmt 
24790 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55  **ppStmt,  /* OU
247a0 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e  T: Statement han
247b0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  dle */.  const v
247c0 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20  oid **pzTail    
247d0 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72   /* OUT: Pointer
247e0 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69   to unused porti
247f0 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b  on of zSql */.);
24800 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
24810 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
24820 36 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20  6_v2(.  sqlite3 
24830 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
24840 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64  /* Database hand
24850 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  le */.  const vo
24860 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20  id *zSql,       
24870 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  /* SQL statement
24880 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64  , UTF-16 encoded
24890 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c   */.  int nByte,
248a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
248b0 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   Maximum length 
248c0 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73  of zSql in bytes
248d0 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73  . */.  sqlite3_s
248e0 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f  tmt **ppStmt,  /
248f0 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74  * OUT: Statement
24900 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
24910 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c  st void **pzTail
24920 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69       /* OUT: Poi
24930 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70  nter to unused p
24940 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a  ortion of zSql *
24950 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.);../*.** CAPI
24960 33 52 45 46 3a 20 52 65 74 72 69 65 76 69 6e 67  3REF: Retrieving
24970 20 53 74 61 74 65 6d 65 6e 74 20 53 51 4c 0a 2a   Statement SQL.*
24980 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65 72  *.** ^This inter
24990 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64  face can be used
249a0 20 74 6f 20 72 65 74 72 69 65 76 65 20 61 20 73   to retrieve a s
249b0 61 76 65 64 20 63 6f 70 79 20 6f 66 20 74 68 65  aved copy of the
249c0 20 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20 53 51 4c   original.** SQL
249d0 20 74 65 78 74 20 75 73 65 64 20 74 6f 20 63 72   text used to cr
249e0 65 61 74 65 20 61 20 5b 70 72 65 70 61 72 65 64  eate a [prepared
249f0 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 66 20 74   statement] if t
24a00 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20 77 61  hat statement wa
24a10 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 75 73  s.** compiled us
24a20 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69  ing either [sqli
24a30 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
24a40 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ] or [sqlite3_pr
24a50 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a  epare16_v2()]..*
24a60 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  /.SQLITE_API con
24a70 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
24a80 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d  _sql(sqlite3_stm
24a90 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
24aa0 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65  * CAPI3REF: Dete
24ab0 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20  rmine If An SQL 
24ac0 53 74 61 74 65 6d 65 6e 74 20 57 72 69 74 65 73  Statement Writes
24ad0 20 54 68 65 20 44 61 74 61 62 61 73 65 0a 2a 2a   The Database.**
24ae0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
24af0 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 58  _stmt_readonly(X
24b00 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
24b10 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65  rns true (non-ze
24b20 72 6f 29 20 69 66 0a 2a 2a 20 61 6e 64 20 6f 6e  ro) if.** and on
24b30 6c 79 20 69 66 20 74 68 65 20 5b 70 72 65 70 61  ly if the [prepa
24b40 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 58  red statement] X
24b50 20 6d 61 6b 65 73 20 6e 6f 20 64 69 72 65 63 74   makes no direct
24b60 20 63 68 61 6e 67 65 73 20 74 6f 0a 2a 2a 20 74   changes to.** t
24b70 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  he content of th
24b80 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e  e database file.
24b90 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  .**.** Note that
24ba0 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   [application-de
24bb0 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
24bc0 6f 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76 69 72 74  ons] or.** [virt
24bd0 75 61 6c 20 74 61 62 6c 65 73 5d 20 6d 69 67 68  ual tables] migh
24be0 74 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74  t change the dat
24bf0 61 62 61 73 65 20 69 6e 64 69 72 65 63 74 6c 79  abase indirectly
24c00 20 61 73 20 61 20 73 69 64 65 20 65 66 66 65 63   as a side effec
24c10 74 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72 20 65 78  t.  .** ^(For ex
24c20 61 6d 70 6c 65 2c 20 69 66 20 61 6e 20 61 70 70  ample, if an app
24c30 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 73  lication defines
24c40 20 61 20 66 75 6e 63 74 69 6f 6e 20 22 65 76 61   a function "eva
24c50 6c 28 29 22 20 74 68 61 74 20 0a 2a 2a 20 63 61  l()" that .** ca
24c60 6c 6c 73 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  lls [sqlite3_exe
24c70 63 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 66  c()], then the f
24c80 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 20 73 74 61  ollowing SQL sta
24c90 74 65 6d 65 6e 74 20 77 6f 75 6c 64 0a 2a 2a 20  tement would.** 
24ca0 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62  change the datab
24cb0 61 73 65 20 66 69 6c 65 20 74 68 72 6f 75 67 68  ase file through
24cc0 20 73 69 64 65 2d 65 66 66 65 63 74 73 3a 0a 2a   side-effects:.*
24cd0 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
24ce0 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 53 45 4c  ><pre>.**    SEL
24cf0 45 43 54 20 65 76 61 6c 28 27 44 45 4c 45 54 45  ECT eval('DELETE
24d00 20 46 52 4f 4d 20 74 31 27 29 20 46 52 4f 4d 20   FROM t1') FROM 
24d10 74 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  t2;.** </pre></b
24d20 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
24d30 20 42 75 74 20 62 65 63 61 75 73 65 20 74 68 65   But because the
24d40 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
24d50 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 68 61  ent does not cha
24d60 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65  nge the database
24d70 20 66 69 6c 65 0a 2a 2a 20 64 69 72 65 63 74 6c   file.** directl
24d80 79 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  y, sqlite3_stmt_
24d90 72 65 61 64 6f 6e 6c 79 28 29 20 77 6f 75 6c 64  readonly() would
24da0 20 73 74 69 6c 6c 20 72 65 74 75 72 6e 20 74 72   still return tr
24db0 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72 61  ue.)^.**.** ^Tra
24dc0 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c  nsaction control
24dd0 20 73 74 61 74 65 6d 65 6e 74 73 20 73 75 63 68   statements such
24de0 20 61 73 20 5b 42 45 47 49 4e 5d 2c 20 5b 43 4f   as [BEGIN], [CO
24df0 4d 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42 41 43 4b  MMIT], [ROLLBACK
24e00 5d 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f 49 4e 54  ],.** [SAVEPOINT
24e10 5d 2c 20 61 6e 64 20 5b 52 45 4c 45 41 53 45 5d  ], and [RELEASE]
24e20 20 63 61 75 73 65 20 73 71 6c 69 74 65 33 5f 73   cause sqlite3_s
24e30 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74  tmt_readonly() t
24e40 6f 20 72 65 74 75 72 6e 20 74 72 75 65 2c 0a 2a  o return true,.*
24e50 2a 20 73 69 6e 63 65 20 74 68 65 20 73 74 61 74  * since the stat
24e60 65 6d 65 6e 74 73 20 74 68 65 6d 73 65 6c 76 65  ements themselve
24e70 73 20 64 6f 20 6e 6f 74 20 61 63 74 75 61 6c 6c  s do not actuall
24e80 79 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74  y modify the dat
24e90 61 62 61 73 65 20 62 75 74 0a 2a 2a 20 72 61 74  abase but.** rat
24ea0 68 65 72 20 74 68 65 79 20 63 6f 6e 74 72 6f 6c  her they control
24eb0 20 74 68 65 20 74 69 6d 69 6e 67 20 6f 66 20 77   the timing of w
24ec0 68 65 6e 20 6f 74 68 65 72 20 73 74 61 74 65 6d  hen other statem
24ed0 65 6e 74 73 20 6d 6f 64 69 66 79 20 74 68 65 20  ents modify the 
24ee0 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 5e  .** database.  ^
24ef0 54 68 65 20 5b 41 54 54 41 43 48 5d 20 61 6e 64  The [ATTACH] and
24f00 20 5b 44 45 54 41 43 48 5d 20 73 74 61 74 65 6d   [DETACH] statem
24f10 65 6e 74 73 20 61 6c 73 6f 20 63 61 75 73 65 0a  ents also cause.
24f20 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  ** sqlite3_stmt_
24f30 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65  readonly() to re
24f40 74 75 72 6e 20 74 72 75 65 20 73 69 6e 63 65 2c  turn true since,
24f50 20 77 68 69 6c 65 20 74 68 6f 73 65 20 73 74 61   while those sta
24f60 74 65 6d 65 6e 74 73 0a 2a 2a 20 63 68 61 6e 67  tements.** chang
24f70 65 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74  e the configurat
24f80 69 6f 6e 20 6f 66 20 61 20 64 61 74 61 62 61 73  ion of a databas
24f90 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 74 68  e connection, th
24fa0 65 79 20 64 6f 20 6e 6f 74 20 6d 61 6b 65 20 0a  ey do not make .
24fb0 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68  ** changes to th
24fc0 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
24fd0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 73 20   database files 
24fe0 6f 6e 20 64 69 73 6b 2e 0a 2a 2f 0a 53 51 4c 49  on disk..*/.SQLI
24ff0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
25000 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79  e3_stmt_readonly
25010 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
25020 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
25030 50 49 33 52 45 46 3a 20 44 79 6e 61 6d 69 63 61  PI3REF: Dynamica
25040 6c 6c 79 20 54 79 70 65 64 20 56 61 6c 75 65 20  lly Typed Value 
25050 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52  Object.** KEYWOR
25060 44 53 3a 20 7b 70 72 6f 74 65 63 74 65 64 20 73  DS: {protected s
25070 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75  qlite3_value} {u
25080 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
25090 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20  e3_value}.**.** 
250a0 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20  SQLite uses the 
250b0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
250c0 6a 65 63 74 20 74 6f 20 72 65 70 72 65 73 65 6e  ject to represen
250d0 74 20 61 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20  t all values.** 
250e0 74 68 61 74 20 63 61 6e 20 62 65 20 73 74 6f 72  that can be stor
250f0 65 64 20 69 6e 20 61 20 64 61 74 61 62 61 73 65  ed in a database
25100 20 74 61 62 6c 65 2e 20 53 51 4c 69 74 65 20 75   table. SQLite u
25110 73 65 73 20 64 79 6e 61 6d 69 63 20 74 79 70 69  ses dynamic typi
25120 6e 67 0a 2a 2a 20 66 6f 72 20 74 68 65 20 76 61  ng.** for the va
25130 6c 75 65 73 20 69 74 20 73 74 6f 72 65 73 2e 20  lues it stores. 
25140 20 5e 56 61 6c 75 65 73 20 73 74 6f 72 65 64 20   ^Values stored 
25150 69 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  in sqlite3_value
25160 20 6f 62 6a 65 63 74 73 0a 2a 2a 20 63 61 6e 20   objects.** can 
25170 62 65 20 69 6e 74 65 67 65 72 73 2c 20 66 6c 6f  be integers, flo
25180 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75  ating point valu
25190 65 73 2c 20 73 74 72 69 6e 67 73 2c 20 42 4c 4f  es, strings, BLO
251a0 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a  Bs, or NULL..**.
251b0 2a 2a 20 41 6e 20 73 71 6c 69 74 65 33 5f 76 61  ** An sqlite3_va
251c0 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61 79 20 62  lue object may b
251d0 65 20 65 69 74 68 65 72 20 22 70 72 6f 74 65 63  e either "protec
251e0 74 65 64 22 20 6f 72 20 22 75 6e 70 72 6f 74 65  ted" or "unprote
251f0 63 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69  cted"..** Some i
25200 6e 74 65 72 66 61 63 65 73 20 72 65 71 75 69 72  nterfaces requir
25210 65 20 61 20 70 72 6f 74 65 63 74 65 64 20 73 71  e a protected sq
25220 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20 20 4f 74  lite3_value.  Ot
25230 68 65 72 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  her interfaces.*
25240 2a 20 77 69 6c 6c 20 61 63 63 65 70 74 20 65 69  * will accept ei
25250 74 68 65 72 20 61 20 70 72 6f 74 65 63 74 65 64  ther a protected
25260 20 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74   or an unprotect
25270 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
25280 2e 0a 2a 2a 20 45 76 65 72 79 20 69 6e 74 65 72  ..** Every inter
25290 66 61 63 65 20 74 68 61 74 20 61 63 63 65 70 74  face that accept
252a0 73 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  s sqlite3_value 
252b0 61 72 67 75 6d 65 6e 74 73 20 73 70 65 63 69 66  arguments specif
252c0 69 65 73 0a 2a 2a 20 77 68 65 74 68 65 72 20 6f  ies.** whether o
252d0 72 20 6e 6f 74 20 69 74 20 72 65 71 75 69 72 65  r not it require
252e0 73 20 61 20 70 72 6f 74 65 63 74 65 64 20 73 71  s a protected sq
252f0 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a  lite3_value..**.
25300 2a 2a 20 54 68 65 20 74 65 72 6d 73 20 22 70 72  ** The terms "pr
25310 6f 74 65 63 74 65 64 22 20 61 6e 64 20 22 75 6e  otected" and "un
25320 70 72 6f 74 65 63 74 65 64 22 20 72 65 66 65 72  protected" refer
25330 20 74 6f 20 77 68 65 74 68 65 72 20 6f 72 20 6e   to whether or n
25340 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78 20 69 73  ot.** a mutex is
25350 20 68 65 6c 64 2e 20 20 41 6e 20 69 6e 74 65 72   held.  An inter
25360 6e 61 6c 20 6d 75 74 65 78 20 69 73 20 68 65 6c  nal mutex is hel
25370 64 20 66 6f 72 20 61 20 70 72 6f 74 65 63 74 65  d for a protecte
25380 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c  d.** sqlite3_val
25390 75 65 20 6f 62 6a 65 63 74 20 62 75 74 20 6e 6f  ue object but no
253a0 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20 66   mutex is held f
253b0 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65  or an unprotecte
253c0 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c  d.** sqlite3_val
253d0 75 65 20 6f 62 6a 65 63 74 2e 20 20 49 66 20 53  ue object.  If S
253e0 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
253f0 64 20 74 6f 20 62 65 20 73 69 6e 67 6c 65 2d 74  d to be single-t
25400 68 72 65 61 64 65 64 0a 2a 2a 20 28 77 69 74 68  hreaded.** (with
25410 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
25420 41 46 45 3d 30 5d 20 61 6e 64 20 77 69 74 68 20  AFE=0] and with 
25430 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73  [sqlite3_threads
25440 61 66 65 28 29 5d 20 72 65 74 75 72 6e 69 6e 67  afe()] returning
25450 20 30 29 0a 2a 2a 20 6f 72 20 69 66 20 53 51 4c   0).** or if SQL
25460 69 74 65 20 69 73 20 72 75 6e 20 69 6e 20 6f 6e  ite is run in on
25470 65 20 6f 66 20 72 65 64 75 63 65 64 20 6d 75 74  e of reduced mut
25480 65 78 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53 51  ex modes .** [SQ
25490 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
254a0 4c 45 54 48 52 45 41 44 5d 20 6f 72 20 5b 53 51  LETHREAD] or [SQ
254b0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
254c0 49 54 48 52 45 41 44 5d 0a 2a 2a 20 74 68 65 6e  ITHREAD].** then
254d0 20 74 68 65 72 65 20 69 73 20 6e 6f 20 64 69 73   there is no dis
254e0 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e  tinction between
254f0 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75   protected and u
25500 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71  nprotected.** sq
25510 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
25520 63 74 73 20 61 6e 64 20 74 68 65 79 20 63 61 6e  cts and they can
25530 20 62 65 20 75 73 65 64 20 69 6e 74 65 72 63 68   be used interch
25540 61 6e 67 65 61 62 6c 79 2e 20 20 48 6f 77 65 76  angeably.  Howev
25550 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78 69 6d  er,.** for maxim
25560 75 6d 20 63 6f 64 65 20 70 6f 72 74 61 62 69 6c  um code portabil
25570 69 74 79 20 69 74 20 69 73 20 72 65 63 6f 6d 6d  ity it is recomm
25580 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c 69  ended that appli
25590 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c  cations.** still
255a0 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69 6e   make the distin
255b0 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72  ction between pr
255c0 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72  otected and unpr
255d0 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74  otected.** sqlit
255e0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
255f0 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74 20 73   even when not s
25600 74 72 69 63 74 6c 79 20 72 65 71 75 69 72 65 64  trictly required
25610 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
25620 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
25630 74 73 20 74 68 61 74 20 61 72 65 20 70 61 73 73  ts that are pass
25640 65 64 20 61 73 20 70 61 72 61 6d 65 74 65 72 73  ed as parameters
25650 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d 70   into the.** imp
25660 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b  lementation of [
25670 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
25680 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
25690 73 5d 20 61 72 65 20 70 72 6f 74 65 63 74 65 64  s] are protected
256a0 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
256b0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 72  3_value object r
256c0 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73  eturned by.** [s
256d0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61  qlite3_column_va
256e0 6c 75 65 28 29 5d 20 69 73 20 75 6e 70 72 6f 74  lue()] is unprot
256f0 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74  ected..** Unprot
25700 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
25710 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d 61 79 20  lue objects may 
25720 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69 74  only be used wit
25730 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  h.** [sqlite3_re
25740 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20 61 6e  sult_value()] an
25750 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  d [sqlite3_bind_
25760 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54 68 65  value()]..** The
25770 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
25780 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 76  blob | sqlite3_v
25790 61 6c 75 65 5f 74 79 70 65 28 29 5d 20 66 61 6d  alue_type()] fam
257a0 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66  ily of.** interf
257b0 61 63 65 73 20 72 65 71 75 69 72 65 20 70 72 6f  aces require pro
257c0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
257d0 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f  alue objects..*/
257e0 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
257f0 4d 65 6d 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  Mem sqlite3_valu
25800 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  e;../*.** CAPI3R
25810 45 46 3a 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e  EF: SQL Function
25820 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74 0a   Context Object.
25830 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65 78  **.** The contex
25840 74 20 69 6e 20 77 68 69 63 68 20 61 6e 20 53 51  t in which an SQ
25850 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78 65 63 75  L function execu
25860 74 65 73 20 69 73 20 73 74 6f 72 65 64 20 69 6e  tes is stored in
25870 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   an.** sqlite3_c
25880 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e 20 20  ontext object.  
25890 5e 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e  ^A pointer to an
258a0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
258b0 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 73 20 61 6c   object.** is al
258c0 77 61 79 73 20 66 69 72 73 74 20 70 61 72 61 6d  ways first param
258d0 65 74 65 72 20 74 6f 20 5b 61 70 70 6c 69 63 61  eter to [applica
258e0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
258f0 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20   functions]..** 
25900 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  The application-
25910 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
25920 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  tion implementat
25930 69 6f 6e 20 77 69 6c 6c 20 70 61 73 73 20 74 68  ion will pass th
25940 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 68  is.** pointer th
25950 72 6f 75 67 68 20 69 6e 74 6f 20 63 61 6c 6c 73  rough into calls
25960 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   to [sqlite3_res
25970 75 6c 74 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65  ult_int | sqlite
25980 33 5f 72 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20  3_result()],.** 
25990 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61  [sqlite3_aggrega
259a0 74 65 5f 63 6f 6e 74 65 78 74 28 29 5d 2c 20 5b  te_context()], [
259b0 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74  sqlite3_user_dat
259c0 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  a()],.** [sqlite
259d0 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e  3_context_db_han
259e0 64 6c 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  dle()], [sqlite3
259f0 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2c  _get_auxdata()],
25a00 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73 71 6c 69  .** and/or [sqli
25a10 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
25a20 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  )]..*/.typedef s
25a30 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 63 6f  truct sqlite3_co
25a40 6e 74 65 78 74 20 73 71 6c 69 74 65 33 5f 63 6f  ntext sqlite3_co
25a50 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ntext;../*.** CA
25a60 50 49 33 52 45 46 3a 20 42 69 6e 64 69 6e 67 20  PI3REF: Binding 
25a70 56 61 6c 75 65 73 20 54 6f 20 50 72 65 70 61 72  Values To Prepar
25a80 65 64 20 53 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  ed Statements.**
25a90 20 4b 45 59 57 4f 52 44 53 3a 20 7b 68 6f 73 74   KEYWORDS: {host
25aa0 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 68 6f 73   parameter} {hos
25ab0 74 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 68  t parameters} {h
25ac0 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61  ost parameter na
25ad0 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  me}.** KEYWORDS:
25ae0 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 7d   {SQL parameter}
25af0 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73   {SQL parameters
25b00 7d 20 7b 70 61 72 61 6d 65 74 65 72 20 62 69 6e  } {parameter bin
25b10 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e  ding}.**.** ^(In
25b20 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
25b30 6e 74 20 74 65 78 74 20 69 6e 70 75 74 20 74 6f  nt text input to
25b40 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
25b50 65 5f 76 32 28 29 5d 20 61 6e 64 20 69 74 73 20  e_v2()] and its 
25b60 76 61 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74  variants,.** lit
25b70 65 72 61 6c 73 20 6d 61 79 20 62 65 20 72 65 70  erals may be rep
25b80 6c 61 63 65 64 20 62 79 20 61 20 5b 70 61 72 61  laced by a [para
25b90 6d 65 74 65 72 5d 20 74 68 61 74 20 6d 61 74 63  meter] that matc
25ba0 68 65 73 20 6f 6e 65 20 6f 66 20 66 6f 6c 6c 6f  hes one of follo
25bb0 77 69 6e 67 0a 2a 2a 20 74 65 6d 70 6c 61 74 65  wing.** template
25bc0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
25bd0 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e   <li>  ?.** <li>
25be0 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20    ?NNN.** <li>  
25bf0 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56  :VVV.** <li>  @V
25c00 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56 56 56  VV.** <li>  $VVV
25c10 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
25c20 49 6e 20 74 68 65 20 74 65 6d 70 6c 61 74 65 73  In the templates
25c30 20 61 62 6f 76 65 2c 20 4e 4e 4e 20 72 65 70 72   above, NNN repr
25c40 65 73 65 6e 74 73 20 61 6e 20 69 6e 74 65 67 65  esents an intege
25c50 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e  r literal,.** an
25c60 64 20 56 56 56 20 72 65 70 72 65 73 65 6e 74 73  d VVV represents
25c70 20 61 6e 20 61 6c 70 68 61 6e 75 6d 65 72 69 63   an alphanumeric
25c80 20 69 64 65 6e 74 69 66 69 65 72 2e 29 5e 20 20   identifier.)^  
25c90 5e 54 68 65 20 76 61 6c 75 65 73 20 6f 66 20 74  ^The values of t
25ca0 68 65 73 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65  hese.** paramete
25cb0 72 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65 64 20  rs (also called 
25cc0 22 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20  "host parameter 
25cd0 6e 61 6d 65 73 22 20 6f 72 20 22 53 51 4c 20 70  names" or "SQL p
25ce0 61 72 61 6d 65 74 65 72 73 22 29 0a 2a 2a 20 63  arameters").** c
25cf0 61 6e 20 62 65 20 73 65 74 20 75 73 69 6e 67 20  an be set using 
25d00 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
25d10 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 64 65  _*() routines de
25d20 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a  fined here..**.*
25d30 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67  * ^The first arg
25d40 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c  ument to the sql
25d50 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f  ite3_bind_*() ro
25d60 75 74 69 6e 65 73 20 69 73 20 61 6c 77 61 79 73  utines is always
25d70 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  .** a pointer to
25d80 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74   the [sqlite3_st
25d90 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72  mt] object retur
25da0 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c  ned from.** [sql
25db0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
25dc0 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e  )] or its varian
25dd0 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ts..**.** ^The s
25de0 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69  econd argument i
25df0 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74  s the index of t
25e00 68 65 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  he SQL parameter
25e10 20 74 6f 20 62 65 20 73 65 74 2e 0a 2a 2a 20 5e   to be set..** ^
25e20 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 53 51 4c  The leftmost SQL
25e30 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 61   parameter has a
25e40 6e 20 69 6e 64 65 78 20 6f 66 20 31 2e 20 20 5e  n index of 1.  ^
25e50 57 68 65 6e 20 74 68 65 20 73 61 6d 65 20 6e 61  When the same na
25e60 6d 65 64 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d  med.** SQL param
25e70 65 74 65 72 20 69 73 20 75 73 65 64 20 6d 6f 72  eter is used mor
25e80 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 73 65 63  e than once, sec
25e90 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65  ond and subseque
25ea0 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65 6e 63 65  nt.** occurrence
25eb0 73 20 68 61 76 65 20 74 68 65 20 73 61 6d 65 20  s have the same 
25ec0 69 6e 64 65 78 20 61 73 20 74 68 65 20 66 69 72  index as the fir
25ed0 73 74 20 6f 63 63 75 72 72 65 6e 63 65 2e 0a 2a  st occurrence..*
25ee0 2a 20 5e 54 68 65 20 69 6e 64 65 78 20 66 6f 72  * ^The index for
25ef0 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72   named parameter
25f00 73 20 63 61 6e 20 62 65 20 6c 6f 6f 6b 65 64 20  s can be looked 
25f10 75 70 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  up using the.** 
25f20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
25f30 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d  rameter_index()]
25f40 20 41 50 49 20 69 66 20 64 65 73 69 72 65 64 2e   API if desired.
25f50 20 20 5e 54 68 65 20 69 6e 64 65 78 0a 2a 2a 20    ^The index.** 
25f60 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61 72 61 6d  for "?NNN" param
25f70 65 74 65 72 73 20 69 73 20 74 68 65 20 76 61 6c  eters is the val
25f80 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54  ue of NNN..** ^T
25f90 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d 75 73  he NNN value mus
25fa0 74 20 62 65 20 62 65 74 77 65 65 6e 20 31 20 61  t be between 1 a
25fb0 6e 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  nd the [sqlite3_
25fc0 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 70 61 72 61  limit()].** para
25fd0 6d 65 74 65 72 20 5b 53 51 4c 49 54 45 5f 4c 49  meter [SQLITE_LI
25fe0 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d  MIT_VARIABLE_NUM
25ff0 42 45 52 5d 20 28 64 65 66 61 75 6c 74 20 76 61  BER] (default va
26000 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a  lue: 999)..**.**
26010 20 5e 54 68 65 20 74 68 69 72 64 20 61 72 67 75   ^The third argu
26020 6d 65 6e 74 20 69 73 20 74 68 65 20 76 61 6c 75  ment is the valu
26030 65 20 74 6f 20 62 69 6e 64 20 74 6f 20 74 68 65  e to bind to the
26040 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
26050 2a 20 5e 28 49 6e 20 74 68 6f 73 65 20 72 6f 75  * ^(In those rou
26060 74 69 6e 65 73 20 74 68 61 74 20 68 61 76 65 20  tines that have 
26070 61 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  a fourth argumen
26080 74 2c 20 69 74 73 20 76 61 6c 75 65 20 69 73 20  t, its value is 
26090 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66  the.** number of
260a0 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 70 61   bytes in the pa
260b0 72 61 6d 65 74 65 72 2e 20 20 54 6f 20 62 65 20  rameter.  To be 
260c0 63 6c 65 61 72 3a 20 74 68 65 20 76 61 6c 75 65  clear: the value
260d0 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65   is the.** numbe
260e0 72 20 6f 66 20 3c 75 3e 62 79 74 65 73 3c 2f 75  r of <u>bytes</u
260f0 3e 20 69 6e 20 74 68 65 20 76 61 6c 75 65 2c 20  > in the value, 
26100 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  not the number o
26110 66 20 63 68 61 72 61 63 74 65 72 73 2e 29 5e 0a  f characters.)^.
26120 2a 2a 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74  ** ^If the fourt
26130 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e  h parameter is n
26140 65 67 61 74 69 76 65 2c 20 74 68 65 20 6c 65 6e  egative, the len
26150 67 74 68 20 6f 66 20 74 68 65 20 73 74 72 69 6e  gth of the strin
26160 67 20 69 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  g is.** the numb
26170 65 72 20 6f 66 20 62 79 74 65 73 20 75 70 20 74  er of bytes up t
26180 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f  o the first zero
26190 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a   terminator..**.
261a0 2a 2a 20 5e 54 68 65 20 66 69 66 74 68 20 61 72  ** ^The fifth ar
261b0 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
261c0 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 20 73  3_bind_blob(), s
261d0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
261e0 28 29 2c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74  (), and.** sqlit
261f0 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29  e3_bind_text16()
26200 20 69 73 20 61 20 64 65 73 74 72 75 63 74 6f 72   is a destructor
26210 20 75 73 65 64 20 74 6f 20 64 69 73 70 6f 73 65   used to dispose
26220 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a   of the BLOB or.
26230 2a 2a 20 73 74 72 69 6e 67 20 61 66 74 65 72 20  ** string after 
26240 53 51 4c 69 74 65 20 68 61 73 20 66 69 6e 69 73  SQLite has finis
26250 68 65 64 20 77 69 74 68 20 69 74 2e 20 20 5e 54  hed with it.  ^T
26260 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73  he destructor is
26270 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 6f 20 64 69   called.** to di
26280 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f  spose of the BLO
26290 42 20 6f 72 20 73 74 72 69 6e 67 20 65 76 65 6e  B or string even
262a0 20 69 66 20 74 68 65 20 63 61 6c 6c 20 74 6f 20   if the call to 
262b0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
262c0 62 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  b(),.** sqlite3_
262d0 62 69 6e 64 5f 74 65 78 74 28 29 2c 20 6f 72 20  bind_text(), or 
262e0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
262f0 74 31 36 28 29 20 66 61 69 6c 73 2e 20 20 0a 2a  t16() fails.  .*
26300 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74 68 20  * ^If the fifth 
26310 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74  argument is.** t
26320 68 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65  he special value
26330 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d   [SQLITE_STATIC]
26340 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 61 73  , then SQLite as
26350 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a  sumes that the.*
26360 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73  * information is
26370 20 69 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d 61   in static, unma
26380 6e 61 67 65 64 20 73 70 61 63 65 20 61 6e 64 20  naged space and 
26390 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f  does not need to
263a0 20 62 65 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49   be freed..** ^I
263b0 66 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75  f the fifth argu
263c0 6d 65 6e 74 20 68 61 73 20 74 68 65 20 76 61 6c  ment has the val
263d0 75 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53  ue [SQLITE_TRANS
263e0 49 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53  IENT], then.** S
263f0 51 4c 69 74 65 20 6d 61 6b 65 73 20 69 74 73 20  QLite makes its 
26400 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79  own private copy
26410 20 6f 66 20 74 68 65 20 64 61 74 61 20 69 6d 6d   of the data imm
26420 65 64 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65  ediately, before
26430 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f  .** the sqlite3_
26440 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65  bind_*() routine
26450 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20   returns..**.** 
26460 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e  ^The sqlite3_bin
26470 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75  d_zeroblob() rou
26480 74 69 6e 65 20 62 69 6e 64 73 20 61 20 42 4c 4f  tine binds a BLO
26490 42 20 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74 68  B of length N th
264a0 61 74 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20  at.** is filled 
264b0 77 69 74 68 20 7a 65 72 6f 65 73 2e 20 20 5e 41  with zeroes.  ^A
264c0 20 7a 65 72 6f 62 6c 6f 62 20 75 73 65 73 20 61   zeroblob uses a
264d0 20 66 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66   fixed amount of
264e0 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74   memory.** (just
264f0 20 61 6e 20 69 6e 74 65 67 65 72 20 74 6f 20 68   an integer to h
26500 6f 6c 64 20 69 74 73 20 73 69 7a 65 29 20 77 68  old its size) wh
26510 69 6c 65 20 69 74 20 69 73 20 62 65 69 6e 67 20  ile it is being 
26520 70 72 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65  processed..** Ze
26530 72 6f 62 6c 6f 62 73 20 61 72 65 20 69 6e 74 65  roblobs are inte
26540 6e 64 65 64 20 74 6f 20 73 65 72 76 65 20 61 73  nded to serve as
26550 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f   placeholders fo
26560 72 20 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a  r BLOBs whose.**
26570 20 63 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74 65   content is late
26580 72 20 77 72 69 74 74 65 6e 20 75 73 69 6e 67 0a  r written using.
26590 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  ** [sqlite3_blob
265a0 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e  _open | incremen
265b0 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f  tal BLOB I/O] ro
265c0 75 74 69 6e 65 73 2e 0a 2a 2a 20 5e 41 20 6e 65  utines..** ^A ne
265d0 67 61 74 69 76 65 20 76 61 6c 75 65 20 66 6f 72  gative value for
265e0 20 74 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72 65   the zeroblob re
265f0 73 75 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f 2d  sults in a zero-
26600 6c 65 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a  length BLOB..**.
26610 2a 2a 20 5e 49 66 20 61 6e 79 20 6f 66 20 74 68  ** ^If any of th
26620 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
26630 28 29 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  () routines are 
26640 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55  called with a NU
26650 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 66 6f  LL pointer.** fo
26660 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  r the [prepared 
26670 73 74 61 74 65 6d 65 6e 74 5d 20 6f 72 20 77 69  statement] or wi
26680 74 68 20 61 20 70 72 65 70 61 72 65 64 20 73 74  th a prepared st
26690 61 74 65 6d 65 6e 74 20 66 6f 72 20 77 68 69 63  atement for whic
266a0 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74  h.** [sqlite3_st
266b0 65 70 28 29 5d 20 68 61 73 20 62 65 65 6e 20 63  ep()] has been c
266c0 61 6c 6c 65 64 20 6d 6f 72 65 20 72 65 63 65 6e  alled more recen
266d0 74 6c 79 20 74 68 61 6e 20 5b 73 71 6c 69 74 65  tly than [sqlite
266e0 33 5f 72 65 73 65 74 28 29 5d 2c 0a 2a 2a 20 74  3_reset()],.** t
266f0 68 65 6e 20 74 68 65 20 63 61 6c 6c 20 77 69 6c  hen the call wil
26700 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  l return [SQLITE
26710 5f 4d 49 53 55 53 45 5d 2e 20 20 49 66 20 61 6e  _MISUSE].  If an
26720 79 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 28  y sqlite3_bind_(
26730 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 69 73 20  ).** routine is 
26740 70 61 73 73 65 64 20 61 20 5b 70 72 65 70 61 72  passed a [prepar
26750 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
26760 61 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61  at has been fina
26770 6c 69 7a 65 64 2c 20 74 68 65 0a 2a 2a 20 72 65  lized, the.** re
26780 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65  sult is undefine
26790 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 68  d and probably h
267a0 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42  armful..**.** ^B
267b0 69 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f 74 20  indings are not 
267c0 63 6c 65 61 72 65 64 20 62 79 20 74 68 65 20 5b  cleared by the [
267d0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
267e0 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 5e 55 6e   routine..** ^Un
267f0 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 73  bound parameters
26800 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64   are interpreted
26810 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   as NULL..**.** 
26820 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e  ^The sqlite3_bin
26830 64 5f 2a 20 72 6f 75 74 69 6e 65 73 20 72 65 74  d_* routines ret
26840 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  urn [SQLITE_OK] 
26850 6f 6e 20 73 75 63 63 65 73 73 20 6f 72 20 61 6e  on success or an
26860 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  .** [error code]
26870 20 69 66 20 61 6e 79 74 68 69 6e 67 20 67 6f 65   if anything goe
26880 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53 51  s wrong..** ^[SQ
26890 4c 49 54 45 5f 52 41 4e 47 45 5d 20 69 73 20 72  LITE_RANGE] is r
268a0 65 74 75 72 6e 65 64 20 69 66 20 74 68 65 20 70  eturned if the p
268b0 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65  arameter.** inde
268c0 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  x is out of rang
268d0 65 2e 20 20 5e 5b 53 51 4c 49 54 45 5f 4e 4f 4d  e.  ^[SQLITE_NOM
268e0 45 4d 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20  EM] is returned 
268f0 69 66 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c  if malloc() fail
26900 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  s..**.** See als
26910 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  o: [sqlite3_bind
26920 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74  _parameter_count
26930 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
26940 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
26950 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71  name()], and [sq
26960 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
26970 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a  eter_index()]..*
26980 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
26990 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c   sqlite3_bind_bl
269a0 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ob(sqlite3_stmt*
269b0 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69  , int, const voi
269c0 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28  d*, int n, void(
269d0 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49  *)(void*));.SQLI
269e0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
269f0 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c 65 28 73  e3_bind_double(s
26a00 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
26a10 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 53 51 4c 49  t, double);.SQLI
26a20 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
26a30 65 33 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69  e3_bind_int(sqli
26a40 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
26a50 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  int);.SQLITE_API
26a60 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e   int sqlite3_bin
26a70 64 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f  d_int64(sqlite3_
26a80 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69  stmt*, int, sqli
26a90 74 65 33 5f 69 6e 74 36 34 29 3b 0a 53 51 4c 49  te3_int64);.SQLI
26aa0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
26ab0 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c  e3_bind_null(sql
26ac0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29  ite3_stmt*, int)
26ad0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
26ae0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
26af0 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  xt(sqlite3_stmt*
26b00 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61  , int, const cha
26b10 72 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28  r*, int n, void(
26b20 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49  *)(void*));.SQLI
26b30 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
26b40 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 73  e3_bind_text16(s
26b50 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
26b60 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  t, const void*, 
26b70 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  int, void(*)(voi
26b80 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  d*));.SQLITE_API
26b90 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e   int sqlite3_bin
26ba0 64 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f  d_value(sqlite3_
26bb0 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73  stmt*, int, cons
26bc0 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t sqlite3_value*
26bd0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
26be0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a  t sqlite3_bind_z
26bf0 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  eroblob(sqlite3_
26c00 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20  stmt*, int, int 
26c10 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  n);../*.** CAPI3
26c20 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 53  REF: Number Of S
26c30 51 4c 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a  QL Parameters.**
26c40 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e  .** ^This routin
26c50 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  e can be used to
26c60 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72   find the number
26c70 20 6f 66 20 5b 53 51 4c 20 70 61 72 61 6d 65 74   of [SQL paramet
26c80 65 72 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70 72  ers].** in a [pr
26c90 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
26ca0 5d 2e 20 20 53 51 4c 20 70 61 72 61 6d 65 74 65  ].  SQL paramete
26cb0 72 73 20 61 72 65 20 74 6f 6b 65 6e 73 20 6f 66  rs are tokens of
26cc0 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22   the.** form "?"
26cd0 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41 22  , "?NNN", ":AAA"
26ce0 2c 20 22 24 41 41 41 22 2c 20 6f 72 20 22 40 41  , "$AAA", or "@A
26cf0 41 41 22 20 74 68 61 74 20 73 65 72 76 65 20 61  AA" that serve a
26d00 73 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 65 72  s.** placeholder
26d10 73 20 66 6f 72 20 76 61 6c 75 65 73 20 74 68 61  s for values tha
26d20 74 20 61 72 65 20 5b 73 71 6c 69 74 65 33 5f 62  t are [sqlite3_b
26d30 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e 64  ind_blob | bound
26d40 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 70 61 72 61  ].** to the para
26d50 6d 65 74 65 72 73 20 61 74 20 61 20 6c 61 74 65  meters at a late
26d60 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28  r time..**.** ^(
26d70 54 68 69 73 20 72 6f 75 74 69 6e 65 20 61 63 74  This routine act
26d80 75 61 6c 6c 79 20 72 65 74 75 72 6e 73 20 74 68  ually returns th
26d90 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 6c  e index of the l
26da0 61 72 67 65 73 74 20 28 72 69 67 68 74 6d 6f 73  argest (rightmos
26db0 74 29 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e  t).** parameter.
26dc0 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d 73 20 65   For all forms e
26dd0 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73  xcept ?NNN, this
26de0 20 77 69 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64   will correspond
26df0 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65   to the.** numbe
26e00 72 20 6f 66 20 75 6e 69 71 75 65 20 70 61 72 61  r of unique para
26e10 6d 65 74 65 72 73 2e 20 20 49 66 20 70 61 72 61  meters.  If para
26e20 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 3f 4e  meters of the ?N
26e30 4e 4e 20 66 6f 72 6d 20 61 72 65 20 75 73 65 64  NN form are used
26e40 2c 0a 2a 2a 20 74 68 65 72 65 20 6d 61 79 20 62  ,.** there may b
26e50 65 20 67 61 70 73 20 69 6e 20 74 68 65 20 6c 69  e gaps in the li
26e60 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  st.)^.**.** See 
26e70 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62  also: [sqlite3_b
26e80 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33  ind_blob|sqlite3
26e90 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71  _bind()],.** [sq
26ea0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
26eb0 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e  eter_name()], an
26ec0 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  d.** [sqlite3_bi
26ed0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
26ee0 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45  ex()]..*/.SQLITE
26ef0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
26f00 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
26f10 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  count(sqlite3_st
26f20 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  mt*);../*.** CAP
26f30 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41  I3REF: Name Of A
26f40 20 48 6f 73 74 20 50 61 72 61 6d 65 74 65 72 0a   Host Parameter.
26f50 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
26f60 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
26f70 72 5f 6e 61 6d 65 28 50 2c 4e 29 20 69 6e 74 65  r_name(P,N) inte
26f80 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a  rface returns.**
26f90 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
26fa0 20 4e 2d 74 68 20 5b 53 51 4c 20 70 61 72 61 6d   N-th [SQL param
26fb0 65 74 65 72 5d 20 69 6e 20 74 68 65 20 5b 70 72  eter] in the [pr
26fc0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
26fd0 5d 20 50 2e 0a 2a 2a 20 5e 28 53 51 4c 20 70 61  ] P..** ^(SQL pa
26fe0 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20  rameters of the 
26ff0 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20 22  form "?NNN" or "
27000 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20  :AAA" or "@AAA" 
27010 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 68 61 76  or "$AAA".** hav
27020 65 20 61 20 6e 61 6d 65 20 77 68 69 63 68 20 69  e a name which i
27030 73 20 74 68 65 20 73 74 72 69 6e 67 20 22 3f 4e  s the string "?N
27040 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72  NN" or ":AAA" or
27050 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41   "@AAA" or "$AAA
27060 22 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c  ".** respectivel
27070 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77  y..** In other w
27080 6f 72 64 73 2c 20 74 68 65 20 69 6e 69 74 69 61  ords, the initia
27090 6c 20 22 3a 22 20 6f 72 20 22 24 22 20 6f 72 20  l ":" or "$" or 
270a0 22 40 22 20 6f 72 20 22 3f 22 0a 2a 2a 20 69 73  "@" or "?".** is
270b0 20 69 6e 63 6c 75 64 65 64 20 61 73 20 70 61 72   included as par
270c0 74 20 6f 66 20 74 68 65 20 6e 61 6d 65 2e 29 5e  t of the name.)^
270d0 0a 2a 2a 20 5e 50 61 72 61 6d 65 74 65 72 73 20  .** ^Parameters 
270e0 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 22 20  of the form "?" 
270f0 77 69 74 68 6f 75 74 20 61 20 66 6f 6c 6c 6f 77  without a follow
27100 69 6e 67 20 69 6e 74 65 67 65 72 20 68 61 76 65  ing integer have
27110 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20   no name.** and 
27120 61 72 65 20 72 65 66 65 72 72 65 64 20 74 6f 20  are referred to 
27130 61 73 20 22 6e 61 6d 65 6c 65 73 73 22 20 6f 72  as "nameless" or
27140 20 22 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61   "anonymous para
27150 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e  meters"..**.** ^
27160 54 68 65 20 66 69 72 73 74 20 68 6f 73 74 20 70  The first host p
27170 61 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20  arameter has an 
27180 69 6e 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20  index of 1, not 
27190 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  0..**.** ^If the
271a0 20 76 61 6c 75 65 20 4e 20 69 73 20 6f 75 74 20   value N is out 
271b0 6f 66 20 72 61 6e 67 65 20 6f 72 20 69 66 20 74  of range or if t
271c0 68 65 20 4e 2d 74 68 20 70 61 72 61 6d 65 74 65  he N-th paramete
271d0 72 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73  r is.** nameless
271e0 2c 20 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72  , then NULL is r
271f0 65 74 75 72 6e 65 64 2e 20 20 5e 54 68 65 20 72  eturned.  ^The r
27200 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69  eturned string i
27210 73 0a 2a 2a 20 61 6c 77 61 79 73 20 69 6e 20 55  s.** always in U
27220 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65 76  TF-8 encoding ev
27230 65 6e 20 69 66 20 74 68 65 20 6e 61 6d 65 64 20  en if the named 
27240 70 61 72 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a  parameter was.**
27250 20 6f 72 69 67 69 6e 61 6c 6c 79 20 73 70 65 63   originally spec
27260 69 66 69 65 64 20 61 73 20 55 54 46 2d 31 36 20  ified as UTF-16 
27270 69 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  in [sqlite3_prep
27280 61 72 65 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b  are16()] or.** [
27290 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
272a0 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53  6_v2()]..**.** S
272b0 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
272c0 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69  3_bind_blob|sqli
272d0 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20  te3_bind()],.** 
272e0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
272f0 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d  rameter_count()]
27300 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  , and.** [sqlite
27310 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
27320 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51  _index()]..*/.SQ
27330 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63  LITE_API const c
27340 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 62 69 6e  har *sqlite3_bin
27350 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65  d_parameter_name
27360 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
27370 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
27380 49 33 52 45 46 3a 20 49 6e 64 65 78 20 4f 66 20  I3REF: Index Of 
27390 41 20 50 61 72 61 6d 65 74 65 72 20 57 69 74 68  A Parameter With
273a0 20 41 20 47 69 76 65 6e 20 4e 61 6d 65 0a 2a 2a   A Given Name.**
273b0 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20  .** ^Return the 
273c0 69 6e 64 65 78 20 6f 66 20 61 6e 20 53 51 4c 20  index of an SQL 
273d0 70 61 72 61 6d 65 74 65 72 20 67 69 76 65 6e 20  parameter given 
273e0 69 74 73 20 6e 61 6d 65 2e 20 20 5e 54 68 65 0a  its name.  ^The.
273f0 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75 65 20 72  ** index value r
27400 65 74 75 72 6e 65 64 20 69 73 20 73 75 69 74 61  eturned is suita
27410 62 6c 65 20 66 6f 72 20 75 73 65 20 61 73 20 74  ble for use as t
27420 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72  he second.** par
27430 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
27440 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c  e3_bind_blob|sql
27450 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20 5e  ite3_bind()].  ^
27460 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65 74  A zero.** is ret
27470 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74 63  urned if no matc
27480 68 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20 69  hing parameter i
27490 73 20 66 6f 75 6e 64 2e 20 20 5e 54 68 65 20 70  s found.  ^The p
274a0 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d 65  arameter.** name
274b0 20 6d 75 73 74 20 62 65 20 67 69 76 65 6e 20 69   must be given i
274c0 6e 20 55 54 46 2d 38 20 65 76 65 6e 20 69 66 20  n UTF-8 even if 
274d0 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61  the original sta
274e0 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 70 72  tement.** was pr
274f0 65 70 61 72 65 64 20 66 72 6f 6d 20 55 54 46 2d  epared from UTF-
27500 31 36 20 74 65 78 74 20 75 73 69 6e 67 20 5b 73  16 text using [s
27510 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
27520 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65  _v2()]..**.** Se
27530 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
27540 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74  _bind_blob|sqlit
27550 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b  e3_bind()],.** [
27560 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
27570 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c  ameter_count()],
27580 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
27590 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
275a0 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c  index()]..*/.SQL
275b0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
275c0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
275d0 65 72 5f 69 6e 64 65 78 28 73 71 6c 69 74 65 33  er_index(sqlite3
275e0 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68  _stmt*, const ch
275f0 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a  ar *zName);../*.
27600 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73  ** CAPI3REF: Res
27610 65 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20  et All Bindings 
27620 4f 6e 20 41 20 50 72 65 70 61 72 65 64 20 53 74  On A Prepared St
27630 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 43  atement.**.** ^C
27640 6f 6e 74 72 61 72 79 20 74 6f 20 74 68 65 20 69  ontrary to the i
27650 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d 61 6e 79  ntuition of many
27660 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  , [sqlite3_reset
27670 28 29 5d 20 64 6f 65 73 20 6e 6f 74 20 72 65 73  ()] does not res
27680 65 74 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74  et.** the [sqlit
27690 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62  e3_bind_blob | b
276a0 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 20 5b 70  indings] on a [p
276b0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
276c0 74 5d 2e 0a 2a 2a 20 5e 55 73 65 20 74 68 69 73  t]..** ^Use this
276d0 20 72 6f 75 74 69 6e 65 20 74 6f 20 72 65 73 65   routine to rese
276e0 74 20 61 6c 6c 20 68 6f 73 74 20 70 61 72 61 6d  t all host param
276f0 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a  eters to NULL..*
27700 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
27710 20 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62   sqlite3_clear_b
27720 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f  indings(sqlite3_
27730 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  stmt*);../*.** C
27740 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20  API3REF: Number 
27750 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20  Of Columns In A 
27760 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a  Result Set.**.**
27770 20 5e 52 65 74 75 72 6e 20 74 68 65 20 6e 75 6d   ^Return the num
27780 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
27790 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  n the result set
277a0 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65   returned by the
277b0 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
277c0 61 74 65 6d 65 6e 74 5d 2e 20 5e 54 68 69 73 20  atement]. ^This 
277d0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
277e0 30 20 69 66 20 70 53 74 6d 74 20 69 73 20 61 6e  0 if pStmt is an
277f0 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e   SQL.** statemen
27800 74 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20  t that does not 
27810 72 65 74 75 72 6e 20 64 61 74 61 20 28 66 6f 72  return data (for
27820 20 65 78 61 6d 70 6c 65 20 61 6e 20 5b 55 50 44   example an [UPD
27830 41 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  ATE])..**.** See
27840 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
27850 64 61 74 61 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f  data_count()].*/
27860 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
27870 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63  sqlite3_column_c
27880 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  ount(sqlite3_stm
27890 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
278a0 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 75  * CAPI3REF: Colu
278b0 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41 20 52 65  mn Names In A Re
278c0 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e  sult Set.**.** ^
278d0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
278e0 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 61  eturn the name a
278f0 73 73 69 67 6e 65 64 20 74 6f 20 61 20 70 61 72  ssigned to a par
27900 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a  ticular column.*
27910 2a 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20  * in the result 
27920 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54  set of a [SELECT
27930 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 54  ] statement.  ^T
27940 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  he sqlite3_colum
27950 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65  n_name().** inte
27960 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
27970 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72  pointer to a zer
27980 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
27990 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61 6e 64  -8 string.** and
279a0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
279b0 6e 61 6d 65 31 36 28 29 20 72 65 74 75 72 6e 73  name16() returns
279c0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
279d0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a  zero-terminated.
279e0 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67  ** UTF-16 string
279f0 2e 20 20 5e 54 68 65 20 66 69 72 73 74 20 70 61  .  ^The first pa
27a00 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b  rameter is the [
27a10 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
27a20 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d 70 6c  nt].** that impl
27a30 65 6d 65 6e 74 73 20 74 68 65 20 5b 53 45 4c 45  ements the [SELE
27a40 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 5e  CT] statement. ^
27a50 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
27a60 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 63  eter is the.** c
27a70 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 20 5e  olumn number.  ^
27a80 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c  The leftmost col
27a90 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20 30 2e  umn is number 0.
27aa0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75  .**.** ^The retu
27ab0 72 6e 65 64 20 73 74 72 69 6e 67 20 70 6f 69 6e  rned string poin
27ac0 74 65 72 20 69 73 20 76 61 6c 69 64 20 75 6e 74  ter is valid unt
27ad0 69 6c 20 65 69 74 68 65 72 20 74 68 65 20 5b 70  il either the [p
27ae0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
27af0 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74 72 6f 79  t].** is destroy
27b00 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66  ed by [sqlite3_f
27b10 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e  inalize()] or un
27b20 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e  til the statemen
27b30 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c  t is automatical
27b40 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64  ly.** reprepared
27b50 20 62 79 20 74 68 65 20 66 69 72 73 74 20 63 61   by the first ca
27b60 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
27b70 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72  tep()] for a par
27b80 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f  ticular run.** o
27b90 72 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74  r until the next
27ba0 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69   call to.** sqli
27bb0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28  te3_column_name(
27bc0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ) or sqlite3_col
27bd0 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f 6e 20  umn_name16() on 
27be0 74 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e  the same column.
27bf0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74  .**.** ^If sqlit
27c00 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c  e3_malloc() fail
27c10 73 20 64 75 72 69 6e 67 20 74 68 65 20 70 72 6f  s during the pro
27c20 63 65 73 73 69 6e 67 20 6f 66 20 65 69 74 68 65  cessing of eithe
27c30 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f  r routine.** (fo
27c40 72 20 65 78 61 6d 70 6c 65 20 64 75 72 69 6e 67  r example during
27c50 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72   a conversion fr
27c60 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55 54 46 2d  om UTF-8 to UTF-
27c70 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55  16) then a.** NU
27c80 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65  LL pointer is re
27c90 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  turned..**.** ^T
27ca0 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 72 65 73  he name of a res
27cb0 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68  ult column is th
27cc0 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 22  e value of the "
27cd0 41 53 22 20 63 6c 61 75 73 65 20 66 6f 72 0a 2a  AS" clause for.*
27ce0 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 69  * that column, i
27cf0 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 41 53  f there is an AS
27d00 20 63 6c 61 75 73 65 2e 20 20 49 66 20 74 68 65   clause.  If the
27d10 72 65 20 69 73 20 6e 6f 20 41 53 20 63 6c 61 75  re is no AS clau
27d20 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6e  se.** then the n
27d30 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d  ame of the colum
27d40 6e 20 69 73 20 75 6e 73 70 65 63 69 66 69 65 64  n is unspecified
27d50 20 61 6e 64 20 6d 61 79 20 63 68 61 6e 67 65 20   and may change 
27d60 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65  from.** one rele
27d70 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20 74 6f  ase of SQLite to
27d80 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a 53 51   the next..*/.SQ
27d90 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63  LITE_API const c
27da0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
27db0 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  umn_name(sqlite3
27dc0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a  _stmt*, int N);.
27dd0 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
27de0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
27df0 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c  olumn_name16(sql
27e00 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
27e10 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  N);../*.** CAPI3
27e20 52 45 46 3a 20 53 6f 75 72 63 65 20 4f 66 20 44  REF: Source Of D
27e30 61 74 61 20 49 6e 20 41 20 51 75 65 72 79 20 52  ata In A Query R
27e40 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  esult.**.** ^The
27e50 73 65 20 72 6f 75 74 69 6e 65 73 20 70 72 6f 76  se routines prov
27e60 69 64 65 20 61 20 6d 65 61 6e 73 20 74 6f 20 64  ide a means to d
27e70 65 74 65 72 6d 69 6e 65 20 74 68 65 20 64 61 74  etermine the dat
27e80 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e  abase, table, an
27e90 64 0a 2a 2a 20 74 61 62 6c 65 20 63 6f 6c 75 6d  d.** table colum
27ea0 6e 20 74 68 61 74 20 69 73 20 74 68 65 20 6f 72  n that is the or
27eb0 69 67 69 6e 20 6f 66 20 61 20 70 61 72 74 69 63  igin of a partic
27ec0 75 6c 61 72 20 72 65 73 75 6c 74 20 63 6f 6c 75  ular result colu
27ed0 6d 6e 20 69 6e 0a 2a 2a 20 5b 53 45 4c 45 43 54  mn in.** [SELECT
27ee0 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20  ] statement..** 
27ef0 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65  ^The name of the
27f00 20 64 61 74 61 62 61 73 65 20 6f 72 20 74 61 62   database or tab
27f10 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e  le or column can
27f20 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 73 0a   be returned as.
27f30 2a 2a 20 65 69 74 68 65 72 20 61 20 55 54 46 2d  ** either a UTF-
27f40 38 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69  8 or UTF-16 stri
27f50 6e 67 2e 20 20 5e 54 68 65 20 5f 64 61 74 61 62  ng.  ^The _datab
27f60 61 73 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65  ase_ routines re
27f70 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61  turn.** the data
27f80 62 61 73 65 20 6e 61 6d 65 2c 20 74 68 65 20 5f  base name, the _
27f90 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73 20  table_ routines 
27fa0 72 65 74 75 72 6e 20 74 68 65 20 74 61 62 6c 65  return the table
27fb0 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 68   name, and.** th
27fc0 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69 6e  e origin_ routin
27fd0 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 63 6f  es return the co
27fe0 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 54  lumn name..** ^T
27ff0 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69  he returned stri
28000 6e 67 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69  ng is valid unti
28010 6c 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  l the [prepared 
28020 73 74 61 74 65 6d 65 6e 74 5d 20 69 73 20 64 65  statement] is de
28030 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73 69 6e 67  stroyed.** using
28040 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
28050 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74  ze()] or until t
28060 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
28070 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a  automatically.**
28080 20 72 65 70 72 65 70 61 72 65 64 20 62 79 20 74   reprepared by t
28090 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20 74 6f  he first call to
280a0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
280b0 5d 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c  ] for a particul
280c0 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74  ar run.** or unt
280d0 69 6c 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f  il the same info
280e0 72 6d 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65  rmation is reque
280f0 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e  sted.** again in
28100 20 61 20 64 69 66 66 65 72 65 6e 74 20 65 6e 63   a different enc
28110 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  oding..**.** ^Th
28120 65 20 6e 61 6d 65 73 20 72 65 74 75 72 6e 65 64  e names returned
28130 20 61 72 65 20 74 68 65 20 6f 72 69 67 69 6e 61   are the origina
28140 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d  l un-aliased nam
28150 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74  es of the.** dat
28160 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e  abase, table, an
28170 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20  d column..**.** 
28180 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d  ^The first argum
28190 65 6e 74 20 74 6f 20 74 68 65 73 65 20 69 6e 74  ent to these int
281a0 65 72 66 61 63 65 73 20 69 73 20 61 20 5b 70 72  erfaces is a [pr
281b0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
281c0 5d 2e 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e  ]..** ^These fun
281d0 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e  ctions return in
281e0 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20  formation about 
281f0 74 68 65 20 4e 74 68 20 72 65 73 75 6c 74 20 63  the Nth result c
28200 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62  olumn returned b
28210 79 0a 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65  y.** the stateme
28220 6e 74 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74  nt, where N is t
28230 68 65 20 73 65 63 6f 6e 64 20 66 75 6e 63 74 69  he second functi
28240 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20  on argument..** 
28250 5e 54 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63  ^The left-most c
28260 6f 6c 75 6d 6e 20 69 73 20 63 6f 6c 75 6d 6e 20  olumn is column 
28270 30 20 66 6f 72 20 74 68 65 73 65 20 72 6f 75 74  0 for these rout
28280 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ines..**.** ^If 
28290 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72  the Nth column r
282a0 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 20 73  eturned by the s
282b0 74 61 74 65 6d 65 6e 74 20 69 73 20 61 6e 20 65  tatement is an e
282c0 78 70 72 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20  xpression or.** 
282d0 73 75 62 71 75 65 72 79 20 61 6e 64 20 69 73 20  subquery and is 
282e0 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c  not a column val
282f0 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20 6f 66 20  ue, then all of 
28300 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  these functions 
28310 72 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20  return.** NULL. 
28320 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 20   ^These routine 
28330 6d 69 67 68 74 20 61 6c 73 6f 20 72 65 74 75 72  might also retur
28340 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d 65 6d 6f  n NULL if a memo
28350 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72  ry allocation er
28360 72 6f 72 0a 2a 2a 20 6f 63 63 75 72 73 2e 20 20  ror.** occurs.  
28370 5e 4f 74 68 65 72 77 69 73 65 2c 20 74 68 65 79  ^Otherwise, they
28380 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65   return the name
28390 20 6f 66 20 74 68 65 20 61 74 74 61 63 68 65 64   of the attached
283a0 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65   database, table
283b0 2c 0a 2a 2a 20 6f 72 20 63 6f 6c 75 6d 6e 20 74  ,.** or column t
283c0 68 61 74 20 71 75 65 72 79 20 72 65 73 75 6c 74  hat query result
283d0 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65 78 74 72   column was extr
283e0 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a  acted from..**.*
283f0 2a 20 5e 41 73 20 77 69 74 68 20 61 6c 6c 20 6f  * ^As with all o
28400 74 68 65 72 20 53 51 4c 69 74 65 20 41 50 49 73  ther SQLite APIs
28410 2c 20 74 68 6f 73 65 20 77 68 6f 73 65 20 6e 61  , those whose na
28420 6d 65 73 20 65 6e 64 20 77 69 74 68 20 22 31 36  mes end with "16
28430 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55 54 46 2d  " return.** UTF-
28440 31 36 20 65 6e 63 6f 64 65 64 20 73 74 72 69 6e  16 encoded strin
28450 67 73 20 61 6e 64 20 74 68 65 20 6f 74 68 65 72  gs and the other
28460 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72   functions retur
28470 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e  n UTF-8..**.** ^
28480 54 68 65 73 65 20 41 50 49 73 20 61 72 65 20 6f  These APIs are o
28490 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66  nly available if
284a0 20 74 68 65 20 6c 69 62 72 61 72 79 20 77 61 73   the library was
284b0 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74   compiled with t
284c0 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e  he.** [SQLITE_EN
284d0 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41  ABLE_COLUMN_META
284e0 44 41 54 41 5d 20 43 2d 70 72 65 70 72 6f 63 65  DATA] C-preproce
284f0 73 73 6f 72 20 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a  ssor symbol..**.
28500 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72  ** If two or mor
28510 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f  e threads call o
28520 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68  ne or more of th
28530 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 67 61  ese routines aga
28540 69 6e 73 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a  inst the same.**
28550 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
28560 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61  ent and column a
28570 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20  t the same time 
28580 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73  then the results
28590 20 61 72 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65   are.** undefine
285a0 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20  d..**.** If two 
285b0 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20  or more threads 
285c0 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  call one or more
285d0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
285e0 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d  umn_database_nam
285f0 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64  e | column metad
28600 61 74 61 20 69 6e 74 65 72 66 61 63 65 73 5d 0a  ata interfaces].
28610 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20  ** for the same 
28620 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
28630 65 6e 74 5d 20 61 6e 64 20 72 65 73 75 6c 74 20  ent] and result 
28640 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20 74 68 65  column.** at the
28650 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20   same time then 
28660 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
28670 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 53 51  undefined..*/.SQ
28680 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63  LITE_API const c
28690 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
286a0 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d  umn_database_nam
286b0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
286c0 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  int);.SQLITE_API
286d0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c   const void *sql
286e0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61  ite3_column_data
286f0 62 61 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69  base_name16(sqli
28700 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
28710 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
28720 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
28730 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65  olumn_table_name
28740 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
28750 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  nt);.SQLITE_API 
28760 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
28770 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65  te3_column_table
28780 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f  _name16(sqlite3_
28790 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49  stmt*,int);.SQLI
287a0 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61  TE_API const cha
287b0 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
287c0 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71  n_origin_name(sq
287d0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
287e0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  ;.SQLITE_API con
287f0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
28800 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e  _column_origin_n
28810 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ame16(sqlite3_st
28820 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  mt*,int);../*.**
28830 20 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c 61   CAPI3REF: Decla
28840 72 65 64 20 44 61 74 61 74 79 70 65 20 4f 66 20  red Datatype Of 
28850 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a  A Query Result.*
28860 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 72 73 74  *.** ^(The first
28870 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
28880 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
28890 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 69 73  ent]..** If this
288a0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20   statement is a 
288b0 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
288c0 6e 74 20 61 6e 64 20 74 68 65 20 4e 74 68 20 63  nt and the Nth c
288d0 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20  olumn of the.** 
288e0 72 65 74 75 72 6e 65 64 20 72 65 73 75 6c 74 20  returned result 
288f0 73 65 74 20 6f 66 20 74 68 61 74 20 5b 53 45 4c  set of that [SEL
28900 45 43 54 5d 20 69 73 20 61 20 74 61 62 6c 65 20  ECT] is a table 
28910 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a  column (not an.*
28920 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20  * expression or 
28930 73 75 62 71 75 65 72 79 29 20 74 68 65 6e 20 74  subquery) then t
28940 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65  he declared type
28950 20 6f 66 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a   of the table.**
28960 20 63 6f 6c 75 6d 6e 20 69 73 20 72 65 74 75 72   column is retur
28970 6e 65 64 2e 29 5e 20 20 5e 49 66 20 74 68 65 20  ned.)^  ^If the 
28980 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  Nth column of th
28990 65 20 72 65 73 75 6c 74 20 73 65 74 20 69 73 20  e result set is 
289a0 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e  an.** expression
289b0 20 6f 72 20 73 75 62 71 75 65 72 79 2c 20 74 68   or subquery, th
289c0 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  en a NULL pointe
289d0 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  r is returned..*
289e0 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20  * ^The returned 
289f0 73 74 72 69 6e 67 20 69 73 20 61 6c 77 61 79 73  string is always
28a00 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2e 0a   UTF-8 encoded..
28a10 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d  **.** ^(For exam
28a20 70 6c 65 2c 20 67 69 76 65 6e 20 74 68 65 20 64  ple, given the d
28a30 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 3a 0a  atabase schema:.
28a40 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20 54 41 42  **.** CREATE TAB
28a50 4c 45 20 74 31 28 63 31 20 56 41 52 49 41 4e 54  LE t1(c1 VARIANT
28a60 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68 65  );.**.** and the
28a70 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65   following state
28a80 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69  ment to be compi
28a90 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43  led:.**.** SELEC
28aa0 54 20 63 31 20 2b 20 31 2c 20 63 31 20 46 52 4f  T c1 + 1, c1 FRO
28ab0 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73  M t1;.**.** this
28ac0 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c 64 20 72   routine would r
28ad0 65 74 75 72 6e 20 74 68 65 20 73 74 72 69 6e 67  eturn the string
28ae0 20 22 56 41 52 49 41 4e 54 22 20 66 6f 72 20 74   "VARIANT" for t
28af0 68 65 20 73 65 63 6f 6e 64 20 72 65 73 75 6c 74  he second result
28b00 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31  .** column (i==1
28b10 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f  ), and a NULL po
28b20 69 6e 74 65 72 20 66 6f 72 20 74 68 65 20 66 69  inter for the fi
28b30 72 73 74 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  rst result colum
28b40 6e 20 28 69 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a  n (i==0).)^.**.*
28b50 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 64  * ^SQLite uses d
28b60 79 6e 61 6d 69 63 20 72 75 6e 2d 74 69 6d 65 20  ynamic run-time 
28b70 74 79 70 69 6e 67 2e 20 20 5e 53 6f 20 6a 75 73  typing.  ^So jus
28b80 74 20 62 65 63 61 75 73 65 20 61 20 63 6f 6c 75  t because a colu
28b90 6d 6e 0a 2a 2a 20 69 73 20 64 65 63 6c 61 72 65  mn.** is declare
28ba0 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20 61 20 70  d to contain a p
28bb0 61 72 74 69 63 75 6c 61 72 20 74 79 70 65 20 64  articular type d
28bc0 6f 65 73 20 6e 6f 74 20 6d 65 61 6e 20 74 68 61  oes not mean tha
28bd0 74 20 74 68 65 0a 2a 2a 20 64 61 74 61 20 73 74  t the.** data st
28be0 6f 72 65 64 20 69 6e 20 74 68 61 74 20 63 6f 6c  ored in that col
28bf0 75 6d 6e 20 69 73 20 6f 66 20 74 68 65 20 64 65  umn is of the de
28c00 63 6c 61 72 65 64 20 74 79 70 65 2e 20 20 53 51  clared type.  SQ
28c10 4c 69 74 65 20 69 73 0a 2a 2a 20 73 74 72 6f 6e  Lite is.** stron
28c20 67 6c 79 20 74 79 70 65 64 2c 20 62 75 74 20 74  gly typed, but t
28c30 68 65 20 74 79 70 69 6e 67 20 69 73 20 64 79 6e  he typing is dyn
28c40 61 6d 69 63 20 6e 6f 74 20 73 74 61 74 69 63 2e  amic not static.
28c50 20 20 5e 54 79 70 65 0a 2a 2a 20 69 73 20 61 73    ^Type.** is as
28c60 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 69 6e  sociated with in
28c70 64 69 76 69 64 75 61 6c 20 76 61 6c 75 65 73 2c  dividual values,
28c80 20 6e 6f 74 20 77 69 74 68 20 74 68 65 20 63 6f   not with the co
28c90 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 75 73 65 64  ntainers.** used
28ca0 20 74 6f 20 68 6f 6c 64 20 74 68 6f 73 65 20 76   to hold those v
28cb0 61 6c 75 65 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45  alues..*/.SQLITE
28cc0 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20  _API const char 
28cd0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
28ce0 64 65 63 6c 74 79 70 65 28 73 71 6c 69 74 65 33  decltype(sqlite3
28cf0 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c  _stmt*,int);.SQL
28d00 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f  ITE_API const vo
28d10 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
28d20 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36 28 73 71  mn_decltype16(sq
28d30 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
28d40 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
28d50 46 3a 20 45 76 61 6c 75 61 74 65 20 41 6e 20 53  F: Evaluate An S
28d60 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a  QL Statement.**.
28d70 2a 2a 20 41 66 74 65 72 20 61 20 5b 70 72 65 70  ** After a [prep
28d80 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
28d90 68 61 73 20 62 65 65 6e 20 70 72 65 70 61 72 65  has been prepare
28da0 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 0a 2a  d using either.*
28db0 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
28dc0 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c  re_v2()] or [sql
28dd0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
28de0 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74  2()] or one of t
28df0 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74  he legacy.** int
28e00 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33  erfaces [sqlite3
28e10 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 5b  _prepare()] or [
28e20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
28e30 36 28 29 5d 2c 20 74 68 69 73 20 66 75 6e 63 74  6()], this funct
28e40 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62 65 20 63  ion.** must be c
28e50 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72  alled one or mor
28e60 65 20 74 69 6d 65 73 20 74 6f 20 65 76 61 6c 75  e times to evalu
28e70 61 74 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e  ate the statemen
28e80 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74  t..**.** The det
28e90 61 69 6c 73 20 6f 66 20 74 68 65 20 62 65 68 61  ails of the beha
28ea0 76 69 6f 72 20 6f 66 20 74 68 65 20 73 71 6c 69  vior of the sqli
28eb0 74 65 33 5f 73 74 65 70 28 29 20 69 6e 74 65 72  te3_step() inter
28ec0 66 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20 6f  face depend.** o
28ed0 6e 20 77 68 65 74 68 65 72 20 74 68 65 20 73 74  n whether the st
28ee0 61 74 65 6d 65 6e 74 20 77 61 73 20 70 72 65 70  atement was prep
28ef0 61 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 6e  ared using the n
28f00 65 77 65 72 20 22 76 32 22 20 69 6e 74 65 72 66  ewer "v2" interf
28f10 61 63 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ace.** [sqlite3_
28f20 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e  prepare_v2()] an
28f30 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  d [sqlite3_prepa
28f40 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 74 68  re16_v2()] or th
28f50 65 20 6f 6c 64 65 72 20 6c 65 67 61 63 79 0a 2a  e older legacy.*
28f60 2a 20 69 6e 74 65 72 66 61 63 65 20 5b 73 71 6c  * interface [sql
28f70 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
28f80 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  and [sqlite3_pre
28f90 70 61 72 65 31 36 28 29 5d 2e 20 20 54 68 65 20  pare16()].  The 
28fa0 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20 6e 65  use of the.** ne
28fb0 77 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  w "v2" interface
28fc0 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
28fd0 66 6f 72 20 6e 65 77 20 61 70 70 6c 69 63 61 74  for new applicat
28fe0 69 6f 6e 73 20 62 75 74 20 74 68 65 20 6c 65 67  ions but the leg
28ff0 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  acy.** interface
29000 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 20 74   will continue t
29010 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e 0a  o be supported..
29020 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 6c 65  **.** ^In the le
29030 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20  gacy interface, 
29040 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
29050 20 77 69 6c 6c 20 62 65 20 65 69 74 68 65 72 20   will be either 
29060 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 0a 2a  [SQLITE_BUSY],.*
29070 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c  * [SQLITE_DONE],
29080 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b   [SQLITE_ROW], [
29090 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 6f  SQLITE_ERROR], o
290a0 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  r [SQLITE_MISUSE
290b0 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20  ]..** ^With the 
290c0 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c 20  "v2" interface, 
290d0 61 6e 79 20 6f 66 20 74 68 65 20 6f 74 68 65 72  any of the other
290e0 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20   [result codes] 
290f0 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  or.** [extended 
29100 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6d 69  result codes] mi
29110 67 68 74 20 62 65 20 72 65 74 75 72 6e 65 64 20  ght be returned 
29120 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e  as well..**.** ^
29130 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6d 65  [SQLITE_BUSY] me
29140 61 6e 73 20 74 68 61 74 20 74 68 65 20 64 61 74  ans that the dat
29150 61 62 61 73 65 20 65 6e 67 69 6e 65 20 77 61 73  abase engine was
29160 20 75 6e 61 62 6c 65 20 74 6f 20 61 63 71 75 69   unable to acqui
29170 72 65 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  re the.** databa
29180 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65 65 64  se locks it need
29190 73 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f 62 2e  s to do its job.
291a0 20 20 5e 49 66 20 74 68 65 20 73 74 61 74 65 6d    ^If the statem
291b0 65 6e 74 20 69 73 20 61 20 5b 43 4f 4d 4d 49 54  ent is a [COMMIT
291c0 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73 20 6f  ].** or occurs o
291d0 75 74 73 69 64 65 20 6f 66 20 61 6e 20 65 78 70  utside of an exp
291e0 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f  licit transactio
291f0 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63 61 6e 20  n, then you can 
29200 72 65 74 72 79 20 74 68 65 0a 2a 2a 20 73 74 61  retry the.** sta
29210 74 65 6d 65 6e 74 2e 20 20 49 66 20 74 68 65 20  tement.  If the 
29220 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74  statement is not
29230 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64 20   a [COMMIT] and 
29240 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 0a  occurs within a.
29250 2a 2a 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e  ** explicit tran
29260 73 61 63 74 69 6f 6e 20 74 68 65 6e 20 79 6f 75  saction then you
29270 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 61 63 6b   should rollback
29280 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e   the transaction
29290 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69   before.** conti
292a0 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53  nuing..**.** ^[S
292b0 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e  QLITE_DONE] mean
292c0 73 20 74 68 61 74 20 74 68 65 20 73 74 61 74 65  s that the state
292d0 6d 65 6e 74 20 68 61 73 20 66 69 6e 69 73 68 65  ment has finishe
292e0 64 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a 20 73  d executing.** s
292f0 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 73 71  uccessfully.  sq
29300 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f  lite3_step() sho
29310 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65  uld not be calle
29320 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 69 73 20  d again on this 
29330 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69  virtual.** machi
29340 6e 65 20 77 69 74 68 6f 75 74 20 66 69 72 73 74  ne without first
29350 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
29360 33 5f 72 65 73 65 74 28 29 5d 20 74 6f 20 72 65  3_reset()] to re
29370 73 65 74 20 74 68 65 20 76 69 72 74 75 61 6c 0a  set the virtual.
29380 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61 63 6b 20  ** machine back 
29390 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73  to its initial s
293a0 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  tate..**.** ^If 
293b0 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
293c0 74 20 62 65 69 6e 67 20 65 78 65 63 75 74 65 64  t being executed
293d0 20 72 65 74 75 72 6e 73 20 61 6e 79 20 64 61 74   returns any dat
293e0 61 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f  a, then [SQLITE_
293f0 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72  ROW].** is retur
29400 6e 65 64 20 65 61 63 68 20 74 69 6d 65 20 61 20  ned each time a 
29410 6e 65 77 20 72 6f 77 20 6f 66 20 64 61 74 61 20  new row of data 
29420 69 73 20 72 65 61 64 79 20 66 6f 72 20 70 72 6f  is ready for pro
29430 63 65 73 73 69 6e 67 20 62 79 20 74 68 65 0a 2a  cessing by the.*
29440 2a 20 63 61 6c 6c 65 72 2e 20 54 68 65 20 76 61  * caller. The va
29450 6c 75 65 73 20 6d 61 79 20 62 65 20 61 63 63 65  lues may be acce
29460 73 73 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b  ssed using the [
29470 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75  column access fu
29480 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c  nctions]..** sql
29490 69 74 65 33 5f 73 74 65 70 28 29 20 69 73 20 63  ite3_step() is c
294a0 61 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f 20 72  alled again to r
294b0 65 74 72 69 65 76 65 20 74 68 65 20 6e 65 78 74  etrieve the next
294c0 20 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a   row of data..**
294d0 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 45 52 52  .** ^[SQLITE_ERR
294e0 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 61  OR] means that a
294f0 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20   run-time error 
29500 28 73 75 63 68 20 61 73 20 61 20 63 6f 6e 73 74  (such as a const
29510 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 69  raint.** violati
29520 6f 6e 29 20 68 61 73 20 6f 63 63 75 72 72 65 64  on) has occurred
29530 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  .  sqlite3_step(
29540 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20  ) should not be 
29550 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 0a  called again on.
29560 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65 20  ** the VM. More 
29570 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 20  information may 
29580 62 65 20 66 6f 75 6e 64 20 62 79 20 63 61 6c 6c  be found by call
29590 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  ing [sqlite3_err
295a0 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e 57 69 74 68  msg()]..** ^With
295b0 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65   the legacy inte
295c0 72 66 61 63 65 2c 20 61 20 6d 6f 72 65 20 73 70  rface, a more sp
295d0 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64  ecific error cod
295e0 65 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c 0a  e (for example,.
295f0 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52  ** [SQLITE_INTER
29600 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 53  RUPT], [SQLITE_S
29610 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 5f  CHEMA], [SQLITE_
29620 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20 73 6f  CORRUPT], and so
29630 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e 20 62   forth).** can b
29640 65 20 6f 62 74 61 69 6e 65 64 20 62 79 20 63 61  e obtained by ca
29650 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  lling [sqlite3_r
29660 65 73 65 74 28 29 5d 20 6f 6e 20 74 68 65 0a 2a  eset()] on the.*
29670 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
29680 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e 20 74 68 65  ement].  ^In the
29690 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c   "v2" interface,
296a0 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 70 65  .** the more spe
296b0 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65  cific error code
296c0 20 69 73 20 72 65 74 75 72 6e 65 64 20 64 69 72   is returned dir
296d0 65 63 74 6c 79 20 62 79 20 73 71 6c 69 74 65 33  ectly by sqlite3
296e0 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b  _step()..**.** [
296f0 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d  SQLITE_MISUSE] m
29700 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 74 68  eans that the th
29710 69 73 20 72 6f 75 74 69 6e 65 20 77 61 73 20 63  is routine was c
29720 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70 72 69  alled inappropri
29730 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 70  ately..** Perhap
29740 73 20 69 74 20 77 61 73 20 63 61 6c 6c 65 64 20  s it was called 
29750 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  on a [prepared s
29760 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68  tatement] that h
29770 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62 65  as.** already be
29780 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  en [sqlite3_fina
29790 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64  lize | finalized
297a0 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61 74  ] or on one that
297b0 20 68 61 64 0a 2a 2a 20 70 72 65 76 69 6f 75 73   had.** previous
297c0 6c 79 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c  ly returned [SQL
297d0 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b 53  ITE_ERROR] or [S
297e0 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72  QLITE_DONE].  Or
297f0 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 20   it could.** be 
29800 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68  the case that th
29810 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
29820 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62 65  connection is be
29830 69 6e 67 20 75 73 65 64 20 62 79 20 74 77 6f 20  ing used by two 
29840 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65 61  or.** more threa
29850 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 6d  ds at the same m
29860 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a 2a  oment in time..*
29870 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20 76 65 72  *.** For all ver
29880 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20  sions of SQLite 
29890 75 70 20 74 6f 20 61 6e 64 20 69 6e 63 6c 75 64  up to and includ
298a0 69 6e 67 20 33 2e 36 2e 32 33 2e 31 2c 20 61 20  ing 3.6.23.1, a 
298b0 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  call to.** [sqli
298c0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77 61 73  te3_reset()] was
298d0 20 72 65 71 75 69 72 65 64 20 61 66 74 65 72 20   required after 
298e0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 72  sqlite3_step() r
298f0 65 74 75 72 6e 65 64 20 61 6e 79 74 68 69 6e 67  eturned anything
29900 0a 2a 2a 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  .** other than [
29910 53 51 4c 49 54 45 5f 52 4f 57 5d 20 62 65 66 6f  SQLITE_ROW] befo
29920 72 65 20 61 6e 79 20 73 75 62 73 65 71 75 65 6e  re any subsequen
29930 74 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 0a  t invocation of.
29940 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  ** sqlite3_step(
29950 29 2e 20 20 46 61 69 6c 75 72 65 20 74 6f 20 72  ).  Failure to r
29960 65 73 65 74 20 74 68 65 20 70 72 65 70 61 72 65  eset the prepare
29970 64 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e  d statement usin
29980 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  g .** [sqlite3_r
29990 65 73 65 74 28 29 5d 20 77 6f 75 6c 64 20 72 65  eset()] would re
299a0 73 75 6c 74 20 69 6e 20 61 6e 20 5b 53 51 4c 49  sult in an [SQLI
299b0 54 45 5f 4d 49 53 55 53 45 5d 20 72 65 74 75 72  TE_MISUSE] retur
299c0 6e 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65  n from.** sqlite
299d0 33 5f 73 74 65 70 28 29 2e 20 20 42 75 74 20 61  3_step().  But a
299e0 66 74 65 72 20 76 65 72 73 69 6f 6e 20 33 2e 36  fter version 3.6
299f0 2e 32 33 2e 31 2c 20 73 71 6c 69 74 65 33 5f 73  .23.1, sqlite3_s
29a00 74 65 70 28 29 20 62 65 67 61 6e 0a 2a 2a 20 63  tep() began.** c
29a10 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
29a20 72 65 73 65 74 28 29 5d 20 61 75 74 6f 6d 61 74  reset()] automat
29a30 69 63 61 6c 6c 79 20 69 6e 20 74 68 69 73 20 63  ically in this c
29a40 69 72 63 75 6d 73 74 61 6e 63 65 20 72 61 74 68  ircumstance rath
29a50 65 72 0a 2a 2a 20 74 68 61 6e 20 72 65 74 75 72  er.** than retur
29a60 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 4d 49 53  ning [SQLITE_MIS
29a70 55 53 45 5d 2e 20 20 54 68 69 73 20 69 73 20 6e  USE].  This is n
29a80 6f 74 20 63 6f 6e 73 69 64 65 72 65 64 20 61 20  ot considered a 
29a90 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 0a 2a 2a  compatibility.**
29aa0 20 62 72 65 61 6b 20 62 65 63 61 75 73 65 20 61   break because a
29ab0 6e 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74  ny application t
29ac0 68 61 74 20 65 76 65 72 20 72 65 63 65 69 76 65  hat ever receive
29ad0 73 20 61 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55  s an SQLITE_MISU
29ae0 53 45 20 65 72 72 6f 72 0a 2a 2a 20 69 73 20 62  SE error.** is b
29af0 72 6f 6b 65 6e 20 62 79 20 64 65 66 69 6e 69 74  roken by definit
29b00 69 6f 6e 2e 20 20 54 68 65 20 5b 53 51 4c 49 54  ion.  The [SQLIT
29b10 45 5f 4f 4d 49 54 5f 41 55 54 4f 52 45 53 45 54  E_OMIT_AUTORESET
29b20 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
29b30 70 74 69 6f 6e 0a 2a 2a 20 63 61 6e 20 62 65 20  ption.** can be 
29b40 75 73 65 64 20 74 6f 20 72 65 73 74 6f 72 65 20  used to restore 
29b50 74 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76  the legacy behav
29b60 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f  ior..**.** <b>Go
29b70 6f 66 79 20 49 6e 74 65 72 66 61 63 65 20 41 6c  ofy Interface Al
29b80 65 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 68 65 20  ert:</b> In the 
29b90 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65  legacy interface
29ba0 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74  , the sqlite3_st
29bb0 65 70 28 29 0a 2a 2a 20 41 50 49 20 61 6c 77 61  ep().** API alwa
29bc0 79 73 20 72 65 74 75 72 6e 73 20 61 20 67 65 6e  ys returns a gen
29bd0 65 72 69 63 20 65 72 72 6f 72 20 63 6f 64 65 2c  eric error code,
29be0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c   [SQLITE_ERROR],
29bf0 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a   following any.*
29c00 2a 20 65 72 72 6f 72 20 6f 74 68 65 72 20 74 68  * error other th
29c10 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  an [SQLITE_BUSY]
29c20 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49 53   and [SQLITE_MIS
29c30 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74 20  USE].  You must 
29c40 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  call.** [sqlite3
29c50 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71  _reset()] or [sq
29c60 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
29c70 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69  ] in order to fi
29c80 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a  nd one of the.**
29c90 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72   specific [error
29ca0 20 63 6f 64 65 73 5d 20 74 68 61 74 20 62 65 74   codes] that bet
29cb0 74 65 72 20 64 65 73 63 72 69 62 65 73 20 74 68  ter describes th
29cc0 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 61  e error..** We a
29cd0 64 6d 69 74 20 74 68 61 74 20 74 68 69 73 20 69  dmit that this i
29ce0 73 20 61 20 67 6f 6f 66 79 20 64 65 73 69 67 6e  s a goofy design
29cf0 2e 20 20 54 68 65 20 70 72 6f 62 6c 65 6d 20 68  .  The problem h
29d00 61 73 20 62 65 65 6e 20 66 69 78 65 64 0a 2a 2a  as been fixed.**
29d10 20 77 69 74 68 20 74 68 65 20 22 76 32 22 20 69   with the "v2" i
29d20 6e 74 65 72 66 61 63 65 2e 20 20 49 66 20 79 6f  nterface.  If yo
29d30 75 20 70 72 65 70 61 72 65 20 61 6c 6c 20 6f 66  u prepare all of
29d40 20 79 6f 75 72 20 53 51 4c 20 73 74 61 74 65 6d   your SQL statem
29d50 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20 65 69  ents.** using ei
29d60 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ther [sqlite3_pr
29d70 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b  epare_v2()] or [
29d80 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
29d90 36 5f 76 32 28 29 5d 20 69 6e 73 74 65 61 64 0a  6_v2()] instead.
29da0 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79  ** of the legacy
29db0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
29dc0 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
29dd0 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 69  3_prepare16()] i
29de0 6e 74 65 72 66 61 63 65 73 2c 0a 2a 2a 20 74 68  nterfaces,.** th
29df0 65 6e 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63  en the more spec
29e00 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65  ific [error code
29e10 73 5d 20 61 72 65 20 72 65 74 75 72 6e 65 64 20  s] are returned 
29e20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20 73  directly.** by s
29e30 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20  qlite3_step().  
29e40 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 22  The use of the "
29e50 76 32 22 20 69 6e 74 65 72 66 61 63 65 20 69 73  v2" interface is
29e60 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2f   recommended..*/
29e70 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
29e80 73 71 6c 69 74 65 33 5f 73 74 65 70 28 73 71 6c  sqlite3_step(sql
29e90 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a  ite3_stmt*);../*
29ea0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75  .** CAPI3REF: Nu
29eb0 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
29ec0 69 6e 20 61 20 72 65 73 75 6c 74 20 73 65 74 0a  in a result set.
29ed0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
29ee0 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29  e3_data_count(P)
29ef0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
29f00 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
29f10 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 0a   columns in the.
29f20 2a 2a 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f  ** current row o
29f30 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
29f40 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73 74   of [prepared st
29f50 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e  atement] P..** ^
29f60 49 66 20 70 72 65 70 61 72 65 64 20 73 74 61 74  If prepared stat
29f70 65 6d 65 6e 74 20 50 20 64 6f 65 73 20 6e 6f 74  ement P does not
29f80 20 68 61 76 65 20 72 65 73 75 6c 74 73 20 72 65   have results re
29f90 61 64 79 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a  ady to return.**
29fa0 20 28 76 69 61 20 63 61 6c 6c 73 20 74 6f 20 74   (via calls to t
29fb0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  he [sqlite3_colu
29fc0 6d 6e 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33  mn_int | sqlite3
29fd0 5f 63 6f 6c 75 6d 6e 5f 2a 28 29 5d 20 6f 66 0a  _column_*()] of.
29fe0 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 29 20 74  ** interfaces) t
29ff0 68 65 6e 20 73 71 6c 69 74 65 33 5f 64 61 74 61  hen sqlite3_data
2a000 5f 63 6f 75 6e 74 28 50 29 20 72 65 74 75 72 6e  _count(P) return
2a010 73 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s 0..** ^The sql
2a020 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
2a030 50 29 20 72 6f 75 74 69 6e 65 20 61 6c 73 6f 20  P) routine also 
2a040 72 65 74 75 72 6e 73 20 30 20 69 66 20 50 20 69  returns 0 if P i
2a050 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
2a060 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
2a070 3a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  : [sqlite3_colum
2a080 6e 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 53 51  n_count()].*/.SQ
2a090 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
2a0a0 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
2a0b0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
2a0c0 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
2a0d0 49 33 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74  I3REF: Fundament
2a0e0 61 6c 20 44 61 74 61 74 79 70 65 73 0a 2a 2a 20  al Datatypes.** 
2a0f0 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45  KEYWORDS: SQLITE
2a100 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 76  _TEXT.**.** ^(Ev
2a110 65 72 79 20 76 61 6c 75 65 20 69 6e 20 53 51 4c  ery value in SQL
2a120 69 74 65 20 68 61 73 20 6f 6e 65 20 6f 66 20 66  ite has one of f
2a130 69 76 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c 20  ive fundamental 
2a140 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a  datatypes:.**.**
2a150 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34   <ul>.** <li> 64
2a160 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
2a170 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62  ger.** <li> 64-b
2a180 69 74 20 49 45 45 45 20 66 6c 6f 61 74 69 6e 67  it IEEE floating
2a190 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a   point number.**
2a1a0 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a 20   <li> string.** 
2a1b0 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69  <li> BLOB.** <li
2a1c0 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29  > NULL.** </ul>)
2a1d0 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  ^.**.** These co
2a1e0 6e 73 74 61 6e 74 73 20 61 72 65 20 63 6f 64 65  nstants are code
2a1f0 73 20 66 6f 72 20 65 61 63 68 20 6f 66 20 74 68  s for each of th
2a200 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a  ose types..**.**
2a210 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 53   Note that the S
2a220 51 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e 73 74  QLITE_TEXT const
2a230 61 6e 74 20 77 61 73 20 61 6c 73 6f 20 75 73 65  ant was also use
2a240 64 20 69 6e 20 53 51 4c 69 74 65 20 76 65 72 73  d in SQLite vers
2a250 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63  ion 2.** for a c
2a260 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66 66 65 72  ompletely differ
2a270 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f  ent meaning.  So
2a280 66 74 77 61 72 65 20 74 68 61 74 20 6c 69 6e 6b  ftware that link
2a290 73 20 61 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a  s against both.*
2a2a0 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  * SQLite version
2a2b0 20 32 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65   2 and SQLite ve
2a2c0 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75  rsion 3 should u
2a2d0 73 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 2c  se SQLITE3_TEXT,
2a2e0 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54   not.** SQLITE_T
2a2f0 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  EXT..*/.#define 
2a300 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 20  SQLITE_INTEGER  
2a310 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
2a320 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23 64 65 66  _FLOAT    2.#def
2a330 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20  ine SQLITE_BLOB 
2a340 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51      4.#define SQ
2a350 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a  LITE_NULL     5.
2a360 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 54 45  #ifdef SQLITE_TE
2a370 58 54 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54  XT.# undef SQLIT
2a380 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23 20 64  E_TEXT.#else.# d
2a390 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 58  efine SQLITE_TEX
2a3a0 54 20 20 20 20 20 33 0a 23 65 6e 64 69 66 0a 23  T     3.#endif.#
2a3b0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 54  define SQLITE3_T
2a3c0 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a  EXT     3../*.**
2a3d0 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c   CAPI3REF: Resul
2a3e0 74 20 56 61 6c 75 65 73 20 46 72 6f 6d 20 41 20  t Values From A 
2a3f0 51 75 65 72 79 0a 2a 2a 20 4b 45 59 57 4f 52 44  Query.** KEYWORD
2a400 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63 63 65 73  S: {column acces
2a410 73 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a  s functions}.**.
2a420 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
2a430 73 20 66 6f 72 6d 20 74 68 65 20 22 72 65 73 75  s form the "resu
2a440 6c 74 20 73 65 74 22 20 69 6e 74 65 72 66 61 63  lt set" interfac
2a450 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  e..**.** ^These 
2a460 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
2a470 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75  information abou
2a480 74 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d  t a single colum
2a490 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74  n of the current
2a4a0 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 6f  .** result row o
2a4b0 66 20 61 20 71 75 65 72 79 2e 20 20 5e 49 6e 20  f a query.  ^In 
2a4c0 65 76 65 72 79 20 63 61 73 65 20 74 68 65 20 66  every case the f
2a4d0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73  irst argument is
2a4e0 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f   a pointer.** to
2a4f0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
2a500 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69  tatement] that i
2a510 73 20 62 65 69 6e 67 20 65 76 61 6c 75 61 74 65  s being evaluate
2a520 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  d (the [sqlite3_
2a530 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74 20 77  stmt*].** that w
2a540 61 73 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d  as returned from
2a550 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2a560 65 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f  e_v2()] or one o
2a570 66 20 69 74 73 20 76 61 72 69 61 6e 74 73 29 0a  f its variants).
2a580 2a 2a 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e  ** and the secon
2a590 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
2a5a0 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63  e index of the c
2a5b0 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69 63 68 20  olumn for which 
2a5c0 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73  information.** s
2a5d0 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65  hould be returne
2a5e0 64 2e 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74  d. ^The leftmost
2a5f0 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72   column of the r
2a600 65 73 75 6c 74 20 73 65 74 20 68 61 73 20 74 68  esult set has th
2a610 65 20 69 6e 64 65 78 20 30 2e 0a 2a 2a 20 5e 54  e index 0..** ^T
2a620 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  he number of col
2a630 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75  umns in the resu
2a640 6c 74 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d  lt can be determ
2a650 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  ined using.** [s
2a660 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f  qlite3_column_co
2a670 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66  unt()]..**.** If
2a680 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
2a690 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 75 72 72  nt does not curr
2a6a0 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61  ently point to a
2a6b0 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69   valid row, or i
2a6c0 66 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20  f the.** column 
2a6d0 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20  index is out of 
2a6e0 72 61 6e 67 65 2c 20 74 68 65 20 72 65 73 75 6c  range, the resul
2a6f0 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  t is undefined..
2a700 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
2a710 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63 61  s may only be ca
2a720 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20 6d 6f  lled when the mo
2a730 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74  st recent call t
2a740 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74  o.** [sqlite3_st
2a750 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e  ep()] has return
2a760 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20  ed [SQLITE_ROW] 
2a770 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b  and neither.** [
2a780 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2a790 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69   nor [sqlite3_fi
2a7a0 6e 61 6c 69 7a 65 28 29 5d 20 68 61 76 65 20 62  nalize()] have b
2a7b0 65 65 6e 20 63 61 6c 6c 65 64 20 73 75 62 73 65  een called subse
2a7c0 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61  quently..** If a
2a7d0 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  ny of these rout
2a7e0 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20  ines are called 
2a7f0 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 72  after [sqlite3_r
2a800 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73  eset()] or.** [s
2a810 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2a820 29 5d 20 6f 72 20 61 66 74 65 72 20 5b 73 71 6c  )] or after [sql
2a830 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73  ite3_step()] has
2a840 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d   returned.** som
2a850 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61  ething other tha
2a860 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20  n [SQLITE_ROW], 
2a870 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
2a880 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66  undefined..** If
2a890 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2a8a0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
2a8b0 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  set()] or [sqlit
2a8c0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a  e3_finalize()].*
2a8d0 2a 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f  * are called fro
2a8e0 6d 20 61 20 64 69 66 66 65 72 65 6e 74 20 74 68  m a different th
2a8f0 72 65 61 64 20 77 68 69 6c 65 20 61 6e 79 20 6f  read while any o
2a900 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
2a910 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e 67 2c  .** are pending,
2a920 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74   then the result
2a930 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
2a940 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2a950 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
2a960 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
2a970 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  s the.** [SQLITE
2a980 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74  _INTEGER | datat
2a990 79 70 65 20 63 6f 64 65 5d 20 66 6f 72 20 74 68  ype code] for th
2a9a0 65 20 69 6e 69 74 69 61 6c 20 64 61 74 61 20 74  e initial data t
2a9b0 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65  ype.** of the re
2a9c0 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 5e 54  sult column.  ^T
2a9d0 68 65 20 72 65 74 75 72 6e 65 64 20 76 61 6c 75  he returned valu
2a9e0 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c  e is one of [SQL
2a9f0 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a  ITE_INTEGER],.**
2aa00 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c   [SQLITE_FLOAT],
2aa10 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20   [SQLITE_TEXT], 
2aa20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f  [SQLITE_BLOB], o
2aa30 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e  r [SQLITE_NULL].
2aa40 20 20 54 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72    The value.** r
2aa50 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
2aa60 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29  e3_column_type()
2aa70 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67   is only meaning
2aa80 66 75 6c 20 69 66 20 6e 6f 20 74 79 70 65 0a 2a  ful if no type.*
2aa90 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68 61  * conversions ha
2aaa0 76 65 20 6f 63 63 75 72 72 65 64 20 61 73 20 64  ve occurred as d
2aab0 65 73 63 72 69 62 65 64 20 62 65 6c 6f 77 2e 20  escribed below. 
2aac0 20 41 66 74 65 72 20 61 20 74 79 70 65 20 63 6f   After a type co
2aad0 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65  nversion,.** the
2aae0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
2aaf0 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
2ab00 6e 5f 74 79 70 65 28 29 20 69 73 20 75 6e 64 65  n_type() is unde
2ab10 66 69 6e 65 64 2e 20 20 46 75 74 75 72 65 0a 2a  fined.  Future.*
2ab20 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  * versions of SQ
2ab30 4c 69 74 65 20 6d 61 79 20 63 68 61 6e 67 65 20  Lite may change 
2ab40 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20  the behavior of 
2ab50 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2ab60 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69  ype().** followi
2ab70 6e 67 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72  ng a type conver
2ab80 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  sion..**.** ^If 
2ab90 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
2aba0 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20 73 74  BLOB or UTF-8 st
2abb0 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71  ring then the sq
2abc0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2abd0 65 73 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  es().** routine 
2abe0 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
2abf0 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
2ac00 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69  hat BLOB or stri
2ac10 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  ng..** ^If the r
2ac20 65 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d 31  esult is a UTF-1
2ac30 36 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73  6 string, then s
2ac40 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2ac50 74 65 73 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a  tes() converts.*
2ac60 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20  * the string to 
2ac70 55 54 46 2d 38 20 61 6e 64 20 74 68 65 6e 20 72  UTF-8 and then r
2ac80 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
2ac90 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e  r of bytes..** ^
2aca0 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
2acb0 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65   a numeric value
2acc0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
2acd0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 75 73 65  lumn_bytes() use
2ace0 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e  s.** [sqlite3_sn
2acf0 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e  printf()] to con
2ad00 76 65 72 74 20 74 68 61 74 20 76 61 6c 75 65 20  vert that value 
2ad10 74 6f 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e  to a UTF-8 strin
2ad20 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a  g and returns.**
2ad30 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
2ad40 79 74 65 73 20 69 6e 20 74 68 61 74 20 73 74 72  ytes in that str
2ad50 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ing..** ^If the 
2ad60 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20  result is NULL, 
2ad70 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
2ad80 75 6d 6e 5f 62 79 74 65 73 28 29 20 72 65 74 75  umn_bytes() retu
2ad90 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20  rns zero..**.** 
2ada0 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
2adb0 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d  s a BLOB or UTF-
2adc0 31 36 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74  16 string then t
2add0 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  he sqlite3_colum
2ade0 6e 5f 62 79 74 65 73 31 36 28 29 0a 2a 2a 20 72  n_bytes16().** r
2adf0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
2ae00 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
2ae10 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20  es in that BLOB 
2ae20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49  or string..** ^I
2ae30 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
2ae40 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2c 20  a UTF-8 string, 
2ae50 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
2ae60 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 63 6f  umn_bytes16() co
2ae70 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74  nverts.** the st
2ae80 72 69 6e 67 20 74 6f 20 55 54 46 2d 31 36 20 61  ring to UTF-16 a
2ae90 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20  nd then returns 
2aea0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
2aeb0 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  tes..** ^If the 
2aec0 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65  result is a nume
2aed0 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73  ric value then s
2aee0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2aef0 74 65 73 31 36 28 29 20 75 73 65 73 0a 2a 2a 20  tes16() uses.** 
2af00 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  [sqlite3_snprint
2af10 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20  f()] to convert 
2af20 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20  that value to a 
2af30 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 61 6e  UTF-16 string an
2af40 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65  d returns.** the
2af50 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
2af60 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e   in that string.
2af70 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
2af80 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  lt is NULL, then
2af90 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2afa0 62 79 74 65 73 31 36 28 29 20 72 65 74 75 72 6e  bytes16() return
2afb0 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54  s zero..**.** ^T
2afc0 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e  he values return
2afd0 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63  ed by [sqlite3_c
2afe0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61  olumn_bytes()] a
2aff0 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  nd .** [sqlite3_
2b000 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
2b010 5d 20 64 6f 20 6e 6f 74 20 69 6e 63 6c 75 64 65  ] do not include
2b020 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e   the zero termin
2b030 61 74 6f 72 73 20 61 74 20 74 68 65 20 65 6e 64  ators at the end
2b040 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74 72 69 6e  .** of the strin
2b050 67 2e 20 20 5e 46 6f 72 20 63 6c 61 72 69 74 79  g.  ^For clarity
2b060 3a 20 74 68 65 20 76 61 6c 75 65 73 20 72 65 74  : the values ret
2b070 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c  urned by.** [sql
2b080 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2b090 73 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  s()] and [sqlite
2b0a0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
2b0b0 28 29 5d 20 61 72 65 20 74 68 65 20 6e 75 6d 62  ()] are the numb
2b0c0 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69  er of.** bytes i
2b0d0 6e 20 74 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f  n the string, no
2b0e0 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  t the number of 
2b0f0 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a  characters..**.*
2b100 2a 20 5e 53 74 72 69 6e 67 73 20 72 65 74 75 72  * ^Strings retur
2b110 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  ned by sqlite3_c
2b120 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64  olumn_text() and
2b130 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2b140 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65  text16(),.** eve
2b150 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 73 2c  n empty strings,
2b160 20 61 72 65 20 61 6c 77 61 79 73 20 7a 65 72 6f   are always zero
2b170 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54   terminated.  ^T
2b180 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c  he return.** val
2b190 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ue from sqlite3_
2b1a0 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f  column_blob() fo
2b1b0 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20  r a zero-length 
2b1c0 42 4c 4f 42 20 69 73 20 61 20 4e 55 4c 4c 20 70  BLOB is a NULL p
2b1d0 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ointer..**.** ^T
2b1e0 68 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  he object return
2b1f0 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63  ed by [sqlite3_c
2b200 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69  olumn_value()] i
2b210 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65  s an.** [unprote
2b220 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2b230 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20 41 6e 20  ue] object.  An 
2b240 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
2b250 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
2b260 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20  .** may only be 
2b270 75 73 65 64 20 77 69 74 68 20 5b 73 71 6c 69 74  used with [sqlit
2b280 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d  e3_bind_value()]
2b290 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65   and [sqlite3_re
2b2a0 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a  sult_value()]..*
2b2b0 2a 20 49 66 20 74 68 65 20 5b 75 6e 70 72 6f 74  * If the [unprot
2b2c0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2b2d0 6c 75 65 5d 20 6f 62 6a 65 63 74 20 72 65 74 75  lue] object retu
2b2e0 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69  rned by.** [sqli
2b2f0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65  te3_column_value
2b300 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e 20 61  ()] is used in a
2b310 6e 79 20 6f 74 68 65 72 20 77 61 79 2c 20 69 6e  ny other way, in
2b320 63 6c 75 64 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a  cluding calls.**
2b330 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b   to routines lik
2b340 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
2b350 5f 69 6e 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65  _int()], [sqlite
2b360 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c  3_value_text()],
2b370 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
2b380 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20  value_bytes()], 
2b390 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
2b3a0 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  r is undefined..
2b3b0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
2b3c0 69 6e 65 73 20 61 74 74 65 6d 70 74 20 74 6f 20  ines attempt to 
2b3d0 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75  convert the valu
2b3e0 65 20 77 68 65 72 65 20 61 70 70 72 6f 70 72 69  e where appropri
2b3f0 61 74 65 2e 20 20 5e 46 6f 72 0a 2a 2a 20 65 78  ate.  ^For.** ex
2b400 61 6d 70 6c 65 2c 20 69 66 20 74 68 65 20 69 6e  ample, if the in
2b410 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74  ternal represent
2b420 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41 54 20 61  ation is FLOAT a
2b430 6e 64 20 61 20 74 65 78 74 20 72 65 73 75 6c 74  nd a text result
2b440 0a 2a 2a 20 69 73 20 72 65 71 75 65 73 74 65 64  .** is requested
2b450 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  , [sqlite3_snpri
2b460 6e 74 66 28 29 5d 20 69 73 20 75 73 65 64 20 69  ntf()] is used i
2b470 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 70 65 72  nternally to per
2b480 66 6f 72 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e 76  form the.** conv
2b490 65 72 73 69 6f 6e 20 61 75 74 6f 6d 61 74 69 63  ersion automatic
2b4a0 61 6c 6c 79 2e 20 20 5e 28 54 68 65 20 66 6f 6c  ally.  ^(The fol
2b4b0 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20 64 65 74  lowing table det
2b4c0 61 69 6c 73 20 74 68 65 20 63 6f 6e 76 65 72 73  ails the convers
2b4d0 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 61 72 65  ions.** that are
2b4e0 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20   applied:.**.** 
2b4f0 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20  <blockquote>.** 
2b500 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31  <table border="1
2b510 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49  ">.** <tr><th> I
2b520 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65 20  nternal<br>Type 
2b530 3c 74 68 3e 20 52 65 71 75 65 73 74 65 64 3c 62  <th> Requested<b
2b540 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 43 6f 6e  r>Type <th>  Con
2b550 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74  version.**.** <t
2b560 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20  r><td>  NULL    
2b570 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c  <td> INTEGER   <
2b580 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 0a  td> Result is 0.
2b590 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c  ** <tr><td>  NUL
2b5a0 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54  L    <td>  FLOAT
2b5b0 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20      <td> Result 
2b5c0 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74  is 0.0.** <tr><t
2b5d0 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e  d>  NULL    <td>
2b5e0 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20     TEXT    <td> 
2b5f0 52 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70  Result is NULL p
2b600 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74  ointer.** <tr><t
2b610 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e  d>  NULL    <td>
2b620 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
2b630 52 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70  Result is NULL p
2b640 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74  ointer.** <tr><t
2b650 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e  d> INTEGER  <td>
2b660 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20    FLOAT    <td> 
2b670 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e 74  Convert from int
2b680 65 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a  eger to float.**
2b690 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45   <tr><td> INTEGE
2b6a0 52 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20  R  <td>   TEXT  
2b6b0 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e    <td> ASCII ren
2b6c0 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 69 6e  dering of the in
2b6d0 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64  teger.** <tr><td
2b6e0 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20  > INTEGER  <td> 
2b6f0 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53    BLOB    <td> S
2b700 61 6d 65 20 61 73 20 49 4e 54 45 47 45 52 2d 3e  ame as INTEGER->
2b710 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  TEXT.** <tr><td>
2b720 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49    FLOAT   <td> I
2b730 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 43 6f  NTEGER   <td> Co
2b740 6e 76 65 72 74 20 66 72 6f 6d 20 66 6c 6f 61 74  nvert from float
2b750 20 74 6f 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c   to integer.** <
2b760 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20  tr><td>  FLOAT  
2b770 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
2b780 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65  <td> ASCII rende
2b790 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f 61  ring of the floa
2b7a0 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46  t.** <tr><td>  F
2b7b0 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 42 4c  LOAT   <td>   BL
2b7c0 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20  OB    <td> Same 
2b7d0 61 73 20 46 4c 4f 41 54 2d 3e 54 45 58 54 0a 2a  as FLOAT->TEXT.*
2b7e0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54  * <tr><td>  TEXT
2b7f0 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52      <td> INTEGER
2b800 20 20 20 3c 74 64 3e 20 55 73 65 20 61 74 6f 69     <td> Use atoi
2b810 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ().** <tr><td>  
2b820 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 46 4c  TEXT    <td>  FL
2b830 4f 41 54 20 20 20 20 3c 74 64 3e 20 55 73 65 20  OAT    <td> Use 
2b840 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74  atof().** <tr><t
2b850 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  d>  TEXT    <td>
2b860 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
2b870 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74 72  No change.** <tr
2b880 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c  ><td>  BLOB    <
2b890 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74  td> INTEGER   <t
2b8a0 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45  d> Convert to TE
2b8b0 58 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f 69  XT then use atoi
2b8c0 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ().** <tr><td>  
2b8d0 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 46 4c  BLOB    <td>  FL
2b8e0 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76  OAT    <td> Conv
2b8f0 65 72 74 20 74 6f 20 54 45 58 54 20 74 68 65 6e  ert to TEXT then
2b900 20 75 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c   use atof().** <
2b910 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20  tr><td>  BLOB   
2b920 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
2b930 3c 74 64 3e 20 41 64 64 20 61 20 7a 65 72 6f 20  <td> Add a zero 
2b940 74 65 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e 65  terminator if ne
2b950 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e  eded.** </table>
2b960 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  .** </blockquote
2b970 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61  >)^.**.** The ta
2b980 62 6c 65 20 61 62 6f 76 65 20 6d 61 6b 65 73 20  ble above makes 
2b990 72 65 66 65 72 65 6e 63 65 20 74 6f 20 73 74 61  reference to sta
2b9a0 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 20  ndard C library 
2b9b0 66 75 6e 63 74 69 6f 6e 73 20 61 74 6f 69 28 29  functions atoi()
2b9c0 0a 2a 2a 20 61 6e 64 20 61 74 6f 66 28 29 2e 20  .** and atof(). 
2b9d0 20 53 51 4c 69 74 65 20 64 6f 65 73 20 6e 6f 74   SQLite does not
2b9e0 20 72 65 61 6c 6c 79 20 75 73 65 20 74 68 65 73   really use thes
2b9f0 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 49 74  e functions.  It
2ba00 20 68 61 73 20 69 74 73 0a 2a 2a 20 6f 77 6e 20   has its.** own 
2ba10 65 71 75 69 76 61 6c 65 6e 74 20 69 6e 74 65 72  equivalent inter
2ba20 6e 61 6c 20 72 6f 75 74 69 6e 65 73 2e 20 20 54  nal routines.  T
2ba30 68 65 20 61 74 6f 69 28 29 20 61 6e 64 20 61 74  he atoi() and at
2ba40 6f 66 28 29 20 6e 61 6d 65 73 20 61 72 65 0a 2a  of() names are.*
2ba50 2a 20 75 73 65 64 20 69 6e 20 74 68 65 20 74 61  * used in the ta
2ba60 62 6c 65 20 66 6f 72 20 62 72 65 76 69 74 79 20  ble for brevity 
2ba70 61 6e 64 20 62 65 63 61 75 73 65 20 74 68 65 79  and because they
2ba80 20 61 72 65 20 66 61 6d 69 6c 69 61 72 20 74 6f   are familiar to
2ba90 20 6d 6f 73 74 0a 2a 2a 20 43 20 70 72 6f 67 72   most.** C progr
2baa0 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f  ammers..**.** No
2bab0 74 65 20 74 68 61 74 20 77 68 65 6e 20 74 79 70  te that when typ
2bac0 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f 63  e conversions oc
2bad0 63 75 72 2c 20 70 6f 69 6e 74 65 72 73 20 72 65  cur, pointers re
2bae0 74 75 72 6e 65 64 20 62 79 20 70 72 69 6f 72 0a  turned by prior.
2baf0 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  ** calls to sqli
2bb00 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
2bb10 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ), sqlite3_colum
2bb20 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f 6f 72  n_text(), and/or
2bb30 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
2bb40 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d 61 79 20  mn_text16() may 
2bb50 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a  be invalidated..
2bb60 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65 72 73 69  ** Type conversi
2bb70 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74 65 72 20  ons and pointer 
2bb80 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d 69  invalidations mi
2bb90 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20  ght occur.** in 
2bba0 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61  the following ca
2bbb0 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ses:.**.** <ul>.
2bbc0 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74  ** <li> The init
2bbd0 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 61  ial content is a
2bbe0 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c 69 74 65   BLOB and sqlite
2bbf0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
2bc00 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74  or.**      sqlit
2bc10 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
2bc20 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 41  () is called.  A
2bc30 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72   zero-terminator
2bc40 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20 20 20 6e   might.**      n
2bc50 65 65 64 20 74 6f 20 62 65 20 61 64 64 65 64 20  eed to be added 
2bc60 74 6f 20 74 68 65 20 73 74 72 69 6e 67 2e 3c 2f  to the string.</
2bc70 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  li>.** <li> The 
2bc80 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20  initial content 
2bc90 69 73 20 55 54 46 2d 38 20 74 65 78 74 20 61 6e  is UTF-8 text an
2bca0 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
2bcb0 5f 62 79 74 65 73 31 36 28 29 20 6f 72 0a 2a 2a  _bytes16() or.**
2bcc0 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f        sqlite3_co
2bcd0 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73  lumn_text16() is
2bce0 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f   called.  The co
2bcf0 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f  ntent must be co
2bd00 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20  nverted.**      
2bd10 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a  to UTF-16.</li>.
2bd20 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74  ** <li> The init
2bd30 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55  ial content is U
2bd40 54 46 2d 31 36 20 74 65 78 74 20 61 6e 64 20 73  TF-16 text and s
2bd50 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2bd60 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20  tes() or.**     
2bd70 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2bd80 74 65 78 74 28 29 20 69 73 20 63 61 6c 6c 65 64  text() is called
2bd90 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d  .  The content m
2bda0 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64  ust be converted
2bdb0 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d  .**      to UTF-
2bdc0 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e  8.</li>.** </ul>
2bdd0 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76 65 72 73 69  .**.** ^Conversi
2bde0 6f 6e 73 20 62 65 74 77 65 65 6e 20 55 54 46 2d  ons between UTF-
2bdf0 31 36 62 65 20 61 6e 64 20 55 54 46 2d 31 36 6c  16be and UTF-16l
2be00 65 20 61 72 65 20 61 6c 77 61 79 73 20 64 6f 6e  e are always don
2be10 65 20 69 6e 20 70 6c 61 63 65 20 61 6e 64 20 64  e in place and d
2be20 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64  o.** not invalid
2be30 61 74 65 20 61 20 70 72 69 6f 72 20 70 6f 69 6e  ate a prior poin
2be40 74 65 72 2c 20 74 68 6f 75 67 68 20 6f 66 20 63  ter, though of c
2be50 6f 75 72 73 65 20 74 68 65 20 63 6f 6e 74 65 6e  ourse the conten
2be60 74 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 0a  t of the buffer.
2be70 2a 2a 20 74 68 61 74 20 74 68 65 20 70 72 69 6f  ** that the prio
2be80 72 20 70 6f 69 6e 74 65 72 20 72 65 66 65 72 65  r pointer refere
2be90 6e 63 65 73 20 77 69 6c 6c 20 68 61 76 65 20 62  nces will have b
2bea0 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e 20 20 4f  een modified.  O
2beb0 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66  ther kinds.** of
2bec0 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 72 65 20   conversion are 
2bed0 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 77 68  done in place wh
2bee0 65 6e 20 69 74 20 69 73 20 70 6f 73 73 69 62 6c  en it is possibl
2bef0 65 2c 20 62 75 74 20 73 6f 6d 65 74 69 6d 65 73  e, but sometimes
2bf00 20 74 68 65 79 0a 2a 2a 20 61 72 65 20 6e 6f 74   they.** are not
2bf10 20 70 6f 73 73 69 62 6c 65 20 61 6e 64 20 69 6e   possible and in
2bf20 20 74 68 6f 73 65 20 63 61 73 65 73 20 70 72 69   those cases pri
2bf30 6f 72 20 70 6f 69 6e 74 65 72 73 20 61 72 65 20  or pointers are 
2bf40 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a  invalidated..**.
2bf50 2a 2a 20 54 68 65 20 73 61 66 65 73 74 20 61 6e  ** The safest an
2bf60 64 20 65 61 73 69 65 73 74 20 74 6f 20 72 65 6d  d easiest to rem
2bf70 65 6d 62 65 72 20 70 6f 6c 69 63 79 20 69 73 20  ember policy is 
2bf80 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73 65 20  to invoke these 
2bf90 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f  routines.** in o
2bfa0 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77  ne of the follow
2bfb0 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20  ing ways:.**.** 
2bfc0 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c  <ul>.**  <li>sql
2bfd0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2bfe0 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73  () followed by s
2bff0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2c000 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c  tes()</li>.**  <
2c010 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  li>sqlite3_colum
2c020 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65  n_blob() followe
2c030 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
2c040 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e  umn_bytes()</li>
2c050 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33  .**  <li>sqlite3
2c060 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
2c070 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c   followed by sql
2c080 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2c090 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f  s16()</li>.** </
2c0a0 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68  ul>.**.** In oth
2c0b0 65 72 20 77 6f 72 64 73 2c 20 79 6f 75 20 73 68  er words, you sh
2c0c0 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74 65  ould call sqlite
2c0d0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c  3_column_text(),
2c0e0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
2c0f0 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73 71  mn_blob(), or sq
2c100 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2c110 74 31 36 28 29 20 66 69 72 73 74 20 74 6f 20 66  t16() first to f
2c120 6f 72 63 65 20 74 68 65 20 72 65 73 75 6c 74 0a  orce the result.
2c130 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64 65 73 69  ** into the desi
2c140 72 65 64 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e  red format, then
2c150 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f   invoke sqlite3_
2c160 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f  column_bytes() o
2c170 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  r.** sqlite3_col
2c180 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 74 6f  umn_bytes16() to
2c190 20 66 69 6e 64 20 74 68 65 20 73 69 7a 65 20 6f   find the size o
2c1a0 66 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20 44  f the result.  D
2c1b0 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 0a  o not mix calls.
2c1c0 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ** to sqlite3_co
2c1d0 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20 73  lumn_text() or s
2c1e0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
2c1f0 6f 62 28 29 20 77 69 74 68 20 63 61 6c 6c 73 20  ob() with calls 
2c200 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  to.** sqlite3_co
2c210 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c 20  lumn_bytes16(), 
2c220 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20 63  and do not mix c
2c230 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
2c240 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a  column_text16().
2c250 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f  ** with calls to
2c260 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2c270 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  bytes()..**.** ^
2c280 54 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74  The pointers ret
2c290 75 72 6e 65 64 20 61 72 65 20 76 61 6c 69 64 20  urned are valid 
2c2a0 75 6e 74 69 6c 20 61 20 74 79 70 65 20 63 6f 6e  until a type con
2c2b0 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 20 61  version occurs a
2c2c0 73 0a 2a 2a 20 64 65 73 63 72 69 62 65 64 20 61  s.** described a
2c2d0 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b  bove, or until [
2c2e0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
2c2f0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  or [sqlite3_rese
2c300 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  t()] or.** [sqli
2c310 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
2c320 69 73 20 63 61 6c 6c 65 64 2e 20 20 5e 54 68 65  is called.  ^The
2c330 20 6d 65 6d 6f 72 79 20 73 70 61 63 65 20 75 73   memory space us
2c340 65 64 20 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e  ed to hold strin
2c350 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 20  gs.** and BLOBs 
2c360 69 73 20 66 72 65 65 64 20 61 75 74 6f 6d 61 74  is freed automat
2c370 69 63 61 6c 6c 79 2e 20 20 44 6f 20 3c 62 3e 6e  ically.  Do <b>n
2c380 6f 74 3c 2f 62 3e 20 70 61 73 73 20 74 68 65 20  ot</b> pass the 
2c390 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65  pointers returne
2c3a0 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d.** [sqlite3_co
2c3b0 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73  lumn_blob()], [s
2c3c0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2c3d0 78 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f  xt()], etc. into
2c3e0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  .** [sqlite3_fre
2c3f0 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66  e()]..**.** ^(If
2c400 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
2c410 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  tion error occur
2c420 73 20 64 75 72 69 6e 67 20 74 68 65 20 65 76 61  s during the eva
2c430 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a  luation of any.*
2c440 2a 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  * of these routi
2c450 6e 65 73 2c 20 61 20 64 65 66 61 75 6c 74 20 76  nes, a default v
2c460 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65 64  alue is returned
2c470 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 76  .  The default v
2c480 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74 68 65  alue.** is eithe
2c490 72 20 74 68 65 20 69 6e 74 65 67 65 72 20 30 2c  r the integer 0,
2c4a0 20 74 68 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f   the floating po
2c4b0 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20  int number 0.0, 
2c4c0 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69  or a NULL.** poi
2c4d0 6e 74 65 72 2e 20 20 53 75 62 73 65 71 75 65 6e  nter.  Subsequen
2c4e0 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  t calls to [sqli
2c4f0 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 77  te3_errcode()] w
2c500 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53  ill return.** [S
2c510 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e 0a  QLITE_NOMEM].)^.
2c520 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  */.SQLITE_API co
2c530 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
2c540 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71  3_column_blob(sq
2c550 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2c560 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41   iCol);.SQLITE_A
2c570 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  PI int sqlite3_c
2c580 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69  olumn_bytes(sqli
2c590 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
2c5a0 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  Col);.SQLITE_API
2c5b0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c   int sqlite3_col
2c5c0 75 6d 6e 5f 62 79 74 65 73 31 36 28 73 71 6c 69  umn_bytes16(sqli
2c5d0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
2c5e0 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  Col);.SQLITE_API
2c5f0 20 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f   double sqlite3_
2c600 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 71  column_double(sq
2c610 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2c620 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41   iCol);.SQLITE_A
2c630 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  PI int sqlite3_c
2c640 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65  olumn_int(sqlite
2c650 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
2c660 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73  l);.SQLITE_API s
2c670 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
2c680 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36  ite3_column_int6
2c690 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  4(sqlite3_stmt*,
2c6a0 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49   int iCol);.SQLI
2c6b0 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 75 6e 73  TE_API const uns
2c6c0 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69  igned char *sqli
2c6d0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
2c6e0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2c6f0 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45  nt iCol);.SQLITE
2c700 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20  _API const void 
2c710 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
2c720 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73  text16(sqlite3_s
2c730 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
2c740 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
2c750 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2c760 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ype(sqlite3_stmt
2c770 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51  *, int iCol);.SQ
2c780 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33  LITE_API sqlite3
2c790 5f 76 61 6c 75 65 20 2a 73 71 6c 69 74 65 33 5f  _value *sqlite3_
2c7a0 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 73 71 6c  column_value(sql
2c7b0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
2c7c0 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  iCol);../*.** CA
2c7d0 50 49 33 52 45 46 3a 20 44 65 73 74 72 6f 79 20  PI3REF: Destroy 
2c7e0 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
2c7f0 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a  ment Object.**.*
2c800 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66  * ^The sqlite3_f
2c810 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63 74 69  inalize() functi
2c820 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20  on is called to 
2c830 64 65 6c 65 74 65 20 61 20 5b 70 72 65 70 61 72  delete a [prepar
2c840 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
2c850 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72  * ^If the most r
2c860 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e  ecent evaluation
2c870 20 6f 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e   of the statemen
2c880 74 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 6e 6f  t encountered no
2c890 20 65 72 72 6f 72 73 20 6f 72 0a 2a 2a 20 6f 72   errors or.** or
2c8a0 20 69 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e   if the statemen
2c8b0 74 20 69 73 20 6e 65 76 65 72 20 62 65 65 6e 20  t is never been 
2c8c0 65 76 61 6c 75 61 74 65 64 2c 20 74 68 65 6e 20  evaluated, then 
2c8d0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2c8e0 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 53 51  () returns.** SQ
2c8f0 4c 49 54 45 5f 4f 4b 2e 20 20 5e 49 66 20 74 68  LITE_OK.  ^If th
2c900 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 76  e most recent ev
2c910 61 6c 75 61 74 69 6f 6e 20 6f 66 20 73 74 61 74  aluation of stat
2c920 65 6d 65 6e 74 20 53 20 66 61 69 6c 65 64 2c 20  ement S failed, 
2c930 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  then.** sqlite3_
2c940 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 65 74 75  finalize(S) retu
2c950 72 6e 73 20 74 68 65 20 61 70 70 72 6f 70 72 69  rns the appropri
2c960 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ate [error code]
2c970 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64   or.** [extended
2c980 20 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a   error code]..**
2c990 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2c9a0 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 6f 75  _finalize(S) rou
2c9b0 74 69 6e 65 20 63 61 6e 20 62 65 20 63 61 6c 6c  tine can be call
2c9c0 65 64 20 61 74 20 61 6e 79 20 70 6f 69 6e 74 20  ed at any point 
2c9d0 64 75 72 69 6e 67 0a 2a 2a 20 74 68 65 20 6c 69  during.** the li
2c9e0 66 65 20 63 79 63 6c 65 20 6f 66 20 5b 70 72 65  fe cycle of [pre
2c9f0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2ca00 20 53 3a 0a 2a 2a 20 62 65 66 6f 72 65 20 73 74   S:.** before st
2ca10 61 74 65 6d 65 6e 74 20 53 20 69 73 20 65 76 65  atement S is eve
2ca20 72 20 65 76 61 6c 75 61 74 65 64 2c 20 61 66 74  r evaluated, aft
2ca30 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72  er.** one or mor
2ca40 65 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  e calls to [sqli
2ca50 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 20 6f 72  te3_reset()], or
2ca60 20 61 66 74 65 72 20 61 6e 79 20 63 61 6c 6c 0a   after any call.
2ca70 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ** to [sqlite3_s
2ca80 74 65 70 28 29 5d 20 72 65 67 61 72 64 6c 65 73  tep()] regardles
2ca90 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20  s of whether or 
2caa0 6e 6f 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e  not the statemen
2cab0 74 20 68 61 73 0a 2a 2a 20 63 6f 6d 70 6c 65 74  t has.** complet
2cac0 65 64 20 65 78 65 63 75 74 69 6f 6e 2e 0a 2a 2a  ed execution..**
2cad0 0a 2a 2a 20 5e 49 6e 76 6f 6b 69 6e 67 20 73 71  .** ^Invoking sq
2cae0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
2caf0 20 6f 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   on a NULL point
2cb00 65 72 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73  er is a harmless
2cb10 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 54 68   no-op..**.** Th
2cb20 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
2cb30 73 74 20 66 69 6e 61 6c 69 7a 65 20 65 76 65 72  st finalize ever
2cb40 79 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  y [prepared stat
2cb50 65 6d 65 6e 74 5d 20 69 6e 20 6f 72 64 65 72 20  ement] in order 
2cb60 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 72 65 73 6f  to avoid.** reso
2cb70 75 72 63 65 20 6c 65 61 6b 73 2e 20 20 49 74 20  urce leaks.  It 
2cb80 69 73 20 61 20 67 72 69 65 76 6f 75 73 20 65 72  is a grievous er
2cb90 72 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70 6c  ror for the appl
2cba0 69 63 61 74 69 6f 6e 20 74 6f 20 74 72 79 20 74  ication to try t
2cbb0 6f 20 75 73 65 0a 2a 2a 20 61 20 70 72 65 70 61  o use.** a prepa
2cbc0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 66  red statement af
2cbd0 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20  ter it has been 
2cbe0 66 69 6e 61 6c 69 7a 65 64 2e 20 20 41 6e 79 20  finalized.  Any 
2cbf0 75 73 65 20 6f 66 20 61 20 70 72 65 70 61 72 65  use of a prepare
2cc00 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61  d.** statement a
2cc10 66 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e  fter it has been
2cc20 20 66 69 6e 61 6c 69 7a 65 64 20 63 61 6e 20 72   finalized can r
2cc30 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e  esult in undefin
2cc40 65 64 20 61 6e 64 0a 2a 2a 20 75 6e 64 65 73 69  ed and.** undesi
2cc50 72 61 62 6c 65 20 62 65 68 61 76 69 6f 72 20 73  rable behavior s
2cc60 75 63 68 20 61 73 20 73 65 67 66 61 75 6c 74 73  uch as segfaults
2cc70 20 61 6e 64 20 68 65 61 70 20 63 6f 72 72 75 70   and heap corrup
2cc80 74 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  tion..*/.SQLITE_
2cc90 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
2cca0 66 69 6e 61 6c 69 7a 65 28 73 71 6c 69 74 65 33  finalize(sqlite3
2ccb0 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
2ccc0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2ccd0 52 65 73 65 74 20 41 20 50 72 65 70 61 72 65 64  Reset A Prepared
2cce0 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63   Statement Objec
2ccf0 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  t.**.** The sqli
2cd00 74 65 33 5f 72 65 73 65 74 28 29 20 66 75 6e 63  te3_reset() func
2cd10 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74  tion is called t
2cd20 6f 20 72 65 73 65 74 20 61 20 5b 70 72 65 70 61  o reset a [prepa
2cd30 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a  red statement].*
2cd40 2a 20 6f 62 6a 65 63 74 20 62 61 63 6b 20 74 6f  * object back to
2cd50 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61   its initial sta
2cd60 74 65 2c 20 72 65 61 64 79 20 74 6f 20 62 65 20  te, ready to be 
2cd70 72 65 2d 65 78 65 63 75 74 65 64 2e 0a 2a 2a 20  re-executed..** 
2cd80 5e 41 6e 79 20 53 51 4c 20 73 74 61 74 65 6d 65  ^Any SQL stateme
2cd90 6e 74 20 76 61 72 69 61 62 6c 65 73 20 74 68 61  nt variables tha
2cda0 74 20 68 61 64 20 76 61 6c 75 65 73 20 62 6f 75  t had values bou
2cdb0 6e 64 20 74 6f 20 74 68 65 6d 20 75 73 69 6e 67  nd to them using
2cdc0 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33  .** the [sqlite3
2cdd0 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c  _bind_blob | sql
2cde0 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 41 50  ite3_bind_*() AP
2cdf0 49 5d 20 72 65 74 61 69 6e 20 74 68 65 69 72 20  I] retain their 
2ce00 76 61 6c 75 65 73 2e 0a 2a 2a 20 55 73 65 20 5b  values..** Use [
2ce10 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69  sqlite3_clear_bi
2ce20 6e 64 69 6e 67 73 28 29 5d 20 74 6f 20 72 65 73  ndings()] to res
2ce30 65 74 20 74 68 65 20 62 69 6e 64 69 6e 67 73 2e  et the bindings.
2ce40 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c  .**.** ^The [sql
2ce50 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69  ite3_reset(S)] i
2ce60 6e 74 65 72 66 61 63 65 20 72 65 73 65 74 73 20  nterface resets 
2ce70 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
2ce80 61 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20 62 61  atement] S.** ba
2ce90 63 6b 20 74 6f 20 74 68 65 20 62 65 67 69 6e 6e  ck to the beginn
2cea0 69 6e 67 20 6f 66 20 69 74 73 20 70 72 6f 67 72  ing of its progr
2ceb0 61 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  am..**.** ^If th
2cec0 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61  e most recent ca
2ced0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
2cee0 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a  tep(S)] for the.
2cef0 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
2cf00 74 65 6d 65 6e 74 5d 20 53 20 72 65 74 75 72 6e  tement] S return
2cf10 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20  ed [SQLITE_ROW] 
2cf20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  or [SQLITE_DONE]
2cf30 2c 0a 2a 2a 20 6f 72 20 69 66 20 5b 73 71 6c 69  ,.** or if [sqli
2cf40 74 65 33 5f 73 74 65 70 28 53 29 5d 20 68 61 73  te3_step(S)] has
2cf50 20 6e 65 76 65 72 20 62 65 66 6f 72 65 20 62 65   never before be
2cf60 65 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a  en called on S,.
2cf70 2a 2a 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33  ** then [sqlite3
2cf80 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74 75 72  _reset(S)] retur
2cf90 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a  ns [SQLITE_OK]..
2cfa0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f  **.** ^If the mo
2cfb0 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74  st recent call t
2cfc0 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  o [sqlite3_step(
2cfd0 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b  S)] for the.** [
2cfe0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2cff0 6e 74 5d 20 53 20 69 6e 64 69 63 61 74 65 64 20  nt] S indicated 
2d000 61 6e 20 65 72 72 6f 72 2c 20 74 68 65 6e 0a 2a  an error, then.*
2d010 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  * [sqlite3_reset
2d020 28 53 29 5d 20 72 65 74 75 72 6e 73 20 61 6e 20  (S)] returns an 
2d030 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72  appropriate [err
2d040 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20  or code]..**.** 
2d050 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65  ^The [sqlite3_re
2d060 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63  set(S)] interfac
2d070 65 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67  e does not chang
2d080 65 20 74 68 65 20 76 61 6c 75 65 73 0a 2a 2a 20  e the values.** 
2d090 6f 66 20 61 6e 79 20 5b 73 71 6c 69 74 65 33 5f  of any [sqlite3_
2d0a0 62 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e  bind_blob|bindin
2d0b0 67 73 5d 20 6f 6e 20 74 68 65 20 5b 70 72 65 70  gs] on the [prep
2d0c0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2d0d0 53 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  S..*/.SQLITE_API
2d0e0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 73   int sqlite3_res
2d0f0 65 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  et(sqlite3_stmt 
2d100 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
2d110 43 41 50 49 33 52 45 46 3a 20 43 72 65 61 74 65  CAPI3REF: Create
2d120 20 4f 72 20 52 65 64 65 66 69 6e 65 20 53 51 4c   Or Redefine SQL
2d130 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b 45   Functions.** KE
2d140 59 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f  YWORDS: {functio
2d150 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69  n creation routi
2d160 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  nes}.** KEYWORDS
2d170 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  : {application-d
2d180 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
2d190 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ion}.** KEYWORDS
2d1a0 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  : {application-d
2d1b0 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
2d1c0 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ions}.**.** ^The
2d1d0 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f  se functions (co
2d1e0 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e  llectively known
2d1f0 20 61 73 20 22 66 75 6e 63 74 69 6f 6e 20 63 72   as "function cr
2d200 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22  eation routines"
2d210 29 0a 2a 2a 20 61 72 65 20 75 73 65 64 20 74 6f  ).** are used to
2d220 20 61 64 64 20 53 51 4c 20 66 75 6e 63 74 69 6f   add SQL functio
2d230 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73  ns or aggregates
2d240 20 6f 72 20 74 6f 20 72 65 64 65 66 69 6e 65 20   or to redefine 
2d250 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20  the behavior.** 
2d260 6f 66 20 65 78 69 73 74 69 6e 67 20 53 51 4c 20  of existing SQL 
2d270 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67  functions or agg
2d280 72 65 67 61 74 65 73 2e 20 20 54 68 65 20 6f 6e  regates.  The on
2d290 6c 79 20 64 69 66 66 65 72 65 6e 63 65 73 20 62  ly differences b
2d2a0 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 73 65 20  etween.** these 
2d2b0 72 6f 75 74 69 6e 65 73 20 61 72 65 20 74 68 65  routines are the
2d2c0 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 65   text encoding e
2d2d0 78 70 65 63 74 65 64 20 66 6f 72 0a 2a 2a 20 74  xpected for.** t
2d2e0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
2d2f0 74 65 72 20 28 74 68 65 20 6e 61 6d 65 20 6f 66  ter (the name of
2d300 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 62 65   the function be
2d310 69 6e 67 20 63 72 65 61 74 65 64 29 0a 2a 2a 20  ing created).** 
2d320 61 6e 64 20 74 68 65 20 70 72 65 73 65 6e 63 65  and the presence
2d330 20 6f 72 20 61 62 73 65 6e 63 65 20 6f 66 20 61   or absence of a
2d340 20 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c   destructor call
2d350 62 61 63 6b 20 66 6f 72 0a 2a 2a 20 74 68 65 20  back for.** the 
2d360 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61  application data
2d370 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
2d380 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d  ^The first param
2d390 65 74 65 72 20 69 73 20 74 68 65 20 5b 64 61 74  eter is the [dat
2d3a0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2d3b0 5d 20 74 6f 20 77 68 69 63 68 20 74 68 65 20 53  ] to which the S
2d3c0 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69  QL.** function i
2d3d0 73 20 74 6f 20 62 65 20 61 64 64 65 64 2e 20 20  s to be added.  
2d3e0 5e 49 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69  ^If an applicati
2d3f0 6f 6e 20 75 73 65 73 20 6d 6f 72 65 20 74 68 61  on uses more tha
2d400 6e 20 6f 6e 65 20 64 61 74 61 62 61 73 65 0a 2a  n one database.*
2d410 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 65  * connection the
2d420 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  n application-de
2d430 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
2d440 6f 6e 73 20 6d 75 73 74 20 62 65 20 61 64 64 65  ons must be adde
2d450 64 0a 2a 2a 20 74 6f 20 65 61 63 68 20 64 61 74  d.** to each dat
2d460 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2d470 20 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a   separately..**.
2d480 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70  ** ^The second p
2d490 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
2d4a0 6e 61 6d 65 20 6f 66 20 74 68 65 20 53 51 4c 20  name of the SQL 
2d4b0 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 63  function to be c
2d4c0 72 65 61 74 65 64 20 6f 72 0a 2a 2a 20 72 65 64  reated or.** red
2d4d0 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 20 6c 65  efined.  ^The le
2d4e0 6e 67 74 68 20 6f 66 20 74 68 65 20 6e 61 6d 65  ngth of the name
2d4f0 20 69 73 20 6c 69 6d 69 74 65 64 20 74 6f 20 32   is limited to 2
2d500 35 35 20 62 79 74 65 73 20 69 6e 20 61 20 55 54  55 bytes in a UT
2d510 46 2d 38 0a 2a 2a 20 72 65 70 72 65 73 65 6e 74  F-8.** represent
2d520 61 74 69 6f 6e 2c 20 65 78 63 6c 75 73 69 76 65  ation, exclusive
2d530 20 6f 66 20 74 68 65 20 7a 65 72 6f 2d 74 65 72   of the zero-ter
2d540 6d 69 6e 61 74 6f 72 2e 20 20 5e 4e 6f 74 65 20  minator.  ^Note 
2d550 74 68 61 74 20 74 68 65 20 6e 61 6d 65 0a 2a 2a  that the name.**
2d560 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20 69 73   length limit is
2d570 20 69 6e 20 55 54 46 2d 38 20 62 79 74 65 73 2c   in UTF-8 bytes,
2d580 20 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 20   not characters 
2d590 6e 6f 72 20 55 54 46 2d 31 36 20 62 79 74 65 73  nor UTF-16 bytes
2d5a0 2e 20 20 0a 2a 2a 20 5e 41 6e 79 20 61 74 74 65  .  .** ^Any atte
2d5b0 6d 70 74 20 74 6f 20 63 72 65 61 74 65 20 61 20  mpt to create a 
2d5c0 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20  function with a 
2d5d0 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77  longer name.** w
2d5e0 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20 5b 53  ill result in [S
2d5f0 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 62 65  QLITE_MISUSE] be
2d600 69 6e 67 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a  ing returned..**
2d610 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 70  .** ^The third p
2d620 61 72 61 6d 65 74 65 72 20 28 6e 41 72 67 29 0a  arameter (nArg).
2d630 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72  ** is the number
2d640 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74 68   of arguments th
2d650 61 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  at the SQL funct
2d660 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67  ion or.** aggreg
2d670 61 74 65 20 74 61 6b 65 73 2e 20 5e 49 66 20 74  ate takes. ^If t
2d680 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 69 73  his parameter is
2d690 20 2d 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51   -1, then the SQ
2d6a0 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a  L function or.**
2d6b0 20 61 67 67 72 65 67 61 74 65 20 6d 61 79 20 74   aggregate may t
2d6c0 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f  ake any number o
2d6d0 66 20 61 72 67 75 6d 65 6e 74 73 20 62 65 74 77  f arguments betw
2d6e0 65 65 6e 20 30 20 61 6e 64 20 74 68 65 20 6c 69  een 0 and the li
2d6f0 6d 69 74 0a 2a 2a 20 73 65 74 20 62 79 20 5b 73  mit.** set by [s
2d700 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53  qlite3_limit]([S
2d710 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43  QLITE_LIMIT_FUNC
2d720 54 49 4f 4e 5f 41 52 47 5d 29 2e 20 20 49 66 20  TION_ARG]).  If 
2d730 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72  the third.** par
2d740 61 6d 65 74 65 72 20 69 73 20 6c 65 73 73 20 74  ameter is less t
2d750 68 61 6e 20 2d 31 20 6f 72 20 67 72 65 61 74 65  han -1 or greate
2d760 72 20 74 68 61 6e 20 31 32 37 20 74 68 65 6e 20  r than 127 then 
2d770 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 0a  the behavior is.
2d780 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  ** undefined..**
2d790 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20  .** ^The fourth 
2d7a0 70 61 72 61 6d 65 74 65 72 2c 20 65 54 65 78 74  parameter, eText
2d7b0 52 65 70 2c 20 73 70 65 63 69 66 69 65 73 20 77  Rep, specifies w
2d7c0 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55  hat.** [SQLITE_U
2d7d0 54 46 38 20 7c 20 74 65 78 74 20 65 6e 63 6f 64  TF8 | text encod
2d7e0 69 6e 67 5d 20 74 68 69 73 20 53 51 4c 20 66 75  ing] this SQL fu
2d7f0 6e 63 74 69 6f 6e 20 70 72 65 66 65 72 73 20 66  nction prefers f
2d800 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d 65  or.** its parame
2d810 74 65 72 73 2e 20 20 45 76 65 72 79 20 53 51 4c  ters.  Every SQL
2d820 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
2d830 65 6e 74 61 74 69 6f 6e 20 6d 75 73 74 20 62 65  entation must be
2d840 20 61 62 6c 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a   able to work.**
2d850 20 77 69 74 68 20 55 54 46 2d 38 2c 20 55 54 46   with UTF-8, UTF
2d860 2d 31 36 6c 65 2c 20 6f 72 20 55 54 46 2d 31 36  -16le, or UTF-16
2d870 62 65 2e 20 20 42 75 74 20 73 6f 6d 65 20 69 6d  be.  But some im
2d880 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 61  plementations ma
2d890 79 20 62 65 0a 2a 2a 20 6d 6f 72 65 20 65 66 66  y be.** more eff
2d8a0 69 63 69 65 6e 74 20 77 69 74 68 20 6f 6e 65 20  icient with one 
2d8b0 65 6e 63 6f 64 69 6e 67 20 74 68 61 6e 20 61 6e  encoding than an
2d8c0 6f 74 68 65 72 2e 20 20 5e 41 6e 20 61 70 70 6c  other.  ^An appl
2d8d0 69 63 61 74 69 6f 6e 20 6d 61 79 0a 2a 2a 20 69  ication may.** i
2d8e0 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 72  nvoke sqlite3_cr
2d8f0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20  eate_function() 
2d900 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  or sqlite3_creat
2d910 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 20 6d  e_function16() m
2d920 75 6c 74 69 70 6c 65 0a 2a 2a 20 74 69 6d 65 73  ultiple.** times
2d930 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 66   with the same f
2d940 75 6e 63 74 69 6f 6e 20 62 75 74 20 77 69 74 68  unction but with
2d950 20 64 69 66 66 65 72 65 6e 74 20 76 61 6c 75 65   different value
2d960 73 20 6f 66 20 65 54 65 78 74 52 65 70 2e 0a 2a  s of eTextRep..*
2d970 2a 20 5e 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65  * ^When multiple
2d980 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
2d990 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e   of the same fun
2d9a0 63 74 69 6f 6e 20 61 72 65 20 61 76 61 69 6c 61  ction are availa
2d9b0 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77  ble, SQLite.** w
2d9c0 69 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e 65  ill pick the one
2d9d0 20 74 68 61 74 20 69 6e 76 6f 6c 76 65 73 20 74   that involves t
2d9e0 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20  he least amount 
2d9f0 6f 66 20 64 61 74 61 20 63 6f 6e 76 65 72 73 69  of data conversi
2da00 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 72 65 20  on..** If there 
2da10 69 73 20 6f 6e 6c 79 20 61 20 73 69 6e 67 6c 65  is only a single
2da20 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
2da30 77 68 69 63 68 20 64 6f 65 73 20 6e 6f 74 20 63  which does not c
2da40 61 72 65 20 77 68 61 74 20 74 65 78 74 0a 2a 2a  are what text.**
2da50 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65   encoding is use
2da60 64 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 75 72  d, then the four
2da70 74 68 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75  th argument shou
2da80 6c 64 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 4e  ld be [SQLITE_AN
2da90 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  Y]..**.** ^(The 
2daa0 66 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 20  fifth parameter 
2dab0 69 73 20 61 6e 20 61 72 62 69 74 72 61 72 79 20  is an arbitrary 
2dac0 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 69 6d  pointer.  The im
2dad0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
2dae0 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  the.** function 
2daf0 63 61 6e 20 67 61 69 6e 20 61 63 63 65 73 73 20  can gain access 
2db00 74 6f 20 74 68 69 73 20 70 6f 69 6e 74 65 72 20  to this pointer 
2db10 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 75  using [sqlite3_u
2db20 73 65 72 5f 64 61 74 61 28 29 5d 2e 29 5e 0a 2a  ser_data()].)^.*
2db30 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74 68 2c  *.** ^The sixth,
2db40 20 73 65 76 65 6e 74 68 20 61 6e 64 20 65 69 67   seventh and eig
2db50 68 74 68 20 70 61 72 61 6d 65 74 65 72 73 2c 20  hth parameters, 
2db60 78 46 75 6e 63 2c 20 78 53 74 65 70 20 61 6e 64  xFunc, xStep and
2db70 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20   xFinal, are.** 
2db80 70 6f 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61  pointers to C-la
2db90 6e 67 75 61 67 65 20 66 75 6e 63 74 69 6f 6e 73  nguage functions
2dba0 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20   that implement 
2dbb0 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
2dbc0 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65   or.** aggregate
2dbd0 2e 20 5e 41 20 73 63 61 6c 61 72 20 53 51 4c 20  . ^A scalar SQL 
2dbe0 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65  function require
2dbf0 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  s an implementat
2dc00 69 6f 6e 20 6f 66 20 74 68 65 20 78 46 75 6e 63  ion of the xFunc
2dc10 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c  .** callback onl
2dc20 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73  y; NULL pointers
2dc30 20 6d 75 73 74 20 62 65 20 70 61 73 73 65 64 20   must be passed 
2dc40 61 73 20 74 68 65 20 78 53 74 65 70 20 61 6e 64  as the xStep and
2dc50 20 78 46 69 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d   xFinal.** param
2dc60 65 74 65 72 73 2e 20 5e 41 6e 20 61 67 67 72 65  eters. ^An aggre
2dc70 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f  gate SQL functio
2dc80 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d  n requires an im
2dc90 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
2dca0 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69  xStep.** and xFi
2dcb0 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 70 6f 69  nal and NULL poi
2dcc0 6e 74 65 72 20 6d 75 73 74 20 62 65 20 70 61 73  nter must be pas
2dcd0 73 65 64 20 66 6f 72 20 78 46 75 6e 63 2e 20 5e  sed for xFunc. ^
2dce0 54 6f 20 64 65 6c 65 74 65 20 61 6e 20 65 78 69  To delete an exi
2dcf0 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 6e  sting.** SQL fun
2dd00 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61  ction or aggrega
2dd10 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20 70 6f  te, pass NULL po
2dd20 69 6e 74 65 72 73 20 66 6f 72 20 61 6c 6c 20 74  inters for all t
2dd30 68 72 65 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  hree function.**
2dd40 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a   callbacks..**.*
2dd50 2a 20 5e 28 49 66 20 74 68 65 20 6e 69 6e 74 68  * ^(If the ninth
2dd60 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
2dd70 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2dd80 63 74 69 6f 6e 5f 76 32 28 29 20 69 73 20 6e 6f  ction_v2() is no
2dd90 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 74 68 65 6e 20  t NULL,.** then 
2dda0 69 74 20 69 73 20 64 65 73 74 72 75 63 74 6f 72  it is destructor
2ddb0 20 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61   for the applica
2ddc0 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65  tion data pointe
2ddd0 72 2e 20 0a 2a 2a 20 54 68 65 20 64 65 73 74 72  r. .** The destr
2dde0 75 63 74 6f 72 20 69 73 20 69 6e 76 6f 6b 65 64  uctor is invoked
2ddf0 20 77 68 65 6e 20 74 68 65 20 66 75 6e 63 74 69   when the functi
2de00 6f 6e 20 69 73 20 64 65 6c 65 74 65 64 2c 20 65  on is deleted, e
2de10 69 74 68 65 72 20 62 79 20 62 65 69 6e 67 0a 2a  ither by being.*
2de20 2a 20 6f 76 65 72 6c 6f 61 64 65 64 20 6f 72 20  * overloaded or 
2de30 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  when the databas
2de40 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f  e connection clo
2de50 73 65 73 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 64  ses.)^.** ^The d
2de60 65 73 74 72 75 63 74 6f 72 20 69 73 20 61 6c 73  estructor is als
2de70 6f 20 69 6e 76 6f 6b 65 64 20 69 66 20 74 68 65  o invoked if the
2de80 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69   call to.** sqli
2de90 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2dea0 69 6f 6e 5f 76 32 28 29 20 66 61 69 6c 73 2e 0a  ion_v2() fails..
2deb0 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20 64 65 73  ** ^When the des
2dec0 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b  tructor callback
2ded0 20 6f 66 20 74 68 65 20 74 65 6e 74 68 20 70 61   of the tenth pa
2dee0 72 61 6d 65 74 65 72 20 69 73 20 69 6e 76 6f 6b  rameter is invok
2def0 65 64 2c 20 69 74 0a 2a 2a 20 69 73 20 70 61 73  ed, it.** is pas
2df00 73 65 64 20 61 20 73 69 6e 67 6c 65 20 61 72 67  sed a single arg
2df10 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
2df20 20 63 6f 70 79 20 6f 66 20 74 68 65 20 61 70 70   copy of the app
2df30 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 0a 2a  lication data .*
2df40 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 20  * pointer which 
2df50 77 61 73 20 74 68 65 20 66 69 66 74 68 20 70 61  was the fifth pa
2df60 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
2df70 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2df80 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  on_v2()..**.** ^
2df90 49 74 20 69 73 20 70 65 72 6d 69 74 74 65 64 20  It is permitted 
2dfa0 74 6f 20 72 65 67 69 73 74 65 72 20 6d 75 6c 74  to register mult
2dfb0 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  iple implementat
2dfc0 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65  ions of the same
2dfd0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 77 69  .** functions wi
2dfe0 74 68 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65  th the same name
2dff0 20 62 75 74 20 77 69 74 68 20 65 69 74 68 65 72   but with either
2e000 20 64 69 66 66 65 72 69 6e 67 20 6e 75 6d 62 65   differing numbe
2e010 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 6e  rs of.** argumen
2e020 74 73 20 6f 72 20 64 69 66 66 65 72 69 6e 67 20  ts or differing 
2e030 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65  preferred text e
2e040 6e 63 6f 64 69 6e 67 73 2e 20 20 5e 53 51 4c 69  ncodings.  ^SQLi
2e050 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 74  te will use.** t
2e060 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
2e070 6e 20 74 68 61 74 20 6d 6f 73 74 20 63 6c 6f 73  n that most clos
2e080 65 6c 79 20 6d 61 74 63 68 65 73 20 74 68 65 20  ely matches the 
2e090 77 61 79 20 69 6e 20 77 68 69 63 68 20 74 68 65  way in which the
2e0a0 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  .** SQL function
2e0b0 20 69 73 20 75 73 65 64 2e 20 20 5e 41 20 66 75   is used.  ^A fu
2e0c0 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74  nction implement
2e0d0 61 74 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e  ation with a non
2e0e0 2d 6e 65 67 61 74 69 76 65 0a 2a 2a 20 6e 41 72  -negative.** nAr
2e0f0 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  g parameter is a
2e100 20 62 65 74 74 65 72 20 6d 61 74 63 68 20 74 68   better match th
2e110 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 69 6d  an a function im
2e120 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74  plementation wit
2e130 68 0a 2a 2a 20 61 20 6e 65 67 61 74 69 76 65 20  h.** a negative 
2e140 6e 41 72 67 2e 20 20 5e 41 20 66 75 6e 63 74 69  nArg.  ^A functi
2e150 6f 6e 20 77 68 65 72 65 20 74 68 65 20 70 72 65  on where the pre
2e160 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f  ferred text enco
2e170 64 69 6e 67 0a 2a 2a 20 6d 61 74 63 68 65 73 20  ding.** matches 
2e180 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 63  the database enc
2e190 6f 64 69 6e 67 20 69 73 20 61 20 62 65 74 74 65  oding is a bette
2e1a0 72 0a 2a 2a 20 6d 61 74 63 68 20 74 68 61 6e 20  r.** match than 
2e1b0 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65  a function where
2e1c0 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 69 73   the encoding is
2e1d0 20 64 69 66 66 65 72 65 6e 74 2e 20 20 0a 2a 2a   different.  .**
2e1e0 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65   ^A function whe
2e1f0 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20  re the encoding 
2e200 64 69 66 66 65 72 65 6e 63 65 20 69 73 20 62 65  difference is be
2e210 74 77 65 65 6e 20 55 54 46 31 36 6c 65 20 61 6e  tween UTF16le an
2e220 64 20 55 54 46 31 36 62 65 0a 2a 2a 20 69 73 20  d UTF16be.** is 
2e230 61 20 63 6c 6f 73 65 72 20 6d 61 74 63 68 20 74  a closer match t
2e240 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77  han a function w
2e250 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e  here the encodin
2e260 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 0a  g difference is.
2e270 2a 2a 20 62 65 74 77 65 65 6e 20 55 54 46 38 20  ** between UTF8 
2e280 61 6e 64 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a  and UTF16..**.**
2e290 20 5e 42 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74   ^Built-in funct
2e2a0 69 6f 6e 73 20 6d 61 79 20 62 65 20 6f 76 65 72  ions may be over
2e2b0 6c 6f 61 64 65 64 20 62 79 20 6e 65 77 20 61 70  loaded by new ap
2e2c0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
2e2d0 64 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a  d functions..**.
2e2e0 2a 2a 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 69  ** ^An applicati
2e2f0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
2e300 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64  ion is permitted
2e310 20 74 6f 20 63 61 6c 6c 20 6f 74 68 65 72 0a 2a   to call other.*
2e320 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  * SQLite interfa
2e330 63 65 73 2e 20 20 48 6f 77 65 76 65 72 2c 20 73  ces.  However, s
2e340 75 63 68 20 63 61 6c 6c 73 20 6d 75 73 74 20 6e  uch calls must n
2e350 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20 74 68 65 20  ot.** close the 
2e360 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2e370 69 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c 69 7a 65  ion nor finalize
2e380 20 6f 72 20 72 65 73 65 74 20 74 68 65 20 70 72   or reset the pr
2e390 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d  epared.** statem
2e3a0 65 6e 74 20 69 6e 20 77 68 69 63 68 20 74 68 65  ent in which the
2e3b0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e   function is run
2e3c0 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  ning..*/.SQLITE_
2e3d0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
2e3e0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
2e3f0 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a  .  sqlite3 *db,.
2e400 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46    const char *zF
2e410 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69  unctionName,.  i
2e420 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65  nt nArg,.  int e
2e430 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20  TextRep,.  void 
2e440 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a  *pApp,.  void (*
2e450 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63  xFunc)(sqlite3_c
2e460 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
2e470 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
2e480 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71  void (*xStep)(sq
2e490 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
2e4a0 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
2e4b0 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  **),.  void (*xF
2e4c0 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f  inal)(sqlite3_co
2e4d0 6e 74 65 78 74 2a 29 0a 29 3b 0a 53 51 4c 49 54  ntext*).);.SQLIT
2e4e0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
2e4f0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2e500 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  n16(.  sqlite3 *
2e510 64 62 2c 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64  db,.  const void
2e520 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c   *zFunctionName,
2e530 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69  .  int nArg,.  i
2e540 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76  nt eTextRep,.  v
2e550 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69  oid *pApp,.  voi
2e560 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74  d (*xFunc)(sqlit
2e570 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
2e580 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
2e590 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70  ,.  void (*xStep
2e5a0 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
2e5b0 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
2e5c0 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
2e5d0 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65  (*xFinal)(sqlite
2e5e0 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 53  3_context*).);.S
2e5f0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
2e600 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2e610 63 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69  ction_v2(.  sqli
2e620 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74  te3 *db,.  const
2e630 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e   char *zFunction
2e640 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67  Name,.  int nArg
2e650 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70  ,.  int eTextRep
2e660 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a  ,.  void *pApp,.
2e670 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28    void (*xFunc)(
2e680 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2e690 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
2e6a0 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
2e6b0 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63  xStep)(sqlite3_c
2e6c0 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
2e6d0 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
2e6e0 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73  void (*xFinal)(s
2e6f0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
2e700 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72  ,.  void(*xDestr
2e710 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f  oy)(void*).);../
2e720 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
2e730 65 78 74 20 45 6e 63 6f 64 69 6e 67 73 0a 2a 2a  ext Encodings.**
2e740 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
2e750 6e 74 20 64 65 66 69 6e 65 20 69 6e 74 65 67 65  nt define intege
2e760 72 20 63 6f 64 65 73 20 74 68 61 74 20 72 65 70  r codes that rep
2e770 72 65 73 65 6e 74 20 74 68 65 20 76 61 72 69 6f  resent the vario
2e780 75 73 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64  us.** text encod
2e790 69 6e 67 73 20 73 75 70 70 6f 72 74 65 64 20 62  ings supported b
2e7a0 79 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65  y SQLite..*/.#de
2e7b0 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 38  fine SQLITE_UTF8
2e7c0 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65             1.#de
2e7d0 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31  fine SQLITE_UTF1
2e7e0 36 4c 45 20 20 20 20 20 20 20 20 32 0a 23 64 65  6LE        2.#de
2e7f0 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31  fine SQLITE_UTF1
2e800 36 42 45 20 20 20 20 20 20 20 20 33 0a 23 64 65  6BE        3.#de
2e810 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31  fine SQLITE_UTF1
2e820 36 20 20 20 20 20 20 20 20 20 20 34 20 20 20 20  6          4    
2e830 2f 2a 20 55 73 65 20 6e 61 74 69 76 65 20 62 79  /* Use native by
2e840 74 65 20 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66  te order */.#def
2e850 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 59 20 20  ine SQLITE_ANY  
2e860 20 20 20 20 20 20 20 20 20 20 35 20 20 20 20 2f            5    /
2e870 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  * sqlite3_create
2e880 5f 66 75 6e 63 74 69 6f 6e 20 6f 6e 6c 79 20 2a  _function only *
2e890 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
2e8a0 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 20 20  _UTF16_ALIGNED  
2e8b0 38 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f  8    /* sqlite3_
2e8c0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
2e8d0 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20   only */../*.** 
2e8e0 43 41 50 49 33 52 45 46 3a 20 44 65 70 72 65 63  CAPI3REF: Deprec
2e8f0 61 74 65 64 20 46 75 6e 63 74 69 6f 6e 73 0a 2a  ated Functions.*
2e900 2a 20 44 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a  * DEPRECATED.**.
2e910 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f  ** These functio
2e920 6e 73 20 61 72 65 20 5b 64 65 70 72 65 63 61 74  ns are [deprecat
2e930 65 64 5d 2e 20 20 49 6e 20 6f 72 64 65 72 20 74  ed].  In order t
2e940 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61  o maintain.** ba
2e950 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62  ckwards compatib
2e960 69 6c 69 74 79 20 77 69 74 68 20 6f 6c 64 65 72  ility with older
2e970 20 63 6f 64 65 2c 20 74 68 65 73 65 20 66 75 6e   code, these fun
2e980 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20  ctions continue 
2e990 0a 2a 2a 20 74 6f 20 62 65 20 73 75 70 70 6f 72  .** to be suppor
2e9a0 74 65 64 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e  ted.  However, n
2e9b0 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  ew applications 
2e9c0 73 68 6f 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20  should avoid.** 
2e9d0 74 68 65 20 75 73 65 20 6f 66 20 74 68 65 73 65  the use of these
2e9e0 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20   functions.  To 
2e9f0 68 65 6c 70 20 65 6e 63 6f 75 72 61 67 65 20 70  help encourage p
2ea00 65 6f 70 6c 65 20 74 6f 20 61 76 6f 69 64 0a 2a  eople to avoid.*
2ea10 2a 20 75 73 69 6e 67 20 74 68 65 73 65 20 66 75  * using these fu
2ea20 6e 63 74 69 6f 6e 73 2c 20 77 65 20 61 72 65 20  nctions, we are 
2ea30 6e 6f 74 20 67 6f 69 6e 67 20 74 6f 20 74 65 6c  not going to tel
2ea40 6c 20 79 6f 75 20 77 68 61 74 20 74 68 65 79 20  l you what they 
2ea50 64 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53  do..*/.#ifndef S
2ea60 51 4c 49 54 45 5f 4f 4d 49 54 5f 44 45 50 52 45  QLITE_OMIT_DEPRE
2ea70 43 41 54 45 44 0a 53 51 4c 49 54 45 5f 41 50 49  CATED.SQLITE_API
2ea80 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54   SQLITE_DEPRECAT
2ea90 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 61  ED int sqlite3_a
2eaa0 67 67 72 65 67 61 74 65 5f 63 6f 75 6e 74 28 73  ggregate_count(s
2eab0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
2eac0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c  ;.SQLITE_API SQL
2ead0 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69  ITE_DEPRECATED i
2eae0 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 70 69 72  nt sqlite3_expir
2eaf0 65 64 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ed(sqlite3_stmt*
2eb00 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51  );.SQLITE_API SQ
2eb10 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
2eb20 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 72 61 6e  int sqlite3_tran
2eb30 73 66 65 72 5f 62 69 6e 64 69 6e 67 73 28 73 71  sfer_bindings(sq
2eb40 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 73 71 6c  lite3_stmt*, sql
2eb50 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c  ite3_stmt*);.SQL
2eb60 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44  ITE_API SQLITE_D
2eb70 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71  EPRECATED int sq
2eb80 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 63  lite3_global_rec
2eb90 6f 76 65 72 28 76 6f 69 64 29 3b 0a 53 51 4c 49  over(void);.SQLI
2eba0 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45  TE_API SQLITE_DE
2ebb0 50 52 45 43 41 54 45 44 20 76 6f 69 64 20 73 71  PRECATED void sq
2ebc0 6c 69 74 65 33 5f 74 68 72 65 61 64 5f 63 6c 65  lite3_thread_cle
2ebd0 61 6e 75 70 28 76 6f 69 64 29 3b 0a 53 51 4c 49  anup(void);.SQLI
2ebe0 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45  TE_API SQLITE_DE
2ebf0 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c  PRECATED int sql
2ec00 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72  ite3_memory_alar
2ec10 6d 28 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c  m(void(*)(void*,
2ec20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c 69 6e  sqlite3_int64,in
2ec30 74 29 2c 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33  t),void*,sqlite3
2ec40 5f 69 6e 74 36 34 29 3b 0a 23 65 6e 64 69 66 0a  _int64);.#endif.
2ec50 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2ec60 20 4f 62 74 61 69 6e 69 6e 67 20 53 51 4c 20 46   Obtaining SQL F
2ec70 75 6e 63 74 69 6f 6e 20 50 61 72 61 6d 65 74 65  unction Paramete
2ec80 72 20 56 61 6c 75 65 73 0a 2a 2a 0a 2a 2a 20 54  r Values.**.** T
2ec90 68 65 20 43 2d 6c 61 6e 67 75 61 67 65 20 69 6d  he C-language im
2eca0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
2ecb0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e  SQL functions an
2ecc0 64 20 61 67 67 72 65 67 61 74 65 73 20 75 73 65  d aggregates use
2ecd0 73 0a 2a 2a 20 74 68 69 73 20 73 65 74 20 6f 66  s.** this set of
2ece0 20 69 6e 74 65 72 66 61 63 65 20 72 6f 75 74 69   interface routi
2ecf0 6e 65 73 20 74 6f 20 61 63 63 65 73 73 20 74 68  nes to access th
2ed00 65 20 70 61 72 61 6d 65 74 65 72 20 76 61 6c 75  e parameter valu
2ed10 65 73 20 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 6e  es on.** the fun
2ed20 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61  ction or aggrega
2ed30 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46  te..**.** The xF
2ed40 75 6e 63 20 28 66 6f 72 20 73 63 61 6c 61 72 20  unc (for scalar 
2ed50 66 75 6e 63 74 69 6f 6e 73 29 20 6f 72 20 78 53  functions) or xS
2ed60 74 65 70 20 28 66 6f 72 20 61 67 67 72 65 67 61  tep (for aggrega
2ed70 74 65 73 29 20 70 61 72 61 6d 65 74 65 72 73 0a  tes) parameters.
2ed80 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ** to [sqlite3_c
2ed90 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
2eda0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  ] and [sqlite3_c
2edb0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
2edc0 28 29 5d 0a 2a 2a 20 64 65 66 69 6e 65 20 63 61  ()].** define ca
2edd0 6c 6c 62 61 63 6b 73 20 74 68 61 74 20 69 6d 70  llbacks that imp
2ede0 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66  lement the SQL f
2edf0 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67  unctions and agg
2ee00 72 65 67 61 74 65 73 2e 0a 2a 2a 20 54 68 65 20  regates..** The 
2ee10 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  3rd parameter to
2ee20 20 74 68 65 73 65 20 63 61 6c 6c 62 61 63 6b 73   these callbacks
2ee30 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20   is an array of 
2ee40 70 6f 69 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 5b  pointers to.** [
2ee50 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2ee60 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73  3_value] objects
2ee70 2e 20 20 54 68 65 72 65 20 69 73 20 6f 6e 65 20  .  There is one 
2ee80 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20  [sqlite3_value] 
2ee90 6f 62 6a 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61  object for.** ea
2eea0 63 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  ch parameter to 
2eeb0 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
2eec0 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  .  These routine
2eed0 73 20 61 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a  s are used to.**
2eee0 20 65 78 74 72 61 63 74 20 76 61 6c 75 65 73 20   extract values 
2eef0 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65  from the [sqlite
2ef00 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73  3_value] objects
2ef10 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ..**.** These ro
2ef20 75 74 69 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c 79  utines work only
2ef30 20 77 69 74 68 20 5b 70 72 6f 74 65 63 74 65 64   with [protected
2ef40 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
2ef50 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e 79 20  objects..** Any 
2ef60 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74  attempt to use t
2ef70 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e  hese routines on
2ef80 20 61 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65 64   an [unprotected
2ef90 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a   sqlite3_value].
2efa0 2a 2a 20 6f 62 6a 65 63 74 20 72 65 73 75 6c 74  ** object result
2efb0 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62  s in undefined b
2efc0 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e  ehavior..**.** ^
2efd0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77  These routines w
2efe0 6f 72 6b 20 6a 75 73 74 20 6c 69 6b 65 20 74 68  ork just like th
2eff0 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  e corresponding 
2f000 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66  [column access f
2f010 75 6e 63 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63  unctions].** exc
2f020 65 70 74 20 74 68 61 74 20 20 74 68 65 73 65 20  ept that  these 
2f030 72 6f 75 74 69 6e 65 73 20 74 61 6b 65 20 61 20  routines take a 
2f040 73 69 6e 67 6c 65 20 5b 70 72 6f 74 65 63 74 65  single [protecte
2f050 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
2f060 20 6f 62 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e 74   object.** point
2f070 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20  er instead of a 
2f080 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20  [sqlite3_stmt*] 
2f090 70 6f 69 6e 74 65 72 20 61 6e 64 20 61 6e 20 69  pointer and an i
2f0a0 6e 74 65 67 65 72 20 63 6f 6c 75 6d 6e 20 6e 75  nteger column nu
2f0b0 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  mber..**.** ^The
2f0c0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
2f0d0 65 78 74 31 36 28 29 20 69 6e 74 65 72 66 61 63  ext16() interfac
2f0e0 65 20 65 78 74 72 61 63 74 73 20 61 20 55 54 46  e extracts a UTF
2f0f0 2d 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69 6e  -16 string.** in
2f100 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65   the native byte
2f110 2d 6f 72 64 65 72 20 6f 66 20 74 68 65 20 68 6f  -order of the ho
2f120 73 74 20 6d 61 63 68 69 6e 65 2e 20 20 5e 54 68  st machine.  ^Th
2f130 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c  e.** sqlite3_val
2f140 75 65 5f 74 65 78 74 31 36 62 65 28 29 20 61 6e  ue_text16be() an
2f150 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  d sqlite3_value_
2f160 74 65 78 74 31 36 6c 65 28 29 20 69 6e 74 65 72  text16le() inter
2f170 66 61 63 65 73 0a 2a 2a 20 65 78 74 72 61 63 74  faces.** extract
2f180 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 73 20   UTF-16 strings 
2f190 61 73 20 62 69 67 2d 65 6e 64 69 61 6e 20 61 6e  as big-endian an
2f1a0 64 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20  d little-endian 
2f1b0 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a  respectively..**
2f1c0 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65  .** ^(The sqlite
2f1d0 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f  3_value_numeric_
2f1e0 74 79 70 65 28 29 20 69 6e 74 65 72 66 61 63 65  type() interface
2f1f0 20 61 74 74 65 6d 70 74 73 20 74 6f 20 61 70 70   attempts to app
2f200 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69 63 20 61 66  ly.** numeric af
2f210 66 69 6e 69 74 79 20 74 6f 20 74 68 65 20 76 61  finity to the va
2f220 6c 75 65 2e 20 20 54 68 69 73 20 6d 65 61 6e 73  lue.  This means
2f230 20 74 68 61 74 20 61 6e 20 61 74 74 65 6d 70 74   that an attempt
2f240 20 69 73 0a 2a 2a 20 6d 61 64 65 20 74 6f 20 63   is.** made to c
2f250 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75 65  onvert the value
2f260 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 6f   to an integer o
2f270 72 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  r floating point
2f280 2e 20 20 49 66 0a 2a 2a 20 73 75 63 68 20 61 20  .  If.** such a 
2f290 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 6f  conversion is po
2f2a0 73 73 69 62 6c 65 20 77 69 74 68 6f 75 74 20 6c  ssible without l
2f2b0 6f 73 73 20 6f 66 20 69 6e 66 6f 72 6d 61 74 69  oss of informati
2f2c0 6f 6e 20 28 69 6e 20 6f 74 68 65 72 0a 2a 2a 20  on (in other.** 
2f2d0 77 6f 72 64 73 2c 20 69 66 20 74 68 65 20 76 61  words, if the va
2f2e0 6c 75 65 20 69 73 20 61 20 73 74 72 69 6e 67 20  lue is a string 
2f2f0 74 68 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20  that looks like 
2f300 61 20 6e 75 6d 62 65 72 29 0a 2a 2a 20 74 68 65  a number).** the
2f310 6e 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e  n the conversion
2f320 20 69 73 20 70 65 72 66 6f 72 6d 65 64 2e 20 20   is performed.  
2f330 4f 74 68 65 72 77 69 73 65 20 6e 6f 20 63 6f 6e  Otherwise no con
2f340 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 2e 0a  version occurs..
2f350 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49  ** The [SQLITE_I
2f360 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70  NTEGER | datatyp
2f370 65 5d 20 61 66 74 65 72 20 63 6f 6e 76 65 72 73  e] after convers
2f380 69 6f 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ion is returned.
2f390 29 5e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65 20  )^.**.** Please 
2f3a0 70 61 79 20 70 61 72 74 69 63 75 6c 61 72 20 61  pay particular a
2f3b0 74 74 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65 20  ttention to the 
2f3c0 66 61 63 74 20 74 68 61 74 20 74 68 65 20 70 6f  fact that the po
2f3d0 69 6e 74 65 72 20 72 65 74 75 72 6e 65 64 0a 2a  inter returned.*
2f3e0 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  * from [sqlite3_
2f3f0 76 61 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b  value_blob()], [
2f400 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
2f410 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71  xt()], or.** [sq
2f420 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
2f430 31 36 28 29 5d 20 63 61 6e 20 62 65 20 69 6e 76  16()] can be inv
2f440 61 6c 69 64 61 74 65 64 20 62 79 20 61 20 73 75  alidated by a su
2f450 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f  bsequent call to
2f460 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  .** [sqlite3_val
2f470 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73 71  ue_bytes()], [sq
2f480 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
2f490 73 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  s16()], [sqlite3
2f4a0 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a  _value_text()],.
2f4b0 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76  ** or [sqlite3_v
2f4c0 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 2e 0a  alue_text16()]..
2f4d0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
2f4e0 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c  ines must be cal
2f4f0 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d  led from the sam
2f500 65 20 74 68 72 65 61 64 20 61 73 0a 2a 2a 20 74  e thread as.** t
2f510 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
2f520 74 68 61 74 20 73 75 70 70 6c 69 65 64 20 74 68  that supplied th
2f530 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
2f540 2a 5d 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a  *] parameters..*
2f550 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  /.SQLITE_API con
2f560 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
2f570 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 69  _value_blob(sqli
2f580 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c  te3_value*);.SQL
2f590 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
2f5a0 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28  te3_value_bytes(
2f5b0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
2f5c0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
2f5d0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
2f5e0 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f 76 61  tes16(sqlite3_va
2f5f0 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  lue*);.SQLITE_AP
2f600 49 20 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33  I double sqlite3
2f610 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73 71  _value_double(sq
2f620 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53  lite3_value*);.S
2f630 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
2f640 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28  lite3_value_int(
2f650 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
2f660 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69  .SQLITE_API sqli
2f670 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
2f680 33 5f 76 61 6c 75 65 5f 69 6e 74 36 34 28 73 71  3_value_int64(sq
2f690 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53  lite3_value*);.S
2f6a0 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
2f6b0 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73  unsigned char *s
2f6c0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
2f6d0 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t(sqlite3_value*
2f6e0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  );.SQLITE_API co
2f6f0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
2f700 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 73  3_value_text16(s
2f710 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
2f720 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
2f730 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76   void *sqlite3_v
2f740 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 73 71  alue_text16le(sq
2f750 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53  lite3_value*);.S
2f760 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
2f770 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61  void *sqlite3_va
2f780 6c 75 65 5f 74 65 78 74 31 36 62 65 28 73 71 6c  lue_text16be(sql
2f790 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51  ite3_value*);.SQ
2f7a0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
2f7b0 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28  ite3_value_type(
2f7c0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
2f7d0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
2f7e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75  sqlite3_value_nu
2f7f0 6d 65 72 69 63 5f 74 79 70 65 28 73 71 6c 69 74  meric_type(sqlit
2f800 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a  e3_value*);../*.
2f810 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74  ** CAPI3REF: Obt
2f820 61 69 6e 20 41 67 67 72 65 67 61 74 65 20 46 75  ain Aggregate Fu
2f830 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 0a 2a  nction Context.*
2f840 2a 0a 2a 2a 20 49 6d 70 6c 65 6d 65 6e 74 61 74  *.** Implementat
2f850 69 6f 6e 73 20 6f 66 20 61 67 67 72 65 67 61 74  ions of aggregat
2f860 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  e SQL functions 
2f870 75 73 65 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74  use this.** rout
2f880 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20  ine to allocate 
2f890 6d 65 6d 6f 72 79 20 66 6f 72 20 73 74 6f 72 69  memory for stori
2f8a0 6e 67 20 74 68 65 69 72 20 73 74 61 74 65 2e 0a  ng their state..
2f8b0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
2f8c0 20 74 69 6d 65 20 74 68 65 20 73 71 6c 69 74 65   time the sqlite
2f8d0 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
2f8e0 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65  ext(C,N) routine
2f8f0 20 69 73 20 63 61 6c 6c 65 64 20 0a 2a 2a 20 66   is called .** f
2f900 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  or a particular 
2f910 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69  aggregate functi
2f920 6f 6e 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6c  on, SQLite.** al
2f930 6c 6f 63 61 74 65 73 20 4e 20 6f 66 20 6d 65 6d  locates N of mem
2f940 6f 72 79 2c 20 7a 65 72 6f 65 73 20 6f 75 74 20  ory, zeroes out 
2f950 74 68 61 74 20 6d 65 6d 6f 72 79 2c 20 61 6e 64  that memory, and
2f960 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
2f970 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 6e 65 77  er.** to the new
2f980 20 6d 65 6d 6f 72 79 2e 20 5e 4f 6e 20 73 65 63   memory. ^On sec
2f990 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65  ond and subseque
2f9a0 6e 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73  nt calls to.** s
2f9b0 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
2f9c0 5f 63 6f 6e 74 65 78 74 28 29 20 66 6f 72 20 74  _context() for t
2f9d0 68 65 20 73 61 6d 65 20 61 67 67 72 65 67 61 74  he same aggregat
2f9e0 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61  e function insta
2f9f0 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 73 61 6d 65  nce,.** the same
2fa00 20 62 75 66 66 65 72 20 69 73 20 72 65 74 75 72   buffer is retur
2fa10 6e 65 64 2e 20 20 53 71 6c 69 74 65 33 5f 61 67  ned.  Sqlite3_ag
2fa20 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
2fa30 29 20 69 73 20 6e 6f 72 6d 61 6c 6c 79 0a 2a 2a  ) is normally.**
2fa40 20 63 61 6c 6c 65 64 20 6f 6e 63 65 20 66 6f 72   called once for
2fa50 20 65 61 63 68 20 69 6e 76 6f 63 61 74 69 6f 6e   each invocation
2fa60 20 6f 66 20 74 68 65 20 78 53 74 65 70 20 63 61   of the xStep ca
2fa70 6c 6c 62 61 63 6b 20 61 6e 64 20 74 68 65 6e 20  llback and then 
2fa80 6f 6e 65 0a 2a 2a 20 6c 61 73 74 20 74 69 6d 65  one.** last time
2fa90 20 77 68 65 6e 20 74 68 65 20 78 46 69 6e 61 6c   when the xFinal
2faa0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
2fab0 6f 6b 65 64 2e 20 20 5e 28 57 68 65 6e 20 6e 6f  oked.  ^(When no
2fac0 20 72 6f 77 73 20 6d 61 74 63 68 0a 2a 2a 20 61   rows match.** a
2fad0 6e 20 61 67 67 72 65 67 61 74 65 20 71 75 65 72  n aggregate quer
2fae0 79 2c 20 74 68 65 20 78 53 74 65 70 28 29 20 63  y, the xStep() c
2faf0 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 61  allback of the a
2fb00 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f  ggregate functio
2fb10 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  n.** implementat
2fb20 69 6f 6e 20 69 73 20 6e 65 76 65 72 20 63 61 6c  ion is never cal
2fb30 6c 65 64 20 61 6e 64 20 78 46 69 6e 61 6c 28 29  led and xFinal()
2fb40 20 69 73 20 63 61 6c 6c 65 64 20 65 78 61 63 74   is called exact
2fb50 6c 79 20 6f 6e 63 65 2e 0a 2a 2a 20 49 6e 20 74  ly once..** In t
2fb60 68 6f 73 65 20 63 61 73 65 73 2c 20 73 71 6c 69  hose cases, sqli
2fb70 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
2fb80 6e 74 65 78 74 28 29 20 6d 69 67 68 74 20 62 65  ntext() might be
2fb90 20 63 61 6c 6c 65 64 20 66 6f 72 20 74 68 65 0a   called for the.
2fba0 2a 2a 20 66 69 72 73 74 20 74 69 6d 65 20 66 72  ** first time fr
2fbb0 6f 6d 20 77 69 74 68 69 6e 20 78 46 69 6e 61 6c  om within xFinal
2fbc0 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ().)^.**.** ^The
2fbd0 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
2fbe0 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20  te_context(C,N) 
2fbf0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
2fc00 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  a NULL pointer i
2fc10 66 20 4e 20 69 73 0a 2a 2a 20 6c 65 73 73 20 74  f N is.** less t
2fc20 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20  han or equal to 
2fc30 7a 65 72 6f 20 6f 72 20 69 66 20 61 20 6d 65 6d  zero or if a mem
2fc40 6f 72 79 20 61 6c 6c 6f 63 61 74 65 20 65 72 72  ory allocate err
2fc50 6f 72 20 6f 63 63 75 72 73 2e 0a 2a 2a 0a 2a 2a  or occurs..**.**
2fc60 20 5e 28 54 68 65 20 61 6d 6f 75 6e 74 20 6f 66   ^(The amount of
2fc70 20 73 70 61 63 65 20 61 6c 6c 6f 63 61 74 65 64   space allocated
2fc80 20 62 79 20 73 71 6c 69 74 65 33 5f 61 67 67 72   by sqlite3_aggr
2fc90 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c  egate_context(C,
2fca0 4e 29 20 69 73 0a 2a 2a 20 64 65 74 65 72 6d 69  N) is.** determi
2fcb0 6e 65 64 20 62 79 20 74 68 65 20 4e 20 70 61 72  ned by the N par
2fcc0 61 6d 65 74 65 72 20 6f 6e 20 66 69 72 73 74 20  ameter on first 
2fcd0 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 2e  successful call.
2fce0 20 20 43 68 61 6e 67 69 6e 67 20 74 68 65 0a 2a    Changing the.*
2fcf0 2a 20 76 61 6c 75 65 20 6f 66 20 4e 20 69 6e 20  * value of N in 
2fd00 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20  subsequent call 
2fd10 74 6f 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  to sqlite3_aggre
2fd20 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 77  gate_context() w
2fd30 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20 73 61 6d  ithin.** the sam
2fd40 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63  e aggregate func
2fd50 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 20 77 69  tion instance wi
2fd60 6c 6c 20 6e 6f 74 20 72 65 73 69 7a 65 20 74 68  ll not resize th
2fd70 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f  e memory.** allo
2fd80 63 61 74 69 6f 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20  cation.)^.**.** 
2fd90 5e 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69  ^SQLite automati
2fda0 63 61 6c 6c 79 20 66 72 65 65 73 20 74 68 65 20  cally frees the 
2fdb0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65 64  memory allocated
2fdc0 20 62 79 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   by .** sqlite3_
2fdd0 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
2fde0 74 28 29 20 77 68 65 6e 20 74 68 65 20 61 67 67  t() when the agg
2fdf0 72 65 67 61 74 65 20 71 75 65 72 79 20 63 6f 6e  regate query con
2fe00 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  cludes..**.** Th
2fe10 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
2fe20 72 20 6d 75 73 74 20 62 65 20 61 20 63 6f 70 79  r must be a copy
2fe30 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   of the.** [sqli
2fe40 74 65 33 5f 63 6f 6e 74 65 78 74 20 7c 20 53 51  te3_context | SQ
2fe50 4c 20 66 75 6e 63 74 69 6f 6e 20 63 6f 6e 74 65  L function conte
2fe60 78 74 5d 20 74 68 61 74 20 69 73 20 74 68 65 20  xt] that is the 
2fe70 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 0a  first parameter.
2fe80 2a 2a 20 74 6f 20 74 68 65 20 78 53 74 65 70 20  ** to the xStep 
2fe90 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61  or xFinal callba
2fea0 63 6b 20 72 6f 75 74 69 6e 65 20 74 68 61 74 20  ck routine that 
2feb0 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 61  implements the a
2fec0 67 67 72 65 67 61 74 65 0a 2a 2a 20 66 75 6e 63  ggregate.** func
2fed0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  tion..**.** This
2fee0 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65   routine must be
2fef0 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65   called from the
2ff00 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20   same thread in 
2ff10 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 67 67  which.** the agg
2ff20 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74  regate SQL funct
2ff30 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  ion is running..
2ff40 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  */.SQLITE_API vo
2ff50 69 64 20 2a 73 71 6c 69 74 65 33 5f 61 67 67 72  id *sqlite3_aggr
2ff60 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 73 71  egate_context(sq
2ff70 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
2ff80 69 6e 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a  int nBytes);../*
2ff90 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 55 73  .** CAPI3REF: Us
2ffa0 65 72 20 44 61 74 61 20 46 6f 72 20 46 75 6e 63  er Data For Func
2ffb0 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  tions.**.** ^The
2ffc0 20 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61   sqlite3_user_da
2ffd0 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  ta() interface r
2ffe0 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66  eturns a copy of
2fff0 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20  .** the pointer 
30000 74 68 61 74 20 77 61 73 20 74 68 65 20 70 55 73  that was the pUs
30010 65 72 44 61 74 61 20 70 61 72 61 6d 65 74 65 72  erData parameter
30020 20 28 74 68 65 20 35 74 68 20 70 61 72 61 6d 65   (the 5th parame
30030 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  ter).** of the [
30040 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
30050 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e  unction()].** an
30060 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  d [sqlite3_creat
30070 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20  e_function16()] 
30080 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72  routines that or
30090 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69  iginally.** regi
300a0 73 74 65 72 65 64 20 74 68 65 20 61 70 70 6c 69  stered the appli
300b0 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66  cation defined f
300c0 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54  unction..**.** T
300d0 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74  his routine must
300e0 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20   be called from 
300f0 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20  the same thread 
30100 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20  in which.** the 
30110 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
30120 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  ned function is 
30130 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49  running..*/.SQLI
30140 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c  TE_API void *sql
30150 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 73  ite3_user_data(s
30160 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
30170 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
30180 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e  F: Database Conn
30190 65 63 74 69 6f 6e 20 46 6f 72 20 46 75 6e 63 74  ection For Funct
301a0 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ions.**.** ^The 
301b0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f  sqlite3_context_
301c0 64 62 5f 68 61 6e 64 6c 65 28 29 20 69 6e 74 65  db_handle() inte
301d0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
301e0 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70  copy of.** the p
301f0 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 64  ointer to the [d
30200 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
30210 6f 6e 5d 20 28 74 68 65 20 31 73 74 20 70 61 72  on] (the 1st par
30220 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68  ameter).** of th
30230 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  e [sqlite3_creat
30240 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a  e_function()].**
30250 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72   and [sqlite3_cr
30260 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
30270 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74  )] routines that
30280 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72   originally.** r
30290 65 67 69 73 74 65 72 65 64 20 74 68 65 20 61 70  egistered the ap
302a0 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65  plication define
302b0 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2f 0a 53  d function..*/.S
302c0 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65  QLITE_API sqlite
302d0 33 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  3 *sqlite3_conte
302e0 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c  xt_db_handle(sql
302f0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a  ite3_context*);.
30300 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
30310 20 46 75 6e 63 74 69 6f 6e 20 41 75 78 69 6c 69   Function Auxili
30320 61 72 79 20 44 61 74 61 0a 2a 2a 0a 2a 2a 20 54  ary Data.**.** T
30330 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 77 6f  he following two
30340 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62   functions may b
30350 65 20 75 73 65 64 20 62 79 20 73 63 61 6c 61 72  e used by scalar
30360 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 74   SQL functions t
30370 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 20 6d  o.** associate m
30380 65 74 61 64 61 74 61 20 77 69 74 68 20 61 72 67  etadata with arg
30390 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e 20 49 66  ument values. If
303a0 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65 20   the same value 
303b0 69 73 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20  is passed to.** 
303c0 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f 63 61 74  multiple invocat
303d0 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65  ions of the same
303e0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 64 75   SQL function du
303f0 72 69 6e 67 20 71 75 65 72 79 20 65 78 65 63 75  ring query execu
30400 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a 20 73  tion, under.** s
30410 6f 6d 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65  ome circumstance
30420 73 20 74 68 65 20 61 73 73 6f 63 69 61 74 65 64  s the associated
30430 20 6d 65 74 61 64 61 74 61 20 6d 61 79 20 62 65   metadata may be
30440 20 70 72 65 73 65 72 76 65 64 2e 20 54 68 69 73   preserved. This
30450 20 6d 61 79 0a 2a 2a 20 62 65 20 75 73 65 64 2c   may.** be used,
30460 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 74 6f   for example, to
30470 20 61 64 64 20 61 20 72 65 67 75 6c 61 72 2d 65   add a regular-e
30480 78 70 72 65 73 73 69 6f 6e 20 6d 61 74 63 68 69  xpression matchi
30490 6e 67 20 73 63 61 6c 61 72 0a 2a 2a 20 66 75 6e  ng scalar.** fun
304a0 63 74 69 6f 6e 2e 20 54 68 65 20 63 6f 6d 70 69  ction. The compi
304b0 6c 65 64 20 76 65 72 73 69 6f 6e 20 6f 66 20 74  led version of t
304c0 68 65 20 72 65 67 75 6c 61 72 20 65 78 70 72 65  he regular expre
304d0 73 73 69 6f 6e 20 69 73 20 73 74 6f 72 65 64 20  ssion is stored 
304e0 61 73 0a 2a 2a 20 6d 65 74 61 64 61 74 61 20 61  as.** metadata a
304f0 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
30500 68 65 20 53 51 4c 20 76 61 6c 75 65 20 70 61 73  he SQL value pas
30510 73 65 64 20 61 73 20 74 68 65 20 72 65 67 75 6c  sed as the regul
30520 61 72 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a  ar expression.**
30530 20 70 61 74 74 65 72 6e 2e 20 20 54 68 65 20 63   pattern.  The c
30540 6f 6d 70 69 6c 65 64 20 72 65 67 75 6c 61 72 20  ompiled regular 
30550 65 78 70 72 65 73 73 69 6f 6e 20 63 61 6e 20 62  expression can b
30560 65 20 72 65 75 73 65 64 20 6f 6e 20 6d 75 6c 74  e reused on mult
30570 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69  iple.** invocati
30580 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ons of the same 
30590 66 75 6e 63 74 69 6f 6e 20 73 6f 20 74 68 61 74  function so that
305a0 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 70 61   the original pa
305b0 74 74 65 72 6e 20 73 74 72 69 6e 67 0a 2a 2a 20  ttern string.** 
305c0 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f  does not need to
305d0 20 62 65 20 72 65 63 6f 6d 70 69 6c 65 64 20 6f   be recompiled o
305e0 6e 20 65 61 63 68 20 69 6e 76 6f 63 61 74 69 6f  n each invocatio
305f0 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  n..**.** ^The sq
30600 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74  lite3_get_auxdat
30610 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  a() interface re
30620 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
30630 74 6f 20 74 68 65 20 6d 65 74 61 64 61 74 61 0a  to the metadata.
30640 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 62 79  ** associated by
30650 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74   the sqlite3_set
30660 5f 61 75 78 64 61 74 61 28 29 20 66 75 6e 63 74  _auxdata() funct
30670 69 6f 6e 20 77 69 74 68 20 74 68 65 20 4e 74 68  ion with the Nth
30680 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 61 6c   argument.** val
30690 75 65 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63  ue to the applic
306a0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
306b0 6e 63 74 69 6f 6e 2e 20 5e 49 66 20 6e 6f 20 6d  nction. ^If no m
306c0 65 74 61 64 61 74 61 20 68 61 73 20 62 65 65 6e  etadata has been
306d0 20 65 76 65 72 0a 2a 2a 20 62 65 65 6e 20 73 65   ever.** been se
306e0 74 20 66 6f 72 20 74 68 65 20 4e 74 68 20 61 72  t for the Nth ar
306f0 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 66 75  gument of the fu
30700 6e 63 74 69 6f 6e 2c 20 6f 72 20 69 66 20 74 68  nction, or if th
30710 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a  e corresponding.
30720 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61  ** function para
30730 6d 65 74 65 72 20 68 61 73 20 63 68 61 6e 67 65  meter has change
30740 64 20 73 69 6e 63 65 20 74 68 65 20 6d 65 74 61  d since the meta
30750 2d 64 61 74 61 20 77 61 73 20 73 65 74 2c 0a 2a  -data was set,.*
30760 2a 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 67  * then sqlite3_g
30770 65 74 5f 61 75 78 64 61 74 61 28 29 20 72 65 74  et_auxdata() ret
30780 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  urns a NULL poin
30790 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ter..**.** ^The 
307a0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
307b0 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20  ata() interface 
307c0 73 61 76 65 73 20 74 68 65 20 6d 65 74 61 64 61  saves the metada
307d0 74 61 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f  ta.** pointed to
307e0 20 62 79 20 69 74 73 20 33 72 64 20 70 61 72 61   by its 3rd para
307f0 6d 65 74 65 72 20 61 73 20 74 68 65 20 6d 65 74  meter as the met
30800 61 64 61 74 61 20 66 6f 72 20 74 68 65 20 4e 2d  adata for the N-
30810 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6f  th.** argument o
30820 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  f the applicatio
30830 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
30840 6f 6e 2e 20 20 53 75 62 73 65 71 75 65 6e 74 0a  on.  Subsequent.
30850 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  ** calls to sqli
30860 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28  te3_get_auxdata(
30870 29 20 6d 69 67 68 74 20 72 65 74 75 72 6e 20 74  ) might return t
30880 68 69 73 20 64 61 74 61 2c 20 69 66 20 69 74 20  his data, if it 
30890 68 61 73 0a 2a 2a 20 6e 6f 74 20 62 65 65 6e 20  has.** not been 
308a0 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 20 5e 49  destroyed..** ^I
308b0 66 20 69 74 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  f it is not NULL
308c0 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e  , SQLite will in
308d0 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72 75 63  voke the destruc
308e0 74 6f 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  tor.** function 
308f0 67 69 76 65 6e 20 62 79 20 74 68 65 20 34 74 68  given by the 4th
30900 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
30910 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
30920 61 28 29 20 6f 6e 0a 2a 2a 20 74 68 65 20 6d 65  a() on.** the me
30930 74 61 64 61 74 61 20 77 68 65 6e 20 74 68 65 20  tadata when the 
30940 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 66 75  corresponding fu
30950 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72  nction parameter
30960 20 63 68 61 6e 67 65 73 0a 2a 2a 20 6f 72 20 77   changes.** or w
30970 68 65 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74  hen the SQL stat
30980 65 6d 65 6e 74 20 63 6f 6d 70 6c 65 74 65 73 2c  ement completes,
30990 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65 73   whichever comes
309a0 20 66 69 72 73 74 2e 0a 2a 2a 0a 2a 2a 20 53 51   first..**.** SQ
309b0 4c 69 74 65 20 69 73 20 66 72 65 65 20 74 6f 20  Lite is free to 
309c0 63 61 6c 6c 20 74 68 65 20 64 65 73 74 72 75 63  call the destruc
309d0 74 6f 72 20 61 6e 64 20 64 72 6f 70 20 6d 65 74  tor and drop met
309e0 61 64 61 74 61 20 6f 6e 20 61 6e 79 0a 2a 2a 20  adata on any.** 
309f0 70 61 72 61 6d 65 74 65 72 20 6f 66 20 61 6e 79  parameter of any
30a00 20 66 75 6e 63 74 69 6f 6e 20 61 74 20 61 6e 79   function at any
30a10 20 74 69 6d 65 2e 20 20 5e 54 68 65 20 6f 6e 6c   time.  ^The onl
30a20 79 20 67 75 61 72 61 6e 74 65 65 20 69 73 20 74  y guarantee is t
30a30 68 61 74 0a 2a 2a 20 74 68 65 20 64 65 73 74 72  hat.** the destr
30a40 75 63 74 6f 72 20 77 69 6c 6c 20 62 65 20 63 61  uctor will be ca
30a50 6c 6c 65 64 20 62 65 66 6f 72 65 20 74 68 65 20  lled before the 
30a60 6d 65 74 61 64 61 74 61 20 69 73 20 64 72 6f 70  metadata is drop
30a70 70 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20  ped..**.** ^(In 
30a80 70 72 61 63 74 69 63 65 2c 20 6d 65 74 61 64 61  practice, metada
30a90 74 61 20 69 73 20 70 72 65 73 65 72 76 65 64 20  ta is preserved 
30aa0 62 65 74 77 65 65 6e 20 66 75 6e 63 74 69 6f 6e  between function
30ab0 20 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20 65 78   calls for.** ex
30ac0 70 72 65 73 73 69 6f 6e 73 20 74 68 61 74 20 61  pressions that a
30ad0 72 65 20 63 6f 6e 73 74 61 6e 74 20 61 74 20 63  re constant at c
30ae0 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 54 68 69  ompile time. Thi
30af0 73 20 69 6e 63 6c 75 64 65 73 20 6c 69 74 65 72  s includes liter
30b00 61 6c 0a 2a 2a 20 76 61 6c 75 65 73 20 61 6e 64  al.** values and
30b10 20 5b 70 61 72 61 6d 65 74 65 72 73 5d 2e 29 5e   [parameters].)^
30b20 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
30b30 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61  tines must be ca
30b40 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61  lled from the sa
30b50 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69  me thread in whi
30b60 63 68 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75  ch.** the SQL fu
30b70 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e  nction is runnin
30b80 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  g..*/.SQLITE_API
30b90 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 67   void *sqlite3_g
30ba0 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74  et_auxdata(sqlit
30bb0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74  e3_context*, int
30bc0 20 4e 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20   N);.SQLITE_API 
30bd0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 65 74  void sqlite3_set
30be0 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74 65 33  _auxdata(sqlite3
30bf0 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e  _context*, int N
30c00 2c 20 76 6f 69 64 2a 2c 20 76 6f 69 64 20 28 2a  , void*, void (*
30c10 29 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a  )(void*));.../*.
30c20 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
30c30 73 74 61 6e 74 73 20 44 65 66 69 6e 69 6e 67 20  stants Defining 
30c40 53 70 65 63 69 61 6c 20 44 65 73 74 72 75 63 74  Special Destruct
30c50 6f 72 20 42 65 68 61 76 69 6f 72 0a 2a 2a 0a 2a  or Behavior.**.*
30c60 2a 20 54 68 65 73 65 20 61 72 65 20 73 70 65 63  * These are spec
30c70 69 61 6c 20 76 61 6c 75 65 73 20 66 6f 72 20 74  ial values for t
30c80 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 74 68  he destructor th
30c90 61 74 20 69 73 20 70 61 73 73 65 64 20 69 6e 20  at is passed in 
30ca0 61 73 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20  as the.** final 
30cb0 61 72 67 75 6d 65 6e 74 20 74 6f 20 72 6f 75 74  argument to rout
30cc0 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74  ines like [sqlit
30cd0 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29  e3_result_blob()
30ce0 5d 2e 20 20 5e 49 66 20 74 68 65 20 64 65 73 74  ].  ^If the dest
30cf0 72 75 63 74 6f 72 0a 2a 2a 20 61 72 67 75 6d 65  ructor.** argume
30d00 6e 74 20 69 73 20 53 51 4c 49 54 45 5f 53 54 41  nt is SQLITE_STA
30d10 54 49 43 2c 20 69 74 20 6d 65 61 6e 73 20 74 68  TIC, it means th
30d20 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 70  at the content p
30d30 6f 69 6e 74 65 72 20 69 73 20 63 6f 6e 73 74 61  ointer is consta
30d40 6e 74 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c 20 6e  nt.** and will n
30d50 65 76 65 72 20 63 68 61 6e 67 65 2e 20 20 49 74  ever change.  It
30d60 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74   does not need t
30d70 6f 20 62 65 20 64 65 73 74 72 6f 79 65 64 2e 20  o be destroyed. 
30d80 20 5e 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f   ^The.** SQLITE_
30d90 54 52 41 4e 53 49 45 4e 54 20 76 61 6c 75 65 20  TRANSIENT value 
30da0 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 63  means that the c
30db0 6f 6e 74 65 6e 74 20 77 69 6c 6c 20 6c 69 6b 65  ontent will like
30dc0 6c 79 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20  ly change in.** 
30dd0 74 68 65 20 6e 65 61 72 20 66 75 74 75 72 65 20  the near future 
30de0 61 6e 64 20 74 68 61 74 20 53 51 4c 69 74 65 20  and that SQLite 
30df0 73 68 6f 75 6c 64 20 6d 61 6b 65 20 69 74 73 20  should make its 
30e00 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79  own private copy
30e10 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65   of.** the conte
30e20 6e 74 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e  nt before return
30e30 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  ing..**.** The t
30e40 79 70 65 64 65 66 20 69 73 20 6e 65 63 65 73 73  ypedef is necess
30e50 61 72 79 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75  ary to work arou
30e60 6e 64 20 70 72 6f 62 6c 65 6d 73 20 69 6e 20 63  nd problems in c
30e70 65 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f  ertain.** C++ co
30e80 6d 70 69 6c 65 72 73 2e 20 20 53 65 65 20 74 69  mpilers.  See ti
30e90 63 6b 65 74 20 23 32 31 39 31 2e 0a 2a 2f 0a 74  cket #2191..*/.t
30ea0 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71  ypedef void (*sq
30eb0 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72  lite3_destructor
30ec0 5f 74 79 70 65 29 28 76 6f 69 64 2a 29 3b 0a 23  _type)(void*);.#
30ed0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54  define SQLITE_ST
30ee0 41 54 49 43 20 20 20 20 20 20 28 28 73 71 6c 69  ATIC      ((sqli
30ef0 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74  te3_destructor_t
30f00 79 70 65 29 30 29 0a 23 64 65 66 69 6e 65 20 53  ype)0).#define S
30f10 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20  QLITE_TRANSIENT 
30f20 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74    ((sqlite3_dest
30f30 72 75 63 74 6f 72 5f 74 79 70 65 29 2d 31 29 0a  ructor_type)-1).
30f40 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
30f50 20 53 65 74 74 69 6e 67 20 54 68 65 20 52 65 73   Setting The Res
30f60 75 6c 74 20 4f 66 20 41 6e 20 53 51 4c 20 46 75  ult Of An SQL Fu
30f70 6e 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68 65  nction.**.** The
30f80 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
30f90 75 73 65 64 20 62 79 20 74 68 65 20 78 46 75 6e  used by the xFun
30fa0 63 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c  c or xFinal call
30fb0 62 61 63 6b 73 20 74 68 61 74 0a 2a 2a 20 69 6d  backs that.** im
30fc0 70 6c 65 6d 65 6e 74 20 53 51 4c 20 66 75 6e 63  plement SQL func
30fd0 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67  tions and aggreg
30fe0 61 74 65 73 2e 20 20 53 65 65 0a 2a 2a 20 5b 73  ates.  See.** [s
30ff0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
31000 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73  nction()] and [s
31010 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
31020 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 66  nction16()].** f
31030 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e  or additional in
31040 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  formation..**.**
31050 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   These functions
31060 20 77 6f 72 6b 20 76 65 72 79 20 6d 75 63 68 20   work very much 
31070 6c 69 6b 65 20 74 68 65 20 5b 70 61 72 61 6d 65  like the [parame
31080 74 65 72 20 62 69 6e 64 69 6e 67 5d 20 66 61 6d  ter binding] fam
31090 69 6c 79 20 6f 66 0a 2a 2a 20 66 75 6e 63 74 69  ily of.** functi
310a0 6f 6e 73 20 75 73 65 64 20 74 6f 20 62 69 6e 64  ons used to bind
310b0 20 76 61 6c 75 65 73 20 74 6f 20 68 6f 73 74 20   values to host 
310c0 70 61 72 61 6d 65 74 65 72 73 20 69 6e 20 70 72  parameters in pr
310d0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
310e0 73 2e 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 74  s..** Refer to t
310f0 68 65 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65  he [SQL paramete
31100 72 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  r] documentation
31110 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
31120 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
31130 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
31140 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 20 69 6e  result_blob() in
31150 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
31160 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20   result from.** 
31170 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  an application-d
31180 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
31190 74 6f 20 62 65 20 74 68 65 20 42 4c 4f 42 20 77  to be the BLOB w
311a0 68 6f 73 65 20 63 6f 6e 74 65 6e 74 20 69 73 20  hose content is 
311b0 70 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f 20 62 79  pointed.** to by
311c0 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
311d0 6d 65 74 65 72 20 61 6e 64 20 77 68 69 63 68 20  meter and which 
311e0 69 73 20 4e 20 62 79 74 65 73 20 6c 6f 6e 67 20  is N bytes long 
311f0 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a  where N is the.*
31200 2a 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  * third paramete
31210 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  r..**.** ^The sq
31220 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72  lite3_result_zer
31230 6f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 63  oblob() interfac
31240 65 73 20 73 65 74 20 74 68 65 20 72 65 73 75 6c  es set the resul
31250 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c  t of.** the appl
31260 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
31270 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  function to be a
31280 20 42 4c 4f 42 20 63 6f 6e 74 61 69 6e 69 6e 67   BLOB containing
31290 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a 20 62 79 74   all zero.** byt
312a0 65 73 20 61 6e 64 20 4e 20 62 79 74 65 73 20 69  es and N bytes i
312b0 6e 20 73 69 7a 65 2c 20 77 68 65 72 65 20 4e 20  n size, where N 
312c0 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  is the value of 
312d0 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
312e0 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  r..**.** ^The sq
312f0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75  lite3_result_dou
31300 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  ble() interface 
31310 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20  sets the result 
31320 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69  from.** an appli
31330 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
31340 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20  unction to be a 
31350 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76  floating point v
31360 61 6c 75 65 20 73 70 65 63 69 66 69 65 64 0a 2a  alue specified.*
31370 2a 20 62 79 20 69 74 73 20 32 6e 64 20 61 72 67  * by its 2nd arg
31380 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ument..**.** ^Th
31390 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
313a0 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c  _error() and sql
313b0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
313c0 72 31 36 28 29 20 66 75 6e 63 74 69 6f 6e 73 0a  r16() functions.
313d0 2a 2a 20 63 61 75 73 65 20 74 68 65 20 69 6d 70  ** cause the imp
313e0 6c 65 6d 65 6e 74 65 64 20 53 51 4c 20 66 75 6e  lemented SQL fun
313f0 63 74 69 6f 6e 20 74 6f 20 74 68 72 6f 77 20 61  ction to throw a
31400 6e 20 65 78 63 65 70 74 69 6f 6e 2e 0a 2a 2a 20  n exception..** 
31410 5e 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65  ^SQLite uses the
31420 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 64 20   string pointed 
31430 74 6f 20 62 79 20 74 68 65 0a 2a 2a 20 32 6e 64  to by the.** 2nd
31440 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 73 71   parameter of sq
31450 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
31460 6f 72 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  or() or sqlite3_
31470 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
31480 0a 2a 2a 20 61 73 20 74 68 65 20 74 65 78 74 20  .** as the text 
31490 6f 66 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73  of an error mess
314a0 61 67 65 2e 20 20 5e 53 51 4c 69 74 65 20 69 6e  age.  ^SQLite in
314b0 74 65 72 70 72 65 74 73 20 74 68 65 20 65 72 72  terprets the err
314c0 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 73 74  or.** message st
314d0 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65  ring from sqlite
314e0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
314f0 20 61 73 20 55 54 46 2d 38 2e 20 5e 53 51 4c 69   as UTF-8. ^SQLi
31500 74 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 73  te.** interprets
31510 20 74 68 65 20 73 74 72 69 6e 67 20 66 72 6f 6d   the string from
31520 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
31530 65 72 72 6f 72 31 36 28 29 20 61 73 20 55 54 46  error16() as UTF
31540 2d 31 36 20 69 6e 20 6e 61 74 69 76 65 0a 2a 2a  -16 in native.**
31550 20 62 79 74 65 20 6f 72 64 65 72 2e 20 20 5e 49   byte order.  ^I
31560 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  f the third para
31570 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
31580 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a  _result_error().
31590 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  ** or sqlite3_re
315a0 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69  sult_error16() i
315b0 73 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20  s negative then 
315c0 53 51 4c 69 74 65 20 74 61 6b 65 73 20 61 73 20  SQLite takes as 
315d0 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73  the error.** mes
315e0 73 61 67 65 20 61 6c 6c 20 74 65 78 74 20 75 70  sage all text up
315f0 20 74 68 72 6f 75 67 68 20 74 68 65 20 66 69 72   through the fir
31600 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65  st zero characte
31610 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74 68  r..** ^If the th
31620 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
31630 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
31640 65 72 72 6f 72 28 29 20 6f 72 0a 2a 2a 20 73 71  error() or.** sq
31650 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
31660 6f 72 31 36 28 29 20 69 73 20 6e 6f 6e 2d 6e 65  or16() is non-ne
31670 67 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69  gative then SQLi
31680 74 65 20 74 61 6b 65 73 20 74 68 61 74 20 6d 61  te takes that ma
31690 6e 79 0a 2a 2a 20 62 79 74 65 73 20 28 6e 6f 74  ny.** bytes (not
316a0 20 63 68 61 72 61 63 74 65 72 73 29 20 66 72 6f   characters) fro
316b0 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  m the 2nd parame
316c0 74 65 72 20 61 73 20 74 68 65 20 65 72 72 6f 72  ter as the error
316d0 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 20 5e 54 68   message..** ^Th
316e0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
316f0 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c  _error() and sql
31700 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
31710 72 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  r16().** routine
31720 73 20 6d 61 6b 65 20 61 20 70 72 69 76 61 74 65  s make a private
31730 20 63 6f 70 79 20 6f 66 20 74 68 65 20 65 72 72   copy of the err
31740 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78 74 20  or message text 
31750 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 79 20 72  before.** they r
31760 65 74 75 72 6e 2e 20 20 48 65 6e 63 65 2c 20 74  eturn.  Hence, t
31770 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74  he calling funct
31780 69 6f 6e 20 63 61 6e 20 64 65 61 6c 6c 6f 63 61  ion can dealloca
31790 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66 79 20  te or.** modify 
317a0 74 68 65 20 74 65 78 74 20 61 66 74 65 72 20 74  the text after t
317b0 68 65 79 20 72 65 74 75 72 6e 20 77 69 74 68 6f  hey return witho
317c0 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 54 68 65  ut harm..** ^The
317d0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
317e0 65 72 72 6f 72 5f 63 6f 64 65 28 29 20 66 75 6e  error_code() fun
317f0 63 74 69 6f 6e 20 63 68 61 6e 67 65 73 20 74 68  ction changes th
31800 65 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20  e error code.** 
31810 72 65 74 75 72 6e 65 64 20 62 79 20 53 51 4c 69  returned by SQLi
31820 74 65 20 61 73 20 61 20 72 65 73 75 6c 74 20 6f  te as a result o
31830 66 20 61 6e 20 65 72 72 6f 72 20 69 6e 20 61 20  f an error in a 
31840 66 75 6e 63 74 69 6f 6e 2e 20 20 5e 42 79 20 64  function.  ^By d
31850 65 66 61 75 6c 74 2c 0a 2a 2a 20 74 68 65 20 65  efault,.** the e
31860 72 72 6f 72 20 63 6f 64 65 20 69 73 20 53 51 4c  rror code is SQL
31870 49 54 45 5f 45 52 52 4f 52 2e 20 20 5e 41 20 73  ITE_ERROR.  ^A s
31880 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74  ubsequent call t
31890 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  o sqlite3_result
318a0 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73  _error().** or s
318b0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
318c0 72 6f 72 31 36 28 29 20 72 65 73 65 74 73 20 74  ror16() resets t
318d0 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 74 6f  he error code to
318e0 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 0a 2a   SQLITE_ERROR..*
318f0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
31900 33 5f 72 65 73 75 6c 74 5f 74 6f 6f 62 69 67 28  3_result_toobig(
31910 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73  ) interface caus
31920 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72  es SQLite to thr
31930 6f 77 20 61 6e 20 65 72 72 6f 72 0a 2a 2a 20 69  ow an error.** i
31940 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 20 61  ndicating that a
31950 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20   string or BLOB 
31960 69 73 20 74 6f 6f 20 6c 6f 6e 67 20 74 6f 20 72  is too long to r
31970 65 70 72 65 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  epresent..**.** 
31980 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
31990 75 6c 74 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74 65  ult_nomem() inte
319a0 72 66 61 63 65 20 63 61 75 73 65 73 20 53 51 4c  rface causes SQL
319b0 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 20  ite to throw an 
319c0 65 72 72 6f 72 0a 2a 2a 20 69 6e 64 69 63 61 74  error.** indicat
319d0 69 6e 67 20 74 68 61 74 20 61 20 6d 65 6d 6f 72  ing that a memor
319e0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69  y allocation fai
319f0 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  led..**.** ^The 
31a00 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69  sqlite3_result_i
31a10 6e 74 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  nt() interface s
31a20 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76  ets the return v
31a30 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61  alue.** of the a
31a40 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
31a50 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
31a60 65 20 74 68 65 20 33 32 2d 62 69 74 20 73 69 67  e the 32-bit sig
31a70 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76  ned integer.** v
31a80 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68  alue given in th
31a90 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a  e 2nd argument..
31aa0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
31ab0 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 29 20 69  result_int64() i
31ac0 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68  nterface sets th
31ad0 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a  e return value.*
31ae0 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  * of the applica
31af0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
31b00 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20  ction to be the 
31b10 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e  64-bit signed in
31b20 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67  teger.** value g
31b30 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20  iven in the 2nd 
31b40 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
31b50 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
31b60 75 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e 74 65 72  ult_null() inter
31b70 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65  face sets the re
31b80 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66  turn value.** of
31b90 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
31ba0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
31bb0 6e 20 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a  n to be NULL..**
31bc0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
31bd0 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 29 2c 20  _result_text(), 
31be0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
31bf0 65 78 74 31 36 28 29 2c 0a 2a 2a 20 73 71 6c 69  ext16(),.** sqli
31c00 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
31c10 36 6c 65 28 29 2c 20 61 6e 64 20 73 71 6c 69 74  6le(), and sqlit
31c20 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
31c30 62 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a  be() interfaces.
31c40 2a 2a 20 73 65 74 20 74 68 65 20 72 65 74 75 72  ** set the retur
31c50 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 61  n value of the a
31c60 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
31c70 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
31c80 65 0a 2a 2a 20 61 20 74 65 78 74 20 73 74 72 69  e.** a text stri
31c90 6e 67 20 77 68 69 63 68 20 69 73 20 72 65 70 72  ng which is repr
31ca0 65 73 65 6e 74 65 64 20 61 73 20 55 54 46 2d 38  esented as UTF-8
31cb0 2c 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20  , UTF-16 native 
31cc0 62 79 74 65 20 6f 72 64 65 72 2c 0a 2a 2a 20 55  byte order,.** U
31cd0 54 46 2d 31 36 20 6c 69 74 74 6c 65 20 65 6e 64  TF-16 little end
31ce0 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20 62  ian, or UTF-16 b
31cf0 69 67 20 65 6e 64 69 61 6e 2c 20 72 65 73 70 65  ig endian, respe
31d00 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 53 51 4c  ctively..** ^SQL
31d10 69 74 65 20 74 61 6b 65 73 20 74 68 65 20 74 65  ite takes the te
31d20 78 74 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 74  xt result from t
31d30 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 66  he application f
31d40 72 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e 64 20 70  rom.** the 2nd p
31d50 61 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65 20  arameter of the 
31d60 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
31d70 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 2e  ext* interfaces.
31d80 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33 72 64 20  .** ^If the 3rd 
31d90 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
31da0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
31db0 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
31dc0 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c  .** is negative,
31dd0 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b   then SQLite tak
31de0 65 73 20 72 65 73 75 6c 74 20 74 65 78 74 20 66  es result text f
31df0 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61  rom the 2nd para
31e00 6d 65 74 65 72 0a 2a 2a 20 74 68 72 6f 75 67 68  meter.** through
31e10 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20   the first zero 
31e20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e 49  character..** ^I
31e30 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65  f the 3rd parame
31e40 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
31e50 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
31e60 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73  interfaces.** is
31e70 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74   non-negative, t
31e80 68 65 6e 20 61 73 20 6d 61 6e 79 20 62 79 74 65  hen as many byte
31e90 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72  s (not character
31ea0 73 29 20 6f 66 20 74 68 65 20 74 65 78 74 0a 2a  s) of the text.*
31eb0 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20  * pointed to by 
31ec0 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
31ed0 72 20 61 72 65 20 74 61 6b 65 6e 20 61 73 20 74  r are taken as t
31ee0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
31ef0 65 66 69 6e 65 64 0a 2a 2a 20 66 75 6e 63 74 69  efined.** functi
31f00 6f 6e 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49  on result..** ^I
31f10 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65  f the 4th parame
31f20 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
31f30 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
31f40 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72  interfaces.** or
31f50 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
31f60 62 6c 6f 62 20 69 73 20 61 20 6e 6f 6e 2d 4e 55  blob is a non-NU
31f70 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e  LL pointer, then
31f80 20 53 51 4c 69 74 65 20 63 61 6c 6c 73 20 74 68   SQLite calls th
31f90 61 74 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 61  at.** function a
31fa0 73 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  s the destructor
31fb0 20 6f 6e 20 74 68 65 20 74 65 78 74 20 6f 72 20   on the text or 
31fc0 42 4c 4f 42 20 72 65 73 75 6c 74 20 77 68 65 6e  BLOB result when
31fd0 20 69 74 20 68 61 73 0a 2a 2a 20 66 69 6e 69 73   it has.** finis
31fe0 68 65 64 20 75 73 69 6e 67 20 74 68 61 74 20 72  hed using that r
31ff0 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68  esult..** ^If th
32000 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 4th parameter 
32010 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72  to the sqlite3_r
32020 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65  esult_text* inte
32030 72 66 61 63 65 73 20 6f 72 20 74 6f 0a 2a 2a 20  rfaces or to.** 
32040 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
32050 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65 63 69  lob is the speci
32060 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49  al constant SQLI
32070 54 45 5f 53 54 41 54 49 43 2c 20 74 68 65 6e 20  TE_STATIC, then 
32080 53 51 4c 69 74 65 0a 2a 2a 20 61 73 73 75 6d 65  SQLite.** assume
32090 73 20 74 68 61 74 20 74 68 65 20 74 65 78 74 20  s that the text 
320a0 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 20 69  or BLOB result i
320b0 73 20 69 6e 20 63 6f 6e 73 74 61 6e 74 20 73 70  s in constant sp
320c0 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74  ace and does not
320d0 0a 2a 2a 20 63 6f 70 79 20 74 68 65 20 63 6f 6e  .** copy the con
320e0 74 65 6e 74 20 6f 66 20 74 68 65 20 70 61 72 61  tent of the para
320f0 6d 65 74 65 72 20 6e 6f 72 20 63 61 6c 6c 20 61  meter nor call a
32100 20 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 74   destructor on t
32110 68 65 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 77 68  he content.** wh
32120 65 6e 20 69 74 20 68 61 73 20 66 69 6e 69 73 68  en it has finish
32130 65 64 20 75 73 69 6e 67 20 74 68 61 74 20 72 65  ed using that re
32140 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  sult..** ^If the
32150 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   4th parameter t
32160 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65  o the sqlite3_re
32170 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72  sult_text* inter
32180 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69  faces.** or sqli
32190 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20  te3_result_blob 
321a0 69 73 20 74 68 65 20 73 70 65 63 69 61 6c 20 63  is the special c
321b0 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 54  onstant SQLITE_T
321c0 52 41 4e 53 49 45 4e 54 0a 2a 2a 20 74 68 65 6e  RANSIENT.** then
321d0 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20   SQLite makes a 
321e0 63 6f 70 79 20 6f 66 20 74 68 65 20 72 65 73 75  copy of the resu
321f0 6c 74 20 69 6e 74 6f 20 73 70 61 63 65 20 6f 62  lt into space ob
32200 74 61 69 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 66  tained from.** f
32210 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
32220 6c 6f 63 28 29 5d 20 62 65 66 6f 72 65 20 69 74  loc()] before it
32230 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20   returns..**.** 
32240 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
32250 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65  ult_value() inte
32260 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72  rface sets the r
32270 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20  esult of.** the 
32280 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
32290 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
322a0 62 65 20 61 20 63 6f 70 79 20 74 68 65 0a 2a 2a  be a copy the.**
322b0 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   [unprotected sq
322c0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
322d0 65 63 74 20 73 70 65 63 69 66 69 65 64 20 62 79  ect specified by
322e0 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
322f0 65 72 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c  er.  ^The.** sql
32300 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
32310 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d 61  e() interface ma
32320 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68  kes a copy of th
32330 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
32340 5d 0a 2a 2a 20 73 6f 20 74 68 61 74 20 74 68 65  ].** so that the
32350 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
32360 20 73 70 65 63 69 66 69 65 64 20 69 6e 20 74 68   specified in th
32370 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  e parameter may 
32380 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 62 65 20  change or.** be 
32390 64 65 61 6c 6c 6f 63 61 74 65 64 20 61 66 74 65  deallocated afte
323a0 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  r sqlite3_result
323b0 5f 76 61 6c 75 65 28 29 20 72 65 74 75 72 6e 73  _value() returns
323c0 20 77 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a   without harm..*
323d0 2a 20 5e 41 20 5b 70 72 6f 74 65 63 74 65 64 20  * ^A [protected 
323e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
323f0 62 6a 65 63 74 20 6d 61 79 20 61 6c 77 61 79 73  bject may always
32400 20 62 65 20 75 73 65 64 20 77 68 65 72 65 20 61   be used where a
32410 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65  n.** [unprotecte
32420 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
32430 20 6f 62 6a 65 63 74 20 69 73 20 72 65 71 75 69   object is requi
32440 72 65 64 2c 20 73 6f 20 65 69 74 68 65 72 0a 2a  red, so either.*
32450 2a 20 6b 69 6e 64 20 6f 66 20 5b 73 71 6c 69 74  * kind of [sqlit
32460 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
32470 20 63 61 6e 20 62 65 20 75 73 65 64 20 77 69 74   can be used wit
32480 68 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  h this interface
32490 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 73 65  ..**.** If these
324a0 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61   routines are ca
324b0 6c 6c 65 64 20 66 72 6f 6d 20 77 69 74 68 69 6e  lled from within
324c0 20 74 68 65 20 64 69 66 66 65 72 65 6e 74 20 74   the different t
324d0 68 72 65 61 64 0a 2a 2a 20 74 68 61 6e 20 74 68  hread.** than th
324e0 65 20 6f 6e 65 20 63 6f 6e 74 61 69 6e 69 6e 67  e one containing
324f0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
32500 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
32510 6e 20 74 68 61 74 20 72 65 63 65 69 76 65 64 0a  n that received.
32520 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** the [sqlite3_
32530 63 6f 6e 74 65 78 74 5d 20 70 6f 69 6e 74 65 72  context] pointer
32540 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  , the results ar
32550 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a  e undefined..*/.
32560 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
32570 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
32580 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  lob(sqlite3_cont
32590 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64  ext*, const void
325a0 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28  *, int, void(*)(
325b0 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f  void*));.SQLITE_
325c0 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33  API void sqlite3
325d0 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 73  _result_double(s
325e0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
325f0 20 64 6f 75 62 6c 65 29 3b 0a 53 51 4c 49 54 45   double);.SQLITE
32600 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65  _API void sqlite
32610 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 73  3_result_error(s
32620 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
32630 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e   const char*, in
32640 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  t);.SQLITE_API v
32650 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
32660 6c 74 5f 65 72 72 6f 72 31 36 28 73 71 6c 69 74  lt_error16(sqlit
32670 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
32680 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a  st void*, int);.
32690 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
326a0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
326b0 72 72 6f 72 5f 74 6f 6f 62 69 67 28 73 71 6c 69  rror_toobig(sqli
326c0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53  te3_context*);.S
326d0 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73  QLITE_API void s
326e0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
326f0 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c 69 74 65  ror_nomem(sqlite
32700 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 4c  3_context*);.SQL
32710 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c  ITE_API void sql
32720 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
32730 72 5f 63 6f 64 65 28 73 71 6c 69 74 65 33 5f 63  r_code(sqlite3_c
32740 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 53  ontext*, int);.S
32750 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73  QLITE_API void s
32760 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e  qlite3_result_in
32770 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t(sqlite3_contex
32780 74 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45  t*, int);.SQLITE
32790 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65  _API void sqlite
327a0 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 73  3_result_int64(s
327b0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
327c0 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b   sqlite3_int64);
327d0 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
327e0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
327f0 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 63 6f 6e  null(sqlite3_con
32800 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41  text*);.SQLITE_A
32810 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  PI void sqlite3_
32820 72 65 73 75 6c 74 5f 74 65 78 74 28 73 71 6c 69  result_text(sqli
32830 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f  te3_context*, co
32840 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 2c 20  nst char*, int, 
32850 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
32860 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
32870 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
32880 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 63  text16(sqlite3_c
32890 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76  ontext*, const v
328a0 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28  oid*, int, void(
328b0 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49  *)(void*));.SQLI
328c0 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69  TE_API void sqli
328d0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
328e0 36 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  6le(sqlite3_cont
328f0 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64  ext*, const void
32900 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76  *, int,void(*)(v
32910 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41  oid*));.SQLITE_A
32920 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  PI void sqlite3_
32930 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28  result_text16be(
32940 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
32950 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
32960 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  nt,void(*)(void*
32970 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  ));.SQLITE_API v
32980 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
32990 6c 74 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33  lt_value(sqlite3
329a0 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74  _context*, sqlit
329b0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49  e3_value*);.SQLI
329c0 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69  TE_API void sqli
329d0 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62  te3_result_zerob
329e0 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  lob(sqlite3_cont
329f0 65 78 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f  ext*, int n);../
32a00 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
32a10 65 66 69 6e 65 20 4e 65 77 20 43 6f 6c 6c 61 74  efine New Collat
32a20 69 6e 67 20 53 65 71 75 65 6e 63 65 73 0a 2a 2a  ing Sequences.**
32a30 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74  .** ^These funct
32a40 69 6f 6e 73 20 61 64 64 2c 20 72 65 6d 6f 76 65  ions add, remove
32a50 2c 20 6f 72 20 6d 6f 64 69 66 79 20 61 20 5b 63  , or modify a [c
32a60 6f 6c 6c 61 74 69 6f 6e 5d 20 61 73 73 6f 63 69  ollation] associ
32a70 61 74 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65  ated.** with the
32a80 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
32a90 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64  ction] specified
32aa0 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72   as the first ar
32ab0 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54  gument..**.** ^T
32ac0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63  he name of the c
32ad0 6f 6c 6c 61 74 69 6f 6e 20 69 73 20 61 20 55 54  ollation is a UT
32ae0 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 66 6f  F-8 string.** fo
32af0 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  r sqlite3_create
32b00 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 61 6e 64  _collation() and
32b10 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
32b20 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 0a 2a  collation_v2().*
32b30 2a 20 61 6e 64 20 61 20 55 54 46 2d 31 36 20 73  * and a UTF-16 s
32b40 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20  tring in native 
32b50 62 79 74 65 20 6f 72 64 65 72 20 66 6f 72 20 73  byte order for s
32b60 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
32b70 6c 6c 61 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a 20  llation16()..** 
32b80 5e 43 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65 73  ^Collation names
32b90 20 74 68 61 74 20 63 6f 6d 70 61 72 65 20 65 71   that compare eq
32ba0 75 61 6c 20 61 63 63 6f 72 64 69 6e 67 20 74 6f  ual according to
32bb0 20 5b 73 71 6c 69 74 65 33 5f 73 74 72 6e 69 63   [sqlite3_strnic
32bc0 6d 70 28 29 5d 20 61 72 65 0a 2a 2a 20 63 6f 6e  mp()] are.** con
32bd0 73 69 64 65 72 65 64 20 74 6f 20 62 65 20 74 68  sidered to be th
32be0 65 20 73 61 6d 65 20 6e 61 6d 65 2e 0a 2a 2a 0a  e same name..**.
32bf0 2a 2a 20 5e 28 54 68 65 20 74 68 69 72 64 20 61  ** ^(The third a
32c00 72 67 75 6d 65 6e 74 20 28 65 54 65 78 74 52 65  rgument (eTextRe
32c10 70 29 20 6d 75 73 74 20 62 65 20 6f 6e 65 20 6f  p) must be one o
32c20 66 20 74 68 65 20 63 6f 6e 73 74 61 6e 74 73 3a  f the constants:
32c30 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
32c40 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 0a   [SQLITE_UTF8],.
32c50 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
32c60 55 54 46 31 36 4c 45 5d 2c 0a 2a 2a 20 3c 6c 69  UTF16LE],.** <li
32c70 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42  > [SQLITE_UTF16B
32c80 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  E],.** <li> [SQL
32c90 49 54 45 5f 55 54 46 31 36 5d 2c 20 6f 72 0a 2a  ITE_UTF16], or.*
32ca0 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55  * <li> [SQLITE_U
32cb0 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 2e 0a 2a  TF16_ALIGNED]..*
32cc0 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 54 68  * </ul>)^.** ^Th
32cd0 65 20 65 54 65 78 74 52 65 70 20 61 72 67 75 6d  e eTextRep argum
32ce0 65 6e 74 20 64 65 74 65 72 6d 69 6e 65 73 20 74  ent determines t
32cf0 68 65 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20 73  he encoding of s
32d00 74 72 69 6e 67 73 20 70 61 73 73 65 64 0a 2a 2a  trings passed.**
32d10 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e   to the collatin
32d20 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62  g function callb
32d30 61 63 6b 2c 20 78 43 61 6c 6c 62 61 63 6b 2e 0a  ack, xCallback..
32d40 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
32d50 55 54 46 31 36 5d 20 61 6e 64 20 5b 53 51 4c 49  UTF16] and [SQLI
32d60 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44  TE_UTF16_ALIGNED
32d70 5d 20 76 61 6c 75 65 73 20 66 6f 72 20 65 54 65  ] values for eTe
32d80 78 74 52 65 70 0a 2a 2a 20 66 6f 72 63 65 20 73  xtRep.** force s
32d90 74 72 69 6e 67 73 20 74 6f 20 62 65 20 55 54 46  trings to be UTF
32da0 31 36 20 77 69 74 68 20 6e 61 74 69 76 65 20 62  16 with native b
32db0 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 20 5e 54  yte order..** ^T
32dc0 68 65 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  he [SQLITE_UTF16
32dd0 5f 41 4c 49 47 4e 45 44 5d 20 76 61 6c 75 65 20  _ALIGNED] value 
32de0 66 6f 72 20 65 54 65 78 74 52 65 70 20 66 6f 72  for eTextRep for
32df0 63 65 73 20 73 74 72 69 6e 67 73 20 74 6f 20 62  ces strings to b
32e00 65 67 69 6e 0a 2a 2a 20 6f 6e 20 61 6e 20 65 76  egin.** on an ev
32e10 65 6e 20 62 79 74 65 20 61 64 64 72 65 73 73 2e  en byte address.
32e20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72  .**.** ^The four
32e30 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 70 41 72  th argument, pAr
32e40 67 2c 20 69 73 20 61 6e 20 61 70 70 6c 69 63 61  g, is an applica
32e50 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65  tion data pointe
32e60 72 20 74 68 61 74 20 69 73 20 70 61 73 73 65 64  r that is passed
32e70 0a 2a 2a 20 74 68 72 6f 75 67 68 20 61 73 20 74  .** through as t
32e80 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
32e90 74 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69  t to the collati
32ea0 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c  ng function call
32eb0 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  back..**.** ^The
32ec0 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 2c   fifth argument,
32ed0 20 78 43 61 6c 6c 62 61 63 6b 2c 20 69 73 20 61   xCallback, is a
32ee0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
32ef0 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
32f00 6f 6e 2e 0a 2a 2a 20 5e 4d 75 6c 74 69 70 6c 65  on..** ^Multiple
32f10 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
32f20 69 6f 6e 73 20 63 61 6e 20 62 65 20 72 65 67 69  ions can be regi
32f30 73 74 65 72 65 64 20 75 73 69 6e 67 20 74 68 65  stered using the
32f40 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 0a 2a   same name but.*
32f50 2a 20 77 69 74 68 20 64 69 66 66 65 72 65 6e 74  * with different
32f60 20 65 54 65 78 74 52 65 70 20 70 61 72 61 6d 65   eTextRep parame
32f70 74 65 72 73 20 61 6e 64 20 53 51 4c 69 74 65 20  ters and SQLite 
32f80 77 69 6c 6c 20 75 73 65 20 77 68 69 63 68 65 76  will use whichev
32f90 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72  er.** function r
32fa0 65 71 75 69 72 65 73 20 74 68 65 20 6c 65 61 73  equires the leas
32fb0 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61  t amount of data
32fc0 20 74 72 61 6e 73 66 6f 72 6d 61 74 69 6f 6e 2e   transformation.
32fd0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 78 43 61 6c  .** ^If the xCal
32fe0 6c 62 61 63 6b 20 61 72 67 75 6d 65 6e 74 20 69  lback argument i
32ff0 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20  s NULL then the 
33000 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
33010 6f 6e 20 69 73 0a 2a 2a 20 64 65 6c 65 74 65 64  on is.** deleted
33020 2e 20 20 5e 57 68 65 6e 20 61 6c 6c 20 63 6f 6c  .  ^When all col
33030 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73  lating functions
33040 20 68 61 76 69 6e 67 20 74 68 65 20 73 61 6d 65   having the same
33050 20 6e 61 6d 65 20 61 72 65 20 64 65 6c 65 74 65   name are delete
33060 64 2c 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 6c 61  d,.** that colla
33070 74 69 6f 6e 20 69 73 20 6e 6f 20 6c 6f 6e 67 65  tion is no longe
33080 72 20 75 73 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20  r usable..**.** 
33090 5e 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66  ^The collating f
330a0 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b  unction callback
330b0 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68   is invoked with
330c0 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 70   a copy of the p
330d0 41 72 67 20 0a 2a 2a 20 61 70 70 6c 69 63 61 74  Arg .** applicat
330e0 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72  ion data pointer
330f0 20 61 6e 64 20 77 69 74 68 20 74 77 6f 20 73 74   and with two st
33100 72 69 6e 67 73 20 69 6e 20 74 68 65 20 65 6e 63  rings in the enc
33110 6f 64 69 6e 67 20 73 70 65 63 69 66 69 65 64 0a  oding specified.
33120 2a 2a 20 62 79 20 74 68 65 20 65 54 65 78 74 52  ** by the eTextR
33130 65 70 20 61 72 67 75 6d 65 6e 74 2e 20 20 54 68  ep argument.  Th
33140 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  e collating func
33150 74 69 6f 6e 20 6d 75 73 74 20 72 65 74 75 72 6e  tion must return
33160 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 74   an.** integer t
33170 68 61 74 20 69 73 20 6e 65 67 61 74 69 76 65 2c  hat is negative,
33180 20 7a 65 72 6f 2c 20 6f 72 20 70 6f 73 69 74 69   zero, or positi
33190 76 65 0a 2a 2a 20 69 66 20 74 68 65 20 66 69 72  ve.** if the fir
331a0 73 74 20 73 74 72 69 6e 67 20 69 73 20 6c 65 73  st string is les
331b0 73 20 74 68 61 6e 2c 20 65 71 75 61 6c 20 74 6f  s than, equal to
331c0 2c 20 6f 72 20 67 72 65 61 74 65 72 20 74 68 61  , or greater tha
331d0 6e 20 74 68 65 20 73 65 63 6f 6e 64 2c 0a 2a 2a  n the second,.**
331e0 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20 20   respectively.  
331f0 41 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  A collating func
33200 74 69 6f 6e 20 6d 75 73 74 20 61 6c 77 61 79 73  tion must always
33210 20 72 65 74 75 72 6e 20 74 68 65 20 73 61 6d 65   return the same
33220 20 61 6e 73 77 65 72 0a 2a 2a 20 67 69 76 65 6e   answer.** given
33230 20 74 68 65 20 73 61 6d 65 20 69 6e 70 75 74 73   the same inputs
33240 2e 20 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72  .  If two or mor
33250 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  e collating func
33260 74 69 6f 6e 73 20 61 72 65 20 72 65 67 69 73 74  tions are regist
33270 65 72 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20 73  ered.** to the s
33280 61 6d 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 6e 61  ame collation na
33290 6d 65 20 28 75 73 69 6e 67 20 64 69 66 66 65 72  me (using differ
332a0 65 6e 74 20 65 54 65 78 74 52 65 70 20 76 61 6c  ent eTextRep val
332b0 75 65 73 29 20 74 68 65 6e 20 61 6c 6c 0a 2a 2a  ues) then all.**
332c0 20 6d 75 73 74 20 67 69 76 65 20 61 6e 20 65 71   must give an eq
332d0 75 69 76 61 6c 65 6e 74 20 61 6e 73 77 65 72 20  uivalent answer 
332e0 77 68 65 6e 20 69 6e 76 6f 6b 65 64 20 77 69 74  when invoked wit
332f0 68 20 65 71 75 69 76 61 6c 65 6e 74 20 73 74 72  h equivalent str
33300 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 20 63 6f 6c  ings..** The col
33310 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  lating function 
33320 6d 75 73 74 20 6f 62 65 79 20 74 68 65 20 66 6f  must obey the fo
33330 6c 6c 6f 77 69 6e 67 20 70 72 6f 70 65 72 74 69  llowing properti
33340 65 73 20 66 6f 72 20 61 6c 6c 0a 2a 2a 20 73 74  es for all.** st
33350 72 69 6e 67 73 20 41 2c 20 42 2c 20 61 6e 64 20  rings A, B, and 
33360 43 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a  C:.**.** <ol>.**
33370 20 3c 6c 69 3e 20 49 66 20 41 3d 3d 42 20 74 68   <li> If A==B th
33380 65 6e 20 42 3d 3d 41 2e 0a 2a 2a 20 3c 6c 69 3e  en B==A..** <li>
33390 20 49 66 20 41 3d 3d 42 20 61 6e 64 20 42 3d 3d   If A==B and B==
333a0 43 20 74 68 65 6e 20 41 3d 3d 43 2e 0a 2a 2a 20  C then A==C..** 
333b0 3c 6c 69 3e 20 49 66 20 41 26 6c 74 3b 42 20 54  <li> If A&lt;B T
333c0 48 45 4e 20 42 26 67 74 3b 41 2e 0a 2a 2a 20 3c  HEN B&gt;A..** <
333d0 6c 69 3e 20 49 66 20 41 26 6c 74 3b 42 20 61 6e  li> If A&lt;B an
333e0 64 20 42 26 6c 74 3b 43 20 74 68 65 6e 20 41 26  d B&lt;C then A&
333f0 6c 74 3b 43 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a  lt;C..** </ol>.*
33400 2a 0a 2a 2a 20 49 66 20 61 20 63 6f 6c 6c 61 74  *.** If a collat
33410 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 66 61 69  ing function fai
33420 6c 73 20 61 6e 79 20 6f 66 20 74 68 65 20 61 62  ls any of the ab
33430 6f 76 65 20 63 6f 6e 73 74 72 61 69 6e 74 73 20  ove constraints 
33440 61 6e 64 20 74 68 61 74 0a 2a 2a 20 63 6f 6c 6c  and that.** coll
33450 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69  ating function i
33460 73 20 20 72 65 67 69 73 74 65 72 65 64 20 61 6e  s  registered an
33470 64 20 75 73 65 64 2c 20 74 68 65 6e 20 74 68 65  d used, then the
33480 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c   behavior of SQL
33490 69 74 65 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69  ite.** is undefi
334a0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ned..**.** ^The 
334b0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
334c0 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77 6f  ollation_v2() wo
334d0 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33  rks like sqlite3
334e0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
334f0 6e 28 29 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  n().** with the 
33500 61 64 64 69 74 69 6f 6e 20 74 68 61 74 20 74 68  addition that th
33510 65 20 78 44 65 73 74 72 6f 79 20 63 61 6c 6c 62  e xDestroy callb
33520 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f  ack is invoked o
33530 6e 20 70 41 72 67 20 77 68 65 6e 0a 2a 2a 20 74  n pArg when.** t
33540 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  he collating fun
33550 63 74 69 6f 6e 20 69 73 20 64 65 6c 65 74 65 64  ction is deleted
33560 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6e 67 20  ..** ^Collating 
33570 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 64 65  functions are de
33580 6c 65 74 65 64 20 77 68 65 6e 20 74 68 65 79 20  leted when they 
33590 61 72 65 20 6f 76 65 72 72 69 64 64 65 6e 20 62  are overridden b
335a0 79 20 6c 61 74 65 72 0a 2a 2a 20 63 61 6c 6c 73  y later.** calls
335b0 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f   to the collatio
335c0 6e 20 63 72 65 61 74 69 6f 6e 20 66 75 6e 63 74  n creation funct
335d0 69 6f 6e 73 20 6f 72 20 77 68 65 6e 20 74 68 65  ions or when the
335e0 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
335f0 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 63 6c 6f  nnection] is clo
33600 73 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  sed using [sqlit
33610 65 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a  e3_close()]..**.
33620 2a 2a 20 5e 54 68 65 20 78 44 65 73 74 72 6f 79  ** ^The xDestroy
33630 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 3c 75 3e   callback is <u>
33640 6e 6f 74 3c 2f 75 3e 20 63 61 6c 6c 65 64 20 69  not</u> called i
33650 66 20 74 68 65 20 0a 2a 2a 20 73 71 6c 69 74 65  f the .** sqlite
33660 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
33670 6f 6e 5f 76 32 28 29 20 66 75 6e 63 74 69 6f 6e  on_v2() function
33680 20 66 61 69 6c 73 2e 20 20 41 70 70 6c 69 63 61   fails.  Applica
33690 74 69 6f 6e 73 20 74 68 61 74 20 69 6e 76 6f 6b  tions that invok
336a0 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65  e.** sqlite3_cre
336b0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
336c0 28 29 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55  () with a non-NU
336d0 4c 4c 20 78 44 65 73 74 72 6f 79 20 61 72 67 75  LL xDestroy argu
336e0 6d 65 6e 74 20 73 68 6f 75 6c 64 20 0a 2a 2a 20  ment should .** 
336f0 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e  check the return
33700 20 63 6f 64 65 20 61 6e 64 20 64 69 73 70 6f 73   code and dispos
33710 65 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  e of the applica
33720 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65  tion data pointe
33730 72 0a 2a 2a 20 74 68 65 6d 73 65 6c 76 65 73 20  r.** themselves 
33740 72 61 74 68 65 72 20 74 68 61 6e 20 65 78 70 65  rather than expe
33750 63 74 69 6e 67 20 53 51 4c 69 74 65 20 74 6f 20  cting SQLite to 
33760 64 65 61 6c 20 77 69 74 68 20 69 74 20 66 6f 72  deal with it for
33770 20 74 68 65 6d 2e 0a 2a 2a 20 54 68 69 73 20 69   them..** This i
33780 73 20 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d  s different from
33790 20 65 76 65 72 79 20 6f 74 68 65 72 20 53 51 4c   every other SQL
337a0 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20  ite interface.  
337b0 54 68 65 20 69 6e 63 6f 6e 73 69 73 74 65 6e 63  The inconsistenc
337c0 79 20 0a 2a 2a 20 69 73 20 75 6e 66 6f 72 74 75  y .** is unfortu
337d0 6e 61 74 65 20 62 75 74 20 63 61 6e 6e 6f 74 20  nate but cannot 
337e0 62 65 20 63 68 61 6e 67 65 64 20 77 69 74 68 6f  be changed witho
337f0 75 74 20 62 72 65 61 6b 69 6e 67 20 62 61 63 6b  ut breaking back
33800 77 61 72 64 73 20 0a 2a 2a 20 63 6f 6d 70 61 74  wards .** compat
33810 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 53  ibility..**.** S
33820 65 65 20 61 6c 73 6f 3a 20 20 5b 73 71 6c 69 74  ee also:  [sqlit
33830 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
33840 64 65 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ded()] and [sqli
33850 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
33860 65 64 65 64 31 36 28 29 5d 2e 0a 2a 2f 0a 53 51  eded16()]..*/.SQ
33870 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
33880 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
33890 61 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33  ation(.  sqlite3
338a0 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  *, .  const char
338b0 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20   *zName, .  int 
338c0 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69  eTextRep, .  voi
338d0 64 20 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a  d *pArg,.  int(*
338e0 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c  xCompare)(void*,
338f0 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  int,const void*,
33900 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29  int,const void*)
33910 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .);.SQLITE_API i
33920 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
33930 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 0a  e_collation_v2(.
33940 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63    sqlite3*, .  c
33950 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
33960 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65  , .  int eTextRe
33970 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41 72 67  p, .  void *pArg
33980 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72  ,.  int(*xCompar
33990 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  e)(void*,int,con
339a0 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  st void*,int,con
339b0 73 74 20 76 6f 69 64 2a 29 2c 0a 20 20 76 6f 69  st void*),.  voi
339c0 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69  d(*xDestroy)(voi
339d0 64 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  d*).);.SQLITE_AP
339e0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72  I int sqlite3_cr
339f0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36  eate_collation16
33a00 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20  (.  sqlite3*, . 
33a10 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 4e 61   const void *zNa
33a20 6d 65 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52  me,.  int eTextR
33a30 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41 72  ep, .  void *pAr
33a40 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61  g,.  int(*xCompa
33a50 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  re)(void*,int,co
33a60 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  nst void*,int,co
33a70 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f  nst void*).);../
33a80 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
33a90 6f 6c 6c 61 74 69 6f 6e 20 4e 65 65 64 65 64 20  ollation Needed 
33aa0 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20  Callbacks.**.** 
33ab0 5e 54 6f 20 61 76 6f 69 64 20 68 61 76 69 6e 67  ^To avoid having
33ac0 20 74 6f 20 72 65 67 69 73 74 65 72 20 61 6c 6c   to register all
33ad0 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   collation seque
33ae0 6e 63 65 73 20 62 65 66 6f 72 65 20 61 20 64 61  nces before a da
33af0 74 61 62 61 73 65 0a 2a 2a 20 63 61 6e 20 62 65  tabase.** can be
33b00 20 75 73 65 64 2c 20 61 20 73 69 6e 67 6c 65 20   used, a single 
33b10 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
33b20 6e 20 6d 61 79 20 62 65 20 72 65 67 69 73 74 65  n may be registe
33b30 72 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  red with the.** 
33b40 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
33b50 74 69 6f 6e 5d 20 74 6f 20 62 65 20 69 6e 76 6f  tion] to be invo
33b60 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 6e 20  ked whenever an 
33b70 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74  undefined collat
33b80 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20  ion.** sequence 
33b90 69 73 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a  is required..**.
33ba0 2a 2a 20 5e 49 66 20 74 68 65 20 66 75 6e 63 74  ** ^If the funct
33bb0 69 6f 6e 20 69 73 20 72 65 67 69 73 74 65 72 65  ion is registere
33bc0 64 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69  d using the sqli
33bd0 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
33be0 65 64 65 64 28 29 20 41 50 49 2c 0a 2a 2a 20 74  eded() API,.** t
33bf0 68 65 6e 20 69 74 20 69 73 20 70 61 73 73 65 64  hen it is passed
33c00 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 75 6e   the names of un
33c10 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f  defined collatio
33c20 6e 20 73 65 71 75 65 6e 63 65 73 20 61 73 20 73  n sequences as s
33c30 74 72 69 6e 67 73 0a 2a 2a 20 65 6e 63 6f 64 65  trings.** encode
33c40 64 20 69 6e 20 55 54 46 2d 38 2e 20 5e 49 66 20  d in UTF-8. ^If 
33c50 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
33c60 6e 5f 6e 65 65 64 65 64 31 36 28 29 20 69 73 20  n_needed16() is 
33c70 75 73 65 64 2c 0a 2a 2a 20 74 68 65 20 6e 61 6d  used,.** the nam
33c80 65 73 20 61 72 65 20 70 61 73 73 65 64 20 61 73  es are passed as
33c90 20 55 54 46 2d 31 36 20 69 6e 20 6d 61 63 68 69   UTF-16 in machi
33ca0 6e 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  ne native byte o
33cb0 72 64 65 72 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c  rder..** ^A call
33cc0 20 74 6f 20 65 69 74 68 65 72 20 66 75 6e 63 74   to either funct
33cd0 69 6f 6e 20 72 65 70 6c 61 63 65 73 20 74 68 65  ion replaces the
33ce0 20 65 78 69 73 74 69 6e 67 20 63 6f 6c 6c 61 74   existing collat
33cf0 69 6f 6e 2d 6e 65 65 64 65 64 20 63 61 6c 6c 62  ion-needed callb
33d00 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 28 57 68 65  ack..**.** ^(Whe
33d10 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  n the callback i
33d20 73 20 69 6e 76 6f 6b 65 64 2c 20 74 68 65 20 66  s invoked, the f
33d30 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 70 61  irst argument pa
33d40 73 73 65 64 20 69 73 20 61 20 63 6f 70 79 0a 2a  ssed is a copy.*
33d50 2a 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20  * of the second 
33d60 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
33d70 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
33d80 65 64 65 64 28 29 20 6f 72 0a 2a 2a 20 73 71 6c  eded() or.** sql
33d90 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
33da0 65 65 64 65 64 31 36 28 29 2e 20 20 54 68 65 20  eeded16().  The 
33db0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
33dc0 69 73 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  is the database.
33dd0 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20  ** connection.  
33de0 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  The third argume
33df0 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51  nt is one of [SQ
33e00 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c  LITE_UTF8], [SQL
33e10 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a  ITE_UTF16BE],.**
33e20 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31   or [SQLITE_UTF1
33e30 36 4c 45 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67  6LE], indicating
33e40 20 74 68 65 20 6d 6f 73 74 20 64 65 73 69 72 61   the most desira
33e50 62 6c 65 20 66 6f 72 6d 20 6f 66 20 74 68 65 20  ble form of the 
33e60 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71  collation.** seq
33e70 75 65 6e 63 65 20 66 75 6e 63 74 69 6f 6e 20 72  uence function r
33e80 65 71 75 69 72 65 64 2e 20 20 54 68 65 20 66 6f  equired.  The fo
33e90 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  urth parameter i
33ea0 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
33eb0 65 0a 2a 2a 20 72 65 71 75 69 72 65 64 20 63 6f  e.** required co
33ec0 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
33ed0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61  .)^.**.** The ca
33ee0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
33ef0 73 68 6f 75 6c 64 20 72 65 67 69 73 74 65 72 20  should register 
33f00 74 68 65 20 64 65 73 69 72 65 64 20 63 6f 6c 6c  the desired coll
33f10 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b  ation using.** [
33f20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
33f30 6f 6c 6c 61 74 69 6f 6e 28 29 5d 2c 20 5b 73 71  ollation()], [sq
33f40 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
33f50 6c 61 74 69 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a  lation16()], or.
33f60 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  ** [sqlite3_crea
33f70 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
33f80 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  )]..*/.SQLITE_AP
33f90 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  I int sqlite3_co
33fa0 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 0a  llation_needed(.
33fb0 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76    sqlite3*, .  v
33fc0 6f 69 64 2a 2c 20 0a 20 20 76 6f 69 64 28 2a 29  oid*, .  void(*)
33fd0 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c  (void*,sqlite3*,
33fe0 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63 6f 6e  int eTextRep,con
33ff0 73 74 20 63 68 61 72 2a 29 0a 29 3b 0a 53 51 4c  st char*).);.SQL
34000 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
34010 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
34020 65 64 65 64 31 36 28 0a 20 20 73 71 6c 69 74 65  eded16(.  sqlite
34030 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20  3*, .  void*,.  
34040 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71  void(*)(void*,sq
34050 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74  lite3*,int eText
34060 52 65 70 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29  Rep,const void*)
34070 0a 29 3b 0a 0a 23 69 66 64 65 66 20 53 51 4c 49  .);..#ifdef SQLI
34080 54 45 5f 48 41 53 5f 43 4f 44 45 43 0a 2f 2a 0a  TE_HAS_CODEC./*.
34090 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65 20 6b  ** Specify the k
340a0 65 79 20 66 6f 72 20 61 6e 20 65 6e 63 72 79 70  ey for an encryp
340b0 74 65 64 20 64 61 74 61 62 61 73 65 2e 20 20 54  ted database.  T
340c0 68 69 73 20 72 6f 75 74 69 6e 65 20 73 68 6f 75  his routine shou
340d0 6c 64 20 62 65 0a 2a 2a 20 63 61 6c 6c 65 64 20  ld be.** called 
340e0 72 69 67 68 74 20 61 66 74 65 72 20 73 71 6c 69  right after sqli
340f0 74 65 33 5f 6f 70 65 6e 28 29 2e 0a 2a 2a 0a 2a  te3_open()..**.*
34100 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d  * The code to im
34110 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49  plement this API
34120 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c   is not availabl
34130 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20  e in the public 
34140 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51  release.** of SQ
34150 4c 69 74 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  Lite..*/.SQLITE_
34160 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
34170 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  key(.  sqlite3 *
34180 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  db,             
34190 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
341a0 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20  e to be rekeyed 
341b0 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
341c0 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20  *pKey, int nKey 
341d0 20 20 20 20 2f 2a 20 54 68 65 20 6b 65 79 20 2a      /* The key *
341e0 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 68 61 6e  /.);../*.** Chan
341f0 67 65 20 74 68 65 20 6b 65 79 20 6f 6e 20 61 6e  ge the key on an
34200 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 2e 20   open database. 
34210 20 49 66 20 74 68 65 20 63 75 72 72 65 6e 74 20   If the current 
34220 64 61 74 61 62 61 73 65 20 69 73 20 6e 6f 74 0a  database is not.
34230 2a 2a 20 65 6e 63 72 79 70 74 65 64 2c 20 74 68  ** encrypted, th
34240 69 73 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20  is routine will 
34250 65 6e 63 72 79 70 74 20 69 74 2e 20 20 49 66 20  encrypt it.  If 
34260 70 4e 65 77 3d 3d 30 20 6f 72 20 6e 4e 65 77 3d  pNew==0 or nNew=
34270 3d 30 2c 20 74 68 65 0a 2a 2a 20 64 61 74 61 62  =0, the.** datab
34280 61 73 65 20 69 73 20 64 65 63 72 79 70 74 65 64  ase is decrypted
34290 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65  ..**.** The code
342a0 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68   to implement th
342b0 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76  is API is not av
342c0 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70  ailable in the p
342d0 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a  ublic release.**
342e0 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 53   of SQLite..*/.S
342f0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
34300 6c 69 74 65 33 5f 72 65 6b 65 79 28 0a 20 20 73  lite3_rekey(.  s
34310 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
34320 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
34330 20 44 61 74 61 62 61 73 65 20 74 6f 20 62 65 20   Database to be 
34340 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e  rekeyed */.  con
34350 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69  st void *pKey, i
34360 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54  nt nKey     /* T
34370 68 65 20 6e 65 77 20 6b 65 79 20 2a 2f 0a 29 3b  he new key */.);
34380 0a 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20  ../*.** Specify 
34390 74 68 65 20 61 63 74 69 76 61 74 69 6f 6e 20 6b  the activation k
343a0 65 79 20 66 6f 72 20 61 20 53 45 45 20 64 61 74  ey for a SEE dat
343b0 61 62 61 73 65 2e 20 20 55 6e 6c 65 73 73 20 0a  abase.  Unless .
343c0 2a 2a 20 61 63 74 69 76 61 74 65 64 2c 20 6e 6f  ** activated, no
343d0 6e 65 20 6f 66 20 74 68 65 20 53 45 45 20 72 6f  ne of the SEE ro
343e0 75 74 69 6e 65 73 20 77 69 6c 6c 20 77 6f 72 6b  utines will work
343f0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
34400 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 61 63 74  void sqlite3_act
34410 69 76 61 74 65 5f 73 65 65 28 0a 20 20 63 6f 6e  ivate_see(.  con
34420 73 74 20 63 68 61 72 20 2a 7a 50 61 73 73 50 68  st char *zPassPh
34430 72 61 73 65 20 20 20 20 20 20 20 20 2f 2a 20 41  rase        /* A
34440 63 74 69 76 61 74 69 6f 6e 20 70 68 72 61 73 65  ctivation phrase
34450 20 2a 2f 0a 29 3b 0a 23 65 6e 64 69 66 0a 0a 23   */.);.#endif..#
34460 69 66 64 65 66 20 53 51 4c 49 54 45 5f 45 4e 41  ifdef SQLITE_ENA
34470 42 4c 45 5f 43 45 52 4f 44 0a 2f 2a 0a 2a 2a 20  BLE_CEROD./*.** 
34480 53 70 65 63 69 66 79 20 74 68 65 20 61 63 74 69  Specify the acti
34490 76 61 74 69 6f 6e 20 6b 65 79 20 66 6f 72 20 61  vation key for a
344a0 20 43 45 52 4f 44 20 64 61 74 61 62 61 73 65 2e   CEROD database.
344b0 20 20 55 6e 6c 65 73 73 20 0a 2a 2a 20 61 63 74    Unless .** act
344c0 69 76 61 74 65 64 2c 20 6e 6f 6e 65 20 6f 66 20  ivated, none of 
344d0 74 68 65 20 43 45 52 4f 44 20 72 6f 75 74 69 6e  the CEROD routin
344e0 65 73 20 77 69 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f  es will work..*/
344f0 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
34500 20 73 71 6c 69 74 65 33 5f 61 63 74 69 76 61 74   sqlite3_activat
34510 65 5f 63 65 72 6f 64 28 0a 20 20 63 6f 6e 73 74  e_cerod(.  const
34520 20 63 68 61 72 20 2a 7a 50 61 73 73 50 68 72 61   char *zPassPhra
34530 73 65 20 20 20 20 20 20 20 20 2f 2a 20 41 63 74  se        /* Act
34540 69 76 61 74 69 6f 6e 20 70 68 72 61 73 65 20 2a  ivation phrase *
34550 2f 0a 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a  /.);.#endif../*.
34560 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 75 73  ** CAPI3REF: Sus
34570 70 65 6e 64 20 45 78 65 63 75 74 69 6f 6e 20 46  pend Execution F
34580 6f 72 20 41 20 53 68 6f 72 74 20 54 69 6d 65 0a  or A Short Time.
34590 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
345a0 33 5f 73 6c 65 65 70 28 29 20 66 75 6e 63 74 69  3_sleep() functi
345b0 6f 6e 20 63 61 75 73 65 73 20 74 68 65 20 63 75  on causes the cu
345c0 72 72 65 6e 74 20 74 68 72 65 61 64 20 74 6f 20  rrent thread to 
345d0 73 75 73 70 65 6e 64 20 65 78 65 63 75 74 69 6f  suspend executio
345e0 6e 0a 2a 2a 20 66 6f 72 20 61 74 20 6c 65 61 73  n.** for at leas
345f0 74 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69  t a number of mi
34600 6c 6c 69 73 65 63 6f 6e 64 73 20 73 70 65 63 69  lliseconds speci
34610 66 69 65 64 20 69 6e 20 69 74 73 20 70 61 72 61  fied in its para
34620 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  meter..**.** If 
34630 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79  the operating sy
34640 73 74 65 6d 20 64 6f 65 73 20 6e 6f 74 20 73 75  stem does not su
34650 70 70 6f 72 74 20 73 6c 65 65 70 20 72 65 71 75  pport sleep requ
34660 65 73 74 73 20 77 69 74 68 0a 2a 2a 20 6d 69 6c  ests with.** mil
34670 6c 69 73 65 63 6f 6e 64 20 74 69 6d 65 20 72 65  lisecond time re
34680 73 6f 6c 75 74 69 6f 6e 2c 20 74 68 65 6e 20 74  solution, then t
34690 68 65 20 74 69 6d 65 20 77 69 6c 6c 20 62 65 20  he time will be 
346a0 72 6f 75 6e 64 65 64 20 75 70 20 74 6f 0a 2a 2a  rounded up to.**
346b0 20 74 68 65 20 6e 65 61 72 65 73 74 20 73 65 63   the nearest sec
346c0 6f 6e 64 2e 20 54 68 65 20 6e 75 6d 62 65 72 20  ond. The number 
346d0 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  of milliseconds 
346e0 6f 66 20 73 6c 65 65 70 20 61 63 74 75 61 6c 6c  of sleep actuall
346f0 79 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20 66  y.** requested f
34700 72 6f 6d 20 74 68 65 20 6f 70 65 72 61 74 69 6e  rom the operatin
34710 67 20 73 79 73 74 65 6d 20 69 73 20 72 65 74 75  g system is retu
34720 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c  rned..**.** ^SQL
34730 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74  ite implements t
34740 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 62 79  his interface by
34750 20 63 61 6c 6c 69 6e 67 20 74 68 65 20 78 53 6c   calling the xSl
34760 65 65 70 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20  eep().** method 
34770 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b  of the default [
34780 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
34790 65 63 74 2e 20 20 49 66 20 74 68 65 20 78 53 6c  ect.  If the xSl
347a0 65 65 70 28 29 20 6d 65 74 68 6f 64 0a 2a 2a 20  eep() method.** 
347b0 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 56  of the default V
347c0 46 53 20 69 73 20 6e 6f 74 20 69 6d 70 6c 65 6d  FS is not implem
347d0 65 6e 74 65 64 20 63 6f 72 72 65 63 74 6c 79 2c  ented correctly,
347e0 20 6f 72 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e   or not implemen
347f0 74 65 64 20 61 74 0a 2a 2a 20 61 6c 6c 2c 20 74  ted at.** all, t
34800 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
34810 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6c 65 65   of sqlite3_slee
34820 70 28 29 20 6d 61 79 20 64 65 76 69 61 74 65 20  p() may deviate 
34830 66 72 6f 6d 20 74 68 65 20 64 65 73 63 72 69 70  from the descrip
34840 74 69 6f 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 70  tion.** in the p
34850 72 65 76 69 6f 75 73 20 70 61 72 61 67 72 61 70  revious paragrap
34860 68 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  hs..*/.SQLITE_AP
34870 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 6c  I int sqlite3_sl
34880 65 65 70 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  eep(int);../*.**
34890 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20   CAPI3REF: Name 
348a0 4f 66 20 54 68 65 20 46 6f 6c 64 65 72 20 48 6f  Of The Folder Ho
348b0 6c 64 69 6e 67 20 54 65 6d 70 6f 72 61 72 79 20  lding Temporary 
348c0 46 69 6c 65 73 0a 2a 2a 0a 2a 2a 20 5e 28 49 66  Files.**.** ^(If
348d0 20 74 68 69 73 20 67 6c 6f 62 61 6c 20 76 61 72   this global var
348e0 69 61 62 6c 65 20 69 73 20 6d 61 64 65 20 74 6f  iable is made to
348f0 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 69   point to a stri
34900 6e 67 20 77 68 69 63 68 20 69 73 0a 2a 2a 20 74  ng which is.** t
34910 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 66 6f 6c  he name of a fol
34920 64 65 72 20 28 61 2e 6b 2e 61 2e 20 64 69 72 65  der (a.k.a. dire
34930 63 74 6f 72 79 29 2c 20 74 68 65 6e 20 61 6c 6c  ctory), then all
34940 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73   temporary files
34950 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 53  .** created by S
34960 51 4c 69 74 65 20 77 68 65 6e 20 75 73 69 6e 67  QLite when using
34970 20 61 20 62 75 69 6c 74 2d 69 6e 20 5b 73 71 6c   a built-in [sql
34980 69 74 65 33 5f 76 66 73 20 7c 20 56 46 53 5d 0a  ite3_vfs | VFS].
34990 2a 2a 20 77 69 6c 6c 20 62 65 20 70 6c 61 63 65  ** will be place
349a0 64 20 69 6e 20 74 68 61 74 20 64 69 72 65 63 74  d in that direct
349b0 6f 72 79 2e 29 5e 20 20 5e 49 66 20 74 68 69 73  ory.)^  ^If this
349c0 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69 73 20   variable.** is 
349d0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  a NULL pointer, 
349e0 74 68 65 6e 20 53 51 4c 69 74 65 20 70 65 72 66  then SQLite perf
349f0 6f 72 6d 73 20 61 20 73 65 61 72 63 68 20 66 6f  orms a search fo
34a00 72 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65  r an appropriate
34a10 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69  .** temporary fi
34a20 6c 65 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a  le directory..**
34a30 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61  .** It is not sa
34a40 66 65 20 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f  fe to read or mo
34a50 64 69 66 79 20 74 68 69 73 20 76 61 72 69 61 62  dify this variab
34a60 6c 65 20 69 6e 20 6d 6f 72 65 20 74 68 61 6e 20  le in more than 
34a70 6f 6e 65 0a 2a 2a 20 74 68 72 65 61 64 20 61 74  one.** thread at
34a80 20 61 20 74 69 6d 65 2e 20 20 49 74 20 69 73 20   a time.  It is 
34a90 6e 6f 74 20 73 61 66 65 20 74 6f 20 72 65 61 64  not safe to read
34aa0 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20   or modify this 
34ab0 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69 66 20 61  variable.** if a
34ac0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
34ad0 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20  ction] is being 
34ae0 75 73 65 64 20 61 74 20 74 68 65 20 73 61 6d 65  used at the same
34af0 20 74 69 6d 65 20 69 6e 20 61 20 73 65 70 61 72   time in a separ
34b00 61 74 65 0a 2a 2a 20 74 68 72 65 61 64 2e 0a 2a  ate.** thread..*
34b10 2a 20 49 74 20 69 73 20 69 6e 74 65 6e 64 65 64  * It is intended
34b20 20 74 68 61 74 20 74 68 69 73 20 76 61 72 69 61   that this varia
34b30 62 6c 65 20 62 65 20 73 65 74 20 6f 6e 63 65 0a  ble be set once.
34b40 2a 2a 20 61 73 20 70 61 72 74 20 6f 66 20 70 72  ** as part of pr
34b50 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69 7a 61  ocess initializa
34b60 74 69 6f 6e 20 61 6e 64 20 62 65 66 6f 72 65 20  tion and before 
34b70 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72  any SQLite inter
34b80 66 61 63 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  face.** routines
34b90 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65   have been calle
34ba0 64 20 61 6e 64 20 74 68 61 74 20 74 68 69 73 20  d and that this 
34bb0 76 61 72 69 61 62 6c 65 20 72 65 6d 61 69 6e 20  variable remain 
34bc0 75 6e 63 68 61 6e 67 65 64 0a 2a 2a 20 74 68 65  unchanged.** the
34bd0 72 65 61 66 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  reafter..**.** ^
34be0 54 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f  The [temp_store_
34bf0 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61  directory pragma
34c00 5d 20 6d 61 79 20 6d 6f 64 69 66 79 20 74 68 69  ] may modify thi
34c10 73 20 76 61 72 69 61 62 6c 65 20 61 6e 64 20 63  s variable and c
34c20 61 75 73 65 0a 2a 2a 20 69 74 20 74 6f 20 70 6f  ause.** it to po
34c30 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  int to memory ob
34c40 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
34c50 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 2e 20 20 5e  ite3_malloc].  ^
34c60 46 75 72 74 68 65 72 6d 6f 72 65 2c 0a 2a 2a 20  Furthermore,.** 
34c70 74 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f  the [temp_store_
34c80 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61  directory pragma
34c90 5d 20 61 6c 77 61 79 73 20 61 73 73 75 6d 65 73  ] always assumes
34ca0 20 74 68 61 74 20 61 6e 79 20 73 74 72 69 6e 67   that any string
34cb0 0a 2a 2a 20 74 68 61 74 20 74 68 69 73 20 76 61  .** that this va
34cc0 72 69 61 62 6c 65 20 70 6f 69 6e 74 73 20 74 6f  riable points to
34cd0 20 69 73 20 68 65 6c 64 20 69 6e 20 6d 65 6d 6f   is held in memo
34ce0 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ry obtained from
34cf0 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61   .** [sqlite3_ma
34d00 6c 6c 6f 63 5d 20 61 6e 64 20 74 68 65 20 70 72  lloc] and the pr
34d10 61 67 6d 61 20 6d 61 79 20 61 74 74 65 6d 70 74  agma may attempt
34d20 20 74 6f 20 66 72 65 65 20 74 68 61 74 20 6d 65   to free that me
34d30 6d 6f 72 79 0a 2a 2a 20 75 73 69 6e 67 20 5b 73  mory.** using [s
34d40 71 6c 69 74 65 33 5f 66 72 65 65 5d 2e 0a 2a 2a  qlite3_free]..**
34d50 20 48 65 6e 63 65 2c 20 69 66 20 74 68 69 73 20   Hence, if this 
34d60 76 61 72 69 61 62 6c 65 20 69 73 20 6d 6f 64 69  variable is modi
34d70 66 69 65 64 20 64 69 72 65 63 74 6c 79 2c 20 65  fied directly, e
34d80 69 74 68 65 72 20 69 74 20 73 68 6f 75 6c 64 20  ither it should 
34d90 62 65 0a 2a 2a 20 6d 61 64 65 20 4e 55 4c 4c 20  be.** made NULL 
34da0 6f 72 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74  or made to point
34db0 20 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69   to memory obtai
34dc0 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
34dd0 33 5f 6d 61 6c 6c 6f 63 5d 0a 2a 2a 20 6f 72 20  3_malloc].** or 
34de0 65 6c 73 65 20 74 68 65 20 75 73 65 20 6f 66 20  else the use of 
34df0 74 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f  the [temp_store_
34e00 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61  directory pragma
34e10 5d 20 73 68 6f 75 6c 64 20 62 65 20 61 76 6f 69  ] should be avoi
34e20 64 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ded..*/.SQLITE_A
34e30 50 49 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  PI char *sqlite3
34e40 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 3b  _temp_directory;
34e50 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
34e60 3a 20 54 65 73 74 20 46 6f 72 20 41 75 74 6f 2d  : Test For Auto-
34e70 43 6f 6d 6d 69 74 20 4d 6f 64 65 0a 2a 2a 20 4b  Commit Mode.** K
34e80 45 59 57 4f 52 44 53 3a 20 7b 61 75 74 6f 63 6f  EYWORDS: {autoco
34e90 6d 6d 69 74 20 6d 6f 64 65 7d 0a 2a 2a 0a 2a 2a  mmit mode}.**.**
34ea0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65   ^The sqlite3_ge
34eb0 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 29 20 69  t_autocommit() i
34ec0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
34ed0 20 6e 6f 6e 2d 7a 65 72 6f 20 6f 72 0a 2a 2a 20   non-zero or.** 
34ee0 7a 65 72 6f 20 69 66 20 74 68 65 20 67 69 76 65  zero if the give
34ef0 6e 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  n database conne
34f00 63 74 69 6f 6e 20 69 73 20 6f 72 20 69 73 20 6e  ction is or is n
34f10 6f 74 20 69 6e 20 61 75 74 6f 63 6f 6d 6d 69 74  ot in autocommit
34f20 20 6d 6f 64 65 2c 0a 2a 2a 20 72 65 73 70 65 63   mode,.** respec
34f30 74 69 76 65 6c 79 2e 20 20 5e 41 75 74 6f 63 6f  tively.  ^Autoco
34f40 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 6f 6e 20  mmit mode is on 
34f50 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 5e  by default..** ^
34f60 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20  Autocommit mode 
34f70 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 61  is disabled by a
34f80 20 5b 42 45 47 49 4e 5d 20 73 74 61 74 65 6d 65   [BEGIN] stateme
34f90 6e 74 2e 0a 2a 2a 20 5e 41 75 74 6f 63 6f 6d 6d  nt..** ^Autocomm
34fa0 69 74 20 6d 6f 64 65 20 69 73 20 72 65 2d 65 6e  it mode is re-en
34fb0 61 62 6c 65 64 20 62 79 20 61 20 5b 43 4f 4d 4d  abled by a [COMM
34fc0 49 54 5d 20 6f 72 20 5b 52 4f 4c 4c 42 41 43 4b  IT] or [ROLLBACK
34fd0 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 63 65 72 74  ]..**.** If cert
34fe0 61 69 6e 20 6b 69 6e 64 73 20 6f 66 20 65 72 72  ain kinds of err
34ff0 6f 72 73 20 6f 63 63 75 72 20 6f 6e 20 61 20 73  ors occur on a s
35000 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20  tatement within 
35010 61 20 6d 75 6c 74 69 2d 73 74 61 74 65 6d 65 6e  a multi-statemen
35020 74 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e  t.** transaction
35030 20 28 65 72 72 6f 72 73 20 69 6e 63 6c 75 64 69   (errors includi
35040 6e 67 20 5b 53 51 4c 49 54 45 5f 46 55 4c 4c 5d  ng [SQLITE_FULL]
35050 2c 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d  , [SQLITE_IOERR]
35060 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d  ,.** [SQLITE_NOM
35070 45 4d 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 55 53  EM], [SQLITE_BUS
35080 59 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f  Y], and [SQLITE_
35090 49 4e 54 45 52 52 55 50 54 5d 29 20 74 68 65 6e  INTERRUPT]) then
350a0 20 74 68 65 0a 2a 2a 20 74 72 61 6e 73 61 63 74   the.** transact
350b0 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 72 6f 6c  ion might be rol
350c0 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74  led back automat
350d0 69 63 61 6c 6c 79 2e 20 20 54 68 65 20 6f 6e 6c  ically.  The onl
350e0 79 20 77 61 79 20 74 6f 0a 2a 2a 20 66 69 6e 64  y way to.** find
350f0 20 6f 75 74 20 77 68 65 74 68 65 72 20 53 51 4c   out whether SQL
35100 69 74 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ite automaticall
35110 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 74 68  y rolled back th
35120 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 61 66  e transaction af
35130 74 65 72 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20  ter.** an error 
35140 69 73 20 74 6f 20 75 73 65 20 74 68 69 73 20 66  is to use this f
35150 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49  unction..**.** I
35160 66 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64  f another thread
35170 20 63 68 61 6e 67 65 73 20 74 68 65 20 61 75 74   changes the aut
35180 6f 63 6f 6d 6d 69 74 20 73 74 61 74 75 73 20 6f  ocommit status o
35190 66 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  f the database.*
351a0 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69  * connection whi
351b0 6c 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  le this routine 
351c0 69 73 20 72 75 6e 6e 69 6e 67 2c 20 74 68 65 6e  is running, then
351d0 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
351e0 65 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65  e.** is undefine
351f0 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  d..*/.SQLITE_API
35200 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74   int sqlite3_get
35210 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 73 71 6c 69  _autocommit(sqli
35220 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  te3*);../*.** CA
35230 50 49 33 52 45 46 3a 20 46 69 6e 64 20 54 68 65  PI3REF: Find The
35240 20 44 61 74 61 62 61 73 65 20 48 61 6e 64 6c 65   Database Handle
35250 20 4f 66 20 41 20 50 72 65 70 61 72 65 64 20 53   Of A Prepared S
35260 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e  tatement.**.** ^
35270 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 68  The sqlite3_db_h
35280 61 6e 64 6c 65 20 69 6e 74 65 72 66 61 63 65 20  andle interface 
35290 72 65 74 75 72 6e 73 20 74 68 65 20 5b 64 61 74  returns the [dat
352a0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
352b0 5d 20 68 61 6e 64 6c 65 0a 2a 2a 20 74 6f 20 77  ] handle.** to w
352c0 68 69 63 68 20 61 20 5b 70 72 65 70 61 72 65 64  hich a [prepared
352d0 20 73 74 61 74 65 6d 65 6e 74 5d 20 62 65 6c 6f   statement] belo
352e0 6e 67 73 2e 20 20 5e 54 68 65 20 5b 64 61 74 61  ngs.  ^The [data
352f0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
35300 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20  .** returned by 
35310 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c  sqlite3_db_handl
35320 65 20 69 73 20 74 68 65 20 73 61 6d 65 20 5b 64  e is the same [d
35330 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
35340 6f 6e 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73 20  on].** that was 
35350 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
35360 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71  nt.** to the [sq
35370 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
35380 28 29 5d 20 63 61 6c 6c 20 28 6f 72 20 69 74 73  ()] call (or its
35390 20 76 61 72 69 61 6e 74 73 29 20 74 68 61 74 20   variants) that 
353a0 77 61 73 20 75 73 65 64 20 74 6f 0a 2a 2a 20 63  was used to.** c
353b0 72 65 61 74 65 20 74 68 65 20 73 74 61 74 65 6d  reate the statem
353c0 65 6e 74 20 69 6e 20 74 68 65 20 66 69 72 73 74  ent in the first
353d0 20 70 6c 61 63 65 2e 0a 2a 2f 0a 53 51 4c 49 54   place..*/.SQLIT
353e0 45 5f 41 50 49 20 73 71 6c 69 74 65 33 20 2a 73  E_API sqlite3 *s
353f0 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65  qlite3_db_handle
35400 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
35410 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
35420 3a 20 46 69 6e 64 20 74 68 65 20 6e 65 78 74 20  : Find the next 
35430 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
35440 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69  nt.**.** ^This i
35450 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
35460 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
35470 65 20 6e 65 78 74 20 5b 70 72 65 70 61 72 65 64  e next [prepared
35480 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 66 74 65   statement] afte
35490 72 0a 2a 2a 20 70 53 74 6d 74 20 61 73 73 6f 63  r.** pStmt assoc
354a0 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 5b  iated with the [
354b0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
354c0 69 6f 6e 5d 20 70 44 62 2e 20 20 5e 49 66 20 70  ion] pDb.  ^If p
354d0 53 74 6d 74 20 69 73 20 4e 55 4c 4c 0a 2a 2a 20  Stmt is NULL.** 
354e0 74 68 65 6e 20 74 68 69 73 20 69 6e 74 65 72 66  then this interf
354f0 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ace returns a po
35500 69 6e 74 65 72 20 74 6f 20 74 68 65 20 66 69 72  inter to the fir
35510 73 74 20 70 72 65 70 61 72 65 64 20 73 74 61 74  st prepared stat
35520 65 6d 65 6e 74 0a 2a 2a 20 61 73 73 6f 63 69 61  ement.** associa
35530 74 65 64 20 77 69 74 68 20 74 68 65 20 64 61 74  ted with the dat
35540 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
35550 20 70 44 62 2e 20 20 5e 49 66 20 6e 6f 20 70 72   pDb.  ^If no pr
35560 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
35570 0a 2a 2a 20 73 61 74 69 73 66 69 65 73 20 74 68  .** satisfies th
35580 65 20 63 6f 6e 64 69 74 69 6f 6e 73 20 6f 66 20  e conditions of 
35590 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 69 74  this routine, it
355a0 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2e 0a 2a   returns NULL..*
355b0 2a 0a 2a 2a 20 54 68 65 20 5b 64 61 74 61 62 61  *.** The [databa
355c0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70  se connection] p
355d0 6f 69 6e 74 65 72 20 44 20 69 6e 20 61 20 63 61  ointer D in a ca
355e0 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ll to.** [sqlite
355f0 33 5f 6e 65 78 74 5f 73 74 6d 74 28 44 2c 53 29  3_next_stmt(D,S)
35600 5d 20 6d 75 73 74 20 72 65 66 65 72 20 74 6f 20  ] must refer to 
35610 61 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65  an open database
35620 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 61  .** connection a
35630 6e 64 20 69 6e 20 70 61 72 74 69 63 75 6c 61 72  nd in particular
35640 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 61 20 4e   must not be a N
35650 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2f 0a  ULL pointer..*/.
35660 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74  SQLITE_API sqlit
35670 65 33 5f 73 74 6d 74 20 2a 73 71 6c 69 74 65 33  e3_stmt *sqlite3
35680 5f 6e 65 78 74 5f 73 74 6d 74 28 73 71 6c 69 74  _next_stmt(sqlit
35690 65 33 20 2a 70 44 62 2c 20 73 71 6c 69 74 65 33  e3 *pDb, sqlite3
356a0 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
356b0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
356c0 43 6f 6d 6d 69 74 20 41 6e 64 20 52 6f 6c 6c 62  Commit And Rollb
356d0 61 63 6b 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e  ack Notification
356e0 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a   Callbacks.**.**
356f0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f   ^The sqlite3_co
35700 6d 6d 69 74 5f 68 6f 6f 6b 28 29 20 69 6e 74 65  mmit_hook() inte
35710 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20  rface registers 
35720 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75  a callback.** fu
35730 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76  nction to be inv
35740 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 20  oked whenever a 
35750 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 5b  transaction is [
35760 43 4f 4d 4d 49 54 20 7c 20 63 6f 6d 6d 69 74 74  COMMIT | committ
35770 65 64 5d 2e 0a 2a 2a 20 5e 41 6e 79 20 63 61 6c  ed]..** ^Any cal
35780 6c 62 61 63 6b 20 73 65 74 20 62 79 20 61 20 70  lback set by a p
35790 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20  revious call to 
357a0 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68  sqlite3_commit_h
357b0 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20 74 68 65  ook().** for the
357c0 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63   same database c
357d0 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 65  onnection is ove
357e0 72 72 69 64 64 65 6e 2e 0a 2a 2a 20 5e 54 68 65  rridden..** ^The
357f0 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63   sqlite3_rollbac
35800 6b 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61  k_hook() interfa
35810 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63  ce registers a c
35820 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74  allback.** funct
35830 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65  ion to be invoke
35840 64 20 77 68 65 6e 65 76 65 72 20 61 20 74 72 61  d whenever a tra
35850 6e 73 61 63 74 69 6f 6e 20 69 73 20 5b 52 4f 4c  nsaction is [ROL
35860 4c 42 41 43 4b 20 7c 20 72 6f 6c 6c 65 64 20 62  LBACK | rolled b
35870 61 63 6b 5d 2e 0a 2a 2a 20 5e 41 6e 79 20 63 61  ack]..** ^Any ca
35880 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20 61 20  llback set by a 
35890 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f  previous call to
358a0 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63   sqlite3_rollbac
358b0 6b 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20  k_hook().** for 
358c0 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
358d0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
358e0 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20 5e  overridden..** ^
358f0 54 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e  The pArg argumen
35900 74 20 69 73 20 70 61 73 73 65 64 20 74 68 72 6f  t is passed thro
35910 75 67 68 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  ugh to the callb
35920 61 63 6b 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ack..** ^If the 
35930 63 61 6c 6c 62 61 63 6b 20 6f 6e 20 61 20 63 6f  callback on a co
35940 6d 6d 69 74 20 68 6f 6f 6b 20 66 75 6e 63 74 69  mmit hook functi
35950 6f 6e 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a  on returns non-z
35960 65 72 6f 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ero,.** then the
35970 20 63 6f 6d 6d 69 74 20 69 73 20 63 6f 6e 76 65   commit is conve
35980 72 74 65 64 20 69 6e 74 6f 20 61 20 72 6f 6c 6c  rted into a roll
35990 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  back..**.** ^The
359a0 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f   sqlite3_commit_
359b0 68 6f 6f 6b 28 44 2c 43 2c 50 29 20 61 6e 64 20  hook(D,C,P) and 
359c0 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b  sqlite3_rollback
359d0 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29 20 66 75 6e  _hook(D,C,P) fun
359e0 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 74 75 72 6e  ctions.** return
359f0 20 74 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20   the P argument 
35a00 66 72 6f 6d 20 74 68 65 20 70 72 65 76 69 6f 75  from the previou
35a10 73 20 63 61 6c 6c 20 6f 66 20 74 68 65 20 73 61  s call of the sa
35a20 6d 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6f  me function.** o
35a30 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61  n the same [data
35a40 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
35a50 20 44 2c 20 6f 72 20 4e 55 4c 4c 20 66 6f 72 0a   D, or NULL for.
35a60 2a 2a 20 74 68 65 20 66 69 72 73 74 20 63 61 6c  ** the first cal
35a70 6c 20 66 6f 72 20 65 61 63 68 20 66 75 6e 63 74  l for each funct
35a80 69 6f 6e 20 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20  ion on D..**.** 
35a90 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 6d 70  The callback imp
35aa0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73 74  lementation must
35ab0 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67   not do anything
35ac0 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66   that will modif
35ad0 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  y.** the databas
35ae0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61  e connection tha
35af0 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 63 61  t invoked the ca
35b00 6c 6c 62 61 63 6b 2e 20 20 41 6e 79 20 61 63 74  llback.  Any act
35b10 69 6f 6e 73 0a 2a 2a 20 74 6f 20 6d 6f 64 69 66  ions.** to modif
35b20 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  y the database c
35b30 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 62  onnection must b
35b40 65 20 64 65 66 65 72 72 65 64 20 75 6e 74 69 6c  e deferred until
35b50 20 61 66 74 65 72 20 74 68 65 0a 2a 2a 20 63 6f   after the.** co
35b60 6d 70 6c 65 74 69 6f 6e 20 6f 66 20 74 68 65 20  mpletion of the 
35b70 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
35b80 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67   call that trigg
35b90 65 72 65 64 20 74 68 65 20 63 6f 6d 6d 69 74 0a  ered the commit.
35ba0 2a 2a 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 68  ** or rollback h
35bb0 6f 6f 6b 20 69 6e 20 74 68 65 20 66 69 72 73 74  ook in the first
35bc0 20 70 6c 61 63 65 2e 0a 2a 2a 20 4e 6f 74 65 20   place..** Note 
35bd0 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72  that [sqlite3_pr
35be0 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20  epare_v2()] and 
35bf0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
35c00 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65   both modify the
35c10 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  ir.** database c
35c20 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74  onnections for t
35c30 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d  he meaning of "m
35c40 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70  odify" in this p
35c50 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20  aragraph..**.** 
35c60 5e 52 65 67 69 73 74 65 72 69 6e 67 20 61 20 4e  ^Registering a N
35c70 55 4c 4c 20 66 75 6e 63 74 69 6f 6e 20 64 69 73  ULL function dis
35c80 61 62 6c 65 73 20 74 68 65 20 63 61 6c 6c 62 61  ables the callba
35c90 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20  ck..**.** ^When 
35ca0 74 68 65 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20  the commit hook 
35cb0 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65  callback routine
35cc0 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20 74   returns zero, t
35cd0 68 65 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f  he [COMMIT].** o
35ce0 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6c 6c 6f  peration is allo
35cf0 77 65 64 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20  wed to continue 
35d00 6e 6f 72 6d 61 6c 6c 79 2e 20 20 5e 49 66 20 74  normally.  ^If t
35d10 68 65 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 0a 2a  he commit hook.*
35d20 2a 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65  * returns non-ze
35d30 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 5b 43 4f  ro, then the [CO
35d40 4d 4d 49 54 5d 20 69 73 20 63 6f 6e 76 65 72 74  MMIT] is convert
35d50 65 64 20 69 6e 74 6f 20 61 20 5b 52 4f 4c 4c 42  ed into a [ROLLB
35d60 41 43 4b 5d 2e 0a 2a 2a 20 5e 54 68 65 20 72 6f  ACK]..** ^The ro
35d70 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20 69 73 20 69  llback hook is i
35d80 6e 76 6f 6b 65 64 20 6f 6e 20 61 20 72 6f 6c 6c  nvoked on a roll
35d90 62 61 63 6b 20 74 68 61 74 20 72 65 73 75 6c 74  back that result
35da0 73 20 66 72 6f 6d 20 61 20 63 6f 6d 6d 69 74 0a  s from a commit.
35db0 2a 2a 20 68 6f 6f 6b 20 72 65 74 75 72 6e 69 6e  ** hook returnin
35dc0 67 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 6a 75 73 74  g non-zero, just
35dd0 20 61 73 20 69 74 20 77 6f 75 6c 64 20 62 65 20   as it would be 
35de0 77 69 74 68 20 61 6e 79 20 6f 74 68 65 72 20 72  with any other r
35df0 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e  ollback..**.** ^
35e00 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65 73  For the purposes
35e10 20 6f 66 20 74 68 69 73 20 41 50 49 2c 20 61 20   of this API, a 
35e20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 73  transaction is s
35e30 61 69 64 20 74 6f 20 68 61 76 65 20 62 65 65 6e  aid to have been
35e40 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20  .** rolled back 
35e50 69 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20 22  if an explicit "
35e60 52 4f 4c 4c 42 41 43 4b 22 20 73 74 61 74 65 6d  ROLLBACK" statem
35e70 65 6e 74 20 69 73 20 65 78 65 63 75 74 65 64 2c  ent is executed,
35e80 20 6f 72 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20   or.** an error 
35e90 6f 72 20 63 6f 6e 73 74 72 61 69 6e 74 20 63 61  or constraint ca
35ea0 75 73 65 73 20 61 6e 20 69 6d 70 6c 69 63 69 74  uses an implicit
35eb0 20 72 6f 6c 6c 62 61 63 6b 20 74 6f 20 6f 63 63   rollback to occ
35ec0 75 72 2e 0a 2a 2a 20 5e 54 68 65 20 72 6f 6c 6c  ur..** ^The roll
35ed0 62 61 63 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73  back callback is
35ee0 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 69 66 20   not invoked if 
35ef0 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73  a transaction is
35f00 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  .** automaticall
35f10 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62 65  y rolled back be
35f20 63 61 75 73 65 20 74 68 65 20 64 61 74 61 62 61  cause the databa
35f30 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
35f40 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 53   closed..**.** S
35f50 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c  ee also the [sql
35f60 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b  ite3_update_hook
35f70 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ()] interface..*
35f80 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  /.SQLITE_API voi
35f90 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69  d *sqlite3_commi
35fa0 74 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c  t_hook(sqlite3*,
35fb0 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20   int(*)(void*), 
35fc0 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 41  void*);.SQLITE_A
35fd0 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  PI void *sqlite3
35fe0 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 73  _rollback_hook(s
35ff0 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 29  qlite3*, void(*)
36000 28 76 6f 69 64 20 2a 29 2c 20 76 6f 69 64 2a 29  (void *), void*)
36010 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
36020 46 3a 20 44 61 74 61 20 43 68 61 6e 67 65 20 4e  F: Data Change N
36030 6f 74 69 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c  otification Call
36040 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  backs.**.** ^The
36050 20 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f   sqlite3_update_
36060 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65  hook() interface
36070 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c   registers a cal
36080 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a  lback function.*
36090 2a 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61  * with the [data
360a0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
360b0 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74   identified by t
360c0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
360d0 74 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 76 6f 6b  t.** to be invok
360e0 65 64 20 77 68 65 6e 65 76 65 72 20 61 20 72 6f  ed whenever a ro
360f0 77 20 69 73 20 75 70 64 61 74 65 64 2c 20 69 6e  w is updated, in
36100 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65  serted or delete
36110 64 2e 0a 2a 2a 20 5e 41 6e 79 20 63 61 6c 6c 62  d..** ^Any callb
36120 61 63 6b 20 73 65 74 20 62 79 20 61 20 70 72 65  ack set by a pre
36130 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 74 68  vious call to th
36140 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 66  is function.** f
36150 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  or the same data
36160 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
36170 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a  is overridden..*
36180 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64  *.** ^The second
36190 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70   argument is a p
361a0 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 66 75  ointer to the fu
361b0 6e 63 74 69 6f 6e 20 74 6f 20 69 6e 76 6f 6b 65  nction to invoke
361c0 20 77 68 65 6e 20 61 0a 2a 2a 20 72 6f 77 20 69   when a.** row i
361d0 73 20 75 70 64 61 74 65 64 2c 20 69 6e 73 65 72  s updated, inser
361e0 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 2e 0a  ted or deleted..
361f0 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  ** ^The first ar
36200 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 63 61  gument to the ca
36210 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79  llback is a copy
36220 20 6f 66 20 74 68 65 20 74 68 69 72 64 20 61 72   of the third ar
36230 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c  gument.** to sql
36240 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b  ite3_update_hook
36250 28 29 2e 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f  ()..** ^The seco
36260 6e 64 20 63 61 6c 6c 62 61 63 6b 20 61 72 67 75  nd callback argu
36270 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b  ment is one of [
36280 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 5d 2c 20  SQLITE_INSERT], 
36290 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 2c  [SQLITE_DELETE],
362a0 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55  .** or [SQLITE_U
362b0 50 44 41 54 45 5d 2c 20 64 65 70 65 6e 64 69 6e  PDATE], dependin
362c0 67 20 6f 6e 20 74 68 65 20 6f 70 65 72 61 74 69  g on the operati
362d0 6f 6e 20 74 68 61 74 20 63 61 75 73 65 64 20 74  on that caused t
362e0 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74  he callback.** t
362f0 6f 20 62 65 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a  o be invoked..**
36300 20 5e 54 68 65 20 74 68 69 72 64 20 61 6e 64 20   ^The third and 
36310 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 73  fourth arguments
36320 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
36330 20 63 6f 6e 74 61 69 6e 20 70 6f 69 6e 74 65 72   contain pointer
36340 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61  s to the.** data
36350 62 61 73 65 20 61 6e 64 20 74 61 62 6c 65 20 6e  base and table n
36360 61 6d 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  ame containing t
36370 68 65 20 61 66 66 65 63 74 65 64 20 72 6f 77 2e  he affected row.
36380 0a 2a 2a 20 5e 54 68 65 20 66 69 6e 61 6c 20 63  .** ^The final c
36390 61 6c 6c 62 61 63 6b 20 70 61 72 61 6d 65 74 65  allback paramete
363a0 72 20 69 73 20 74 68 65 20 5b 72 6f 77 69 64 5d  r is the [rowid]
363b0 20 6f 66 20 74 68 65 20 72 6f 77 2e 0a 2a 2a 20   of the row..** 
363c0 5e 49 6e 20 74 68 65 20 63 61 73 65 20 6f 66 20  ^In the case of 
363d0 61 6e 20 75 70 64 61 74 65 2c 20 74 68 69 73 20  an update, this 
363e0 69 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 61  is the [rowid] a
363f0 66 74 65 72 20 74 68 65 20 75 70 64 61 74 65 20  fter the update 
36400 74 61 6b 65 73 20 70 6c 61 63 65 2e 0a 2a 2a 0a  takes place..**.
36410 2a 2a 20 5e 28 54 68 65 20 75 70 64 61 74 65 20  ** ^(The update 
36420 68 6f 6f 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f  hook is not invo
36430 6b 65 64 20 77 68 65 6e 20 69 6e 74 65 72 6e 61  ked when interna
36440 6c 20 73 79 73 74 65 6d 20 74 61 62 6c 65 73 20  l system tables 
36450 61 72 65 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 20  are.** modified 
36460 28 69 2e 65 2e 20 73 71 6c 69 74 65 5f 6d 61 73  (i.e. sqlite_mas
36470 74 65 72 20 61 6e 64 20 73 71 6c 69 74 65 5f 73  ter and sqlite_s
36480 65 71 75 65 6e 63 65 29 2e 29 5e 0a 2a 2a 0a 2a  equence).)^.**.*
36490 2a 20 5e 49 6e 20 74 68 65 20 63 75 72 72 65 6e  * ^In the curren
364a0 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  t implementation
364b0 2c 20 74 68 65 20 75 70 64 61 74 65 20 68 6f 6f  , the update hoo
364c0 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 69 6e 76 6f  k.** is not invo
364d0 6b 65 64 20 77 68 65 6e 20 64 75 70 6c 69 63 61  ked when duplica
364e0 74 69 6f 6e 20 72 6f 77 73 20 61 72 65 20 64 65  tion rows are de
364f0 6c 65 74 65 64 20 62 65 63 61 75 73 65 20 6f 66  leted because of
36500 20 61 6e 0a 2a 2a 20 5b 4f 4e 20 43 4f 4e 46 4c   an.** [ON CONFL
36510 49 43 54 20 7c 20 4f 4e 20 43 4f 4e 46 4c 49 43  ICT | ON CONFLIC
36520 54 20 52 45 50 4c 41 43 45 5d 20 63 6c 61 75 73  T REPLACE] claus
36530 65 2e 20 20 5e 4e 6f 72 20 69 73 20 74 68 65 20  e.  ^Nor is the 
36540 75 70 64 61 74 65 20 68 6f 6f 6b 0a 2a 2a 20 69  update hook.** i
36550 6e 76 6f 6b 65 64 20 77 68 65 6e 20 72 6f 77 73  nvoked when rows
36560 20 61 72 65 20 64 65 6c 65 74 65 64 20 75 73 69   are deleted usi
36570 6e 67 20 74 68 65 20 5b 74 72 75 6e 63 61 74 65  ng the [truncate
36580 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 2e 0a   optimization]..
36590 2a 2a 20 54 68 65 20 65 78 63 65 70 74 69 6f 6e  ** The exception
365a0 73 20 64 65 66 69 6e 65 64 20 69 6e 20 74 68 69  s defined in thi
365b0 73 20 70 61 72 61 67 72 61 70 68 20 6d 69 67 68  s paragraph migh
365c0 74 20 63 68 61 6e 67 65 20 69 6e 20 61 20 66 75  t change in a fu
365d0 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20  ture.** release 
365e0 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a  of SQLite..**.**
365f0 20 54 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b   The update hook
36600 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
36610 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74  must not do anyt
36620 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d  hing that will m
36630 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74  odify.** the dat
36640 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
36650 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
36660 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 2e 20 20  e update hook.  
36670 41 6e 79 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 74  Any actions.** t
36680 6f 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74  o modify the dat
36690 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
366a0 20 6d 75 73 74 20 62 65 20 64 65 66 65 72 72 65   must be deferre
366b0 64 20 75 6e 74 69 6c 20 61 66 74 65 72 20 74 68  d until after th
366c0 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e 20  e.** completion 
366d0 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
366e0 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 74 68 61  step()] call tha
366f0 74 20 74 72 69 67 67 65 72 65 64 20 74 68 65 20  t triggered the 
36700 75 70 64 61 74 65 20 68 6f 6f 6b 2e 0a 2a 2a 20  update hook..** 
36710 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74  Note that [sqlit
36720 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
36730 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74   and [sqlite3_st
36740 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66  ep()] both modif
36750 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62  y their.** datab
36760 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20  ase connections 
36770 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20  for the meaning 
36780 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74  of "modify" in t
36790 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a  his paragraph..*
367a0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
367b0 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 44 2c  3_update_hook(D,
367c0 43 2c 50 29 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  C,P) function.**
367d0 20 72 65 74 75 72 6e 73 20 74 68 65 20 50 20 61   returns the P a
367e0 72 67 75 6d 65 6e 74 20 66 72 6f 6d 20 74 68 65  rgument from the
367f0 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 0a 2a   previous call.*
36800 2a 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64  * on the same [d
36810 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
36820 6f 6e 5d 20 44 2c 20 6f 72 20 4e 55 4c 4c 20 66  on] D, or NULL f
36830 6f 72 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20  or.** the first 
36840 63 61 6c 6c 20 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a  call on D..**.**
36850 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73   See also the [s
36860 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f  qlite3_commit_ho
36870 6f 6b 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ok()] and [sqlit
36880 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b  e3_rollback_hook
36890 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  ()].** interface
368a0 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  s..*/.SQLITE_API
368b0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 75   void *sqlite3_u
368c0 70 64 61 74 65 5f 68 6f 6f 6b 28 0a 20 20 73 71  pdate_hook(.  sq
368d0 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 28  lite3*, .  void(
368e0 2a 29 28 76 6f 69 64 20 2a 2c 69 6e 74 20 2c 63  *)(void *,int ,c
368f0 68 61 72 20 63 6f 6e 73 74 20 2a 2c 63 68 61 72  har const *,char
36900 20 63 6f 6e 73 74 20 2a 2c 73 71 6c 69 74 65 33   const *,sqlite3
36910 5f 69 6e 74 36 34 29 2c 0a 20 20 76 6f 69 64 2a  _int64),.  void*
36920 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
36930 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44  REF: Enable Or D
36940 69 73 61 62 6c 65 20 53 68 61 72 65 64 20 50 61  isable Shared Pa
36950 67 65 72 20 43 61 63 68 65 0a 2a 2a 20 4b 45 59  ger Cache.** KEY
36960 57 4f 52 44 53 3a 20 7b 73 68 61 72 65 64 20 63  WORDS: {shared c
36970 61 63 68 65 7d 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  ache}.**.** ^(Th
36980 69 73 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c  is routine enabl
36990 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74  es or disables t
369a0 68 65 20 73 68 61 72 69 6e 67 20 6f 66 20 74 68  he sharing of th
369b0 65 20 64 61 74 61 62 61 73 65 20 63 61 63 68 65  e database cache
369c0 0a 2a 2a 20 61 6e 64 20 73 63 68 65 6d 61 20 64  .** and schema d
369d0 61 74 61 20 73 74 72 75 63 74 75 72 65 73 20 62  ata structures b
369e0 65 74 77 65 65 6e 20 5b 64 61 74 61 62 61 73 65  etween [database
369f0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 7c 20 63 6f   connection | co
36a00 6e 6e 65 63 74 69 6f 6e 73 5d 0a 2a 2a 20 74 6f  nnections].** to
36a10 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
36a20 73 65 2e 20 53 68 61 72 69 6e 67 20 69 73 20 65  se. Sharing is e
36a30 6e 61 62 6c 65 64 20 69 66 20 74 68 65 20 61 72  nabled if the ar
36a40 67 75 6d 65 6e 74 20 69 73 20 74 72 75 65 0a 2a  gument is true.*
36a50 2a 20 61 6e 64 20 64 69 73 61 62 6c 65 64 20 69  * and disabled i
36a60 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 69  f the argument i
36a70 73 20 66 61 6c 73 65 2e 29 5e 0a 2a 2a 0a 2a 2a  s false.)^.**.**
36a80 20 5e 43 61 63 68 65 20 73 68 61 72 69 6e 67 20   ^Cache sharing 
36a90 69 73 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 64  is enabled and d
36aa0 69 73 61 62 6c 65 64 20 66 6f 72 20 61 6e 20 65  isabled for an e
36ab0 6e 74 69 72 65 20 70 72 6f 63 65 73 73 2e 0a 2a  ntire process..*
36ac0 2a 20 54 68 69 73 20 69 73 20 61 20 63 68 61 6e  * This is a chan
36ad0 67 65 20 61 73 20 6f 66 20 53 51 4c 69 74 65 20  ge as of SQLite 
36ae0 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 2e 20 49  version 3.5.0. I
36af0 6e 20 70 72 69 6f 72 20 76 65 72 73 69 6f 6e 73  n prior versions
36b00 20 6f 66 20 53 51 4c 69 74 65 2c 0a 2a 2a 20 73   of SQLite,.** s
36b10 68 61 72 69 6e 67 20 77 61 73 20 65 6e 61 62 6c  haring was enabl
36b20 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 20 66  ed or disabled f
36b30 6f 72 20 65 61 63 68 20 74 68 72 65 61 64 20 73  or each thread s
36b40 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a  eparately..**.**
36b50 20 5e 28 54 68 65 20 63 61 63 68 65 20 73 68 61   ^(The cache sha
36b60 72 69 6e 67 20 6d 6f 64 65 20 73 65 74 20 62 79  ring mode set by
36b70 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   this interface 
36b80 65 66 66 65 63 74 73 20 61 6c 6c 20 73 75 62 73  effects all subs
36b90 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20  equent.** calls 
36ba0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  to [sqlite3_open
36bb0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
36bc0 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64 20 5b 73  en_v2()], and [s
36bd0 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
36be0 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 64 61  ..** Existing da
36bf0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
36c00 6e 73 20 63 6f 6e 74 69 6e 75 65 20 75 73 65 20  ns continue use 
36c10 74 68 65 20 73 68 61 72 69 6e 67 20 6d 6f 64 65  the sharing mode
36c20 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 69 6e 20  .** that was in 
36c30 65 66 66 65 63 74 20 61 74 20 74 68 65 20 74 69  effect at the ti
36c40 6d 65 20 74 68 65 79 20 77 65 72 65 20 6f 70 65  me they were ope
36c50 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 54  ned.)^.**.** ^(T
36c60 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75  his routine retu
36c70 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  rns [SQLITE_OK] 
36c80 69 66 20 73 68 61 72 65 64 20 63 61 63 68 65 20  if shared cache 
36c90 77 61 73 20 65 6e 61 62 6c 65 64 20 6f 72 20 64  was enabled or d
36ca0 69 73 61 62 6c 65 64 0a 2a 2a 20 73 75 63 63 65  isabled.** succe
36cb0 73 73 66 75 6c 6c 79 2e 20 20 41 6e 20 5b 65 72  ssfully.  An [er
36cc0 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74  ror code] is ret
36cd0 75 72 6e 65 64 20 6f 74 68 65 72 77 69 73 65 2e  urned otherwise.
36ce0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 68 61 72 65 64  )^.**.** ^Shared
36cf0 20 63 61 63 68 65 20 69 73 20 64 69 73 61 62 6c   cache is disabl
36d00 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 20 42  ed by default. B
36d10 75 74 20 74 68 69 73 20 6d 69 67 68 74 20 63 68  ut this might ch
36d20 61 6e 67 65 20 69 6e 0a 2a 2a 20 66 75 74 75 72  ange in.** futur
36d30 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51  e releases of SQ
36d40 4c 69 74 65 2e 20 20 41 70 70 6c 69 63 61 74 69  Lite.  Applicati
36d50 6f 6e 73 20 74 68 61 74 20 63 61 72 65 20 61 62  ons that care ab
36d60 6f 75 74 20 73 68 61 72 65 64 0a 2a 2a 20 63 61  out shared.** ca
36d70 63 68 65 20 73 65 74 74 69 6e 67 20 73 68 6f 75  che setting shou
36d80 6c 64 20 73 65 74 20 69 74 20 65 78 70 6c 69 63  ld set it explic
36d90 69 74 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  itly..**.** See 
36da0 41 6c 73 6f 3a 20 20 5b 53 51 4c 69 74 65 20 53  Also:  [SQLite S
36db0 68 61 72 65 64 2d 43 61 63 68 65 20 4d 6f 64 65  hared-Cache Mode
36dc0 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ].*/.SQLITE_API 
36dd0 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 6e 61 62  int sqlite3_enab
36de0 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28  le_shared_cache(
36df0 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
36e00 49 33 52 45 46 3a 20 41 74 74 65 6d 70 74 20 54  I3REF: Attempt T
36e10 6f 20 46 72 65 65 20 48 65 61 70 20 4d 65 6d 6f  o Free Heap Memo
36e20 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ry.**.** ^The sq
36e30 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65  lite3_release_me
36e40 6d 6f 72 79 28 29 20 69 6e 74 65 72 66 61 63 65  mory() interface
36e50 20 61 74 74 65 6d 70 74 73 20 74 6f 20 66 72 65   attempts to fre
36e60 65 20 4e 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20  e N bytes.** of 
36e70 68 65 61 70 20 6d 65 6d 6f 72 79 20 62 79 20 64  heap memory by d
36e80 65 61 6c 6c 6f 63 61 74 69 6e 67 20 6e 6f 6e 2d  eallocating non-
36e90 65 73 73 65 6e 74 69 61 6c 20 6d 65 6d 6f 72 79  essential memory
36ea0 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 0a 2a 2a 20   allocations.** 
36eb0 68 65 6c 64 20 62 79 20 74 68 65 20 64 61 74 61  held by the data
36ec0 62 61 73 65 20 6c 69 62 72 61 72 79 2e 20 20 20  base library.   
36ed0 4d 65 6d 6f 72 79 20 75 73 65 64 20 74 6f 20 63  Memory used to c
36ee0 61 63 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a  ache database.**
36ef0 20 70 61 67 65 73 20 74 6f 20 69 6d 70 72 6f 76   pages to improv
36f00 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 69 73  e performance is
36f10 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 6e   an example of n
36f20 6f 6e 2d 65 73 73 65 6e 74 69 61 6c 20 6d 65 6d  on-essential mem
36f30 6f 72 79 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33  ory..** ^sqlite3
36f40 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28  _release_memory(
36f50 29 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  ) returns the nu
36f60 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 61 63  mber of bytes ac
36f70 74 75 61 6c 6c 79 20 66 72 65 65 64 2c 0a 2a 2a  tually freed,.**
36f80 20 77 68 69 63 68 20 6d 69 67 68 74 20 62 65 20   which might be 
36f90 6d 6f 72 65 20 6f 72 20 6c 65 73 73 20 74 68 61  more or less tha
36fa0 6e 20 74 68 65 20 61 6d 6f 75 6e 74 20 72 65 71  n the amount req
36fb0 75 65 73 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20  uested..** ^The 
36fc0 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f  sqlite3_release_
36fd0 6d 65 6d 6f 72 79 28 29 20 72 6f 75 74 69 6e 65  memory() routine
36fe0 20 69 73 20 61 20 6e 6f 2d 6f 70 20 72 65 74 75   is a no-op retu
36ff0 72 6e 69 6e 67 20 7a 65 72 6f 0a 2a 2a 20 69 66  rning zero.** if
37000 20 53 51 4c 69 74 65 20 69 73 20 6e 6f 74 20 63   SQLite is not c
37010 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51  ompiled with [SQ
37020 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 4f  LITE_ENABLE_MEMO
37030 52 59 5f 4d 41 4e 41 47 45 4d 45 4e 54 5d 2e 0a  RY_MANAGEMENT]..
37040 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
37050 74 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73  t sqlite3_releas
37060 65 5f 6d 65 6d 6f 72 79 28 69 6e 74 29 3b 0a 0a  e_memory(int);..
37070 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
37080 49 6d 70 6f 73 65 20 41 20 4c 69 6d 69 74 20 4f  Impose A Limit O
37090 6e 20 48 65 61 70 20 53 69 7a 65 0a 2a 2a 0a 2a  n Heap Size.**.*
370a0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73  * ^The sqlite3_s
370b0 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34  oft_heap_limit64
370c0 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
370d0 73 20 61 6e 64 2f 6f 72 20 71 75 65 72 69 65 73  s and/or queries
370e0 20 74 68 65 0a 2a 2a 20 73 6f 66 74 20 6c 69 6d   the.** soft lim
370f0 69 74 20 6f 6e 20 74 68 65 20 61 6d 6f 75 6e 74  it on the amount
37100 20 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72 79 20   of heap memory 
37110 74 68 61 74 20 6d 61 79 20 62 65 20 61 6c 6c 6f  that may be allo
37120 63 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 2e  cated by SQLite.
37130 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 73 74 72 69  .** ^SQLite stri
37140 76 65 73 20 74 6f 20 6b 65 65 70 20 68 65 61 70  ves to keep heap
37150 20 6d 65 6d 6f 72 79 20 75 74 69 6c 69 7a 61 74   memory utilizat
37160 69 6f 6e 20 62 65 6c 6f 77 20 74 68 65 20 73 6f  ion below the so
37170 66 74 20 68 65 61 70 0a 2a 2a 20 6c 69 6d 69 74  ft heap.** limit
37180 20 62 79 20 72 65 64 75 63 69 6e 67 20 74 68 65   by reducing the
37190 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 67 65 73   number of pages
371a0 20 68 65 6c 64 20 69 6e 20 74 68 65 20 70 61 67   held in the pag
371b0 65 20 63 61 63 68 65 0a 2a 2a 20 61 73 20 68 65  e cache.** as he
371c0 61 70 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 73  ap memory usages
371d0 20 61 70 70 72 6f 61 63 68 65 73 20 74 68 65 20   approaches the 
371e0 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 54 68 65 20 73  limit..** ^The s
371f0 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69  oft heap limit i
37200 73 20 22 73 6f 66 74 22 20 62 65 63 61 75 73 65  s "soft" because
37210 20 65 76 65 6e 20 74 68 6f 75 67 68 20 53 51 4c   even though SQL
37220 69 74 65 20 73 74 72 69 76 65 73 20 74 6f 20 73  ite strives to s
37230 74 61 79 0a 2a 2a 20 62 65 6c 6f 77 20 74 68 65  tay.** below the
37240 20 6c 69 6d 69 74 2c 20 69 74 20 77 69 6c 6c 20   limit, it will 
37250 65 78 63 65 65 64 20 74 68 65 20 6c 69 6d 69 74  exceed the limit
37260 20 72 61 74 68 65 72 20 74 68 61 6e 20 67 65 6e   rather than gen
37270 65 72 61 74 65 0a 2a 2a 20 61 6e 20 5b 53 51 4c  erate.** an [SQL
37280 49 54 45 5f 4e 4f 4d 45 4d 5d 20 65 72 72 6f 72  ITE_NOMEM] error
37290 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  .  In other word
372a0 73 2c 20 74 68 65 20 73 6f 66 74 20 68 65 61 70  s, the soft heap
372b0 20 6c 69 6d 69 74 20 0a 2a 2a 20 69 73 20 61 64   limit .** is ad
372c0 76 69 73 6f 72 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a  visory only..**.
372d0 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 20 76  ** ^The return v
372e0 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65  alue from sqlite
372f0 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69  3_soft_heap_limi
37300 74 36 34 28 29 20 69 73 20 74 68 65 20 73 69 7a  t64() is the siz
37310 65 20 6f 66 0a 2a 2a 20 74 68 65 20 73 6f 66 74  e of.** the soft
37320 20 68 65 61 70 20 6c 69 6d 69 74 20 70 72 69 6f   heap limit prio
37330 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 2e 20 20  r to the call.  
37340 5e 49 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74  ^If the argument
37350 20 4e 20 69 73 20 6e 65 67 61 74 69 76 65 0a 2a   N is negative.*
37360 2a 20 74 68 65 6e 20 6e 6f 20 63 68 61 6e 67 65  * then no change
37370 20 69 73 20 6d 61 64 65 20 74 6f 20 74 68 65 20   is made to the 
37380 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 2e  soft heap limit.
37390 20 20 48 65 6e 63 65 2c 20 74 68 65 20 63 75 72    Hence, the cur
373a0 72 65 6e 74 0a 2a 2a 20 73 69 7a 65 20 6f 66 20  rent.** size of 
373b0 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69  the soft heap li
373c0 6d 69 74 20 63 61 6e 20 62 65 20 64 65 74 65 72  mit can be deter
373d0 6d 69 6e 65 64 20 62 79 20 69 6e 76 6f 6b 69 6e  mined by invokin
373e0 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 6f 66  g.** sqlite3_sof
373f0 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29  t_heap_limit64()
37400 20 77 69 74 68 20 61 20 6e 65 67 61 74 69 76 65   with a negative
37410 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a   argument..**.**
37420 20 5e 49 66 20 74 68 65 20 61 72 67 75 6d 65 6e   ^If the argumen
37430 74 20 4e 20 69 73 20 7a 65 72 6f 20 74 68 65 6e  t N is zero then
37440 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c   the soft heap l
37450 69 6d 69 74 20 69 73 20 64 69 73 61 62 6c 65 64  imit is disabled
37460 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 6f  ..**.** ^(The so
37470 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73  ft heap limit is
37480 20 6e 6f 74 20 65 6e 66 6f 72 63 65 64 20 69 6e   not enforced in
37490 20 74 68 65 20 63 75 72 72 65 6e 74 20 69 6d 70   the current imp
374a0 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69  lementation.** i
374b0 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66  f one or more of
374c0 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 6f 6e 64 69   following condi
374d0 74 69 6f 6e 73 20 61 72 65 20 74 72 75 65 3a 0a  tions are true:.
374e0 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
374f0 69 3e 20 54 68 65 20 73 6f 66 74 20 68 65 61 70  i> The soft heap
37500 20 6c 69 6d 69 74 20 69 73 20 73 65 74 20 74 6f   limit is set to
37510 20 7a 65 72 6f 2e 0a 2a 2a 20 3c 6c 69 3e 20 4d   zero..** <li> M
37520 65 6d 6f 72 79 20 61 63 63 6f 75 6e 74 69 6e 67  emory accounting
37530 20 69 73 20 64 69 73 61 62 6c 65 64 20 75 73 69   is disabled usi
37540 6e 67 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e  ng a combination
37550 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   of the.**      
37560 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d  [sqlite3_config]
37570 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  ([SQLITE_CONFIG_
37580 4d 45 4d 53 54 41 54 55 53 5d 2c 2e 2e 2e 29 20  MEMSTATUS],...) 
37590 73 74 61 72 74 2d 74 69 6d 65 20 6f 70 74 69 6f  start-time optio
375a0 6e 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 74 68  n and.**      th
375b0 65 20 5b 53 51 4c 49 54 45 5f 44 45 46 41 55 4c  e [SQLITE_DEFAUL
375c0 54 5f 4d 45 4d 53 54 41 54 55 53 5d 20 63 6f 6d  T_MEMSTATUS] com
375d0 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
375e0 2e 0a 2a 2a 20 3c 6c 69 3e 20 41 6e 20 61 6c 74  ..** <li> An alt
375f0 65 72 6e 61 74 69 76 65 20 70 61 67 65 20 63 61  ernative page ca
37600 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  che implementati
37610 6f 6e 20 69 73 20 73 70 65 63 69 66 69 65 64 20  on is specified 
37620 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20 5b 73  using.**      [s
37630 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b  qlite3_config]([
37640 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
37650 41 43 48 45 5d 2c 2e 2e 2e 29 2e 0a 2a 2a 20 3c  ACHE],...)..** <
37660 6c 69 3e 20 54 68 65 20 70 61 67 65 20 63 61 63  li> The page cac
37670 68 65 20 61 6c 6c 6f 63 61 74 65 73 20 66 72 6f  he allocates fro
37680 6d 20 69 74 73 20 6f 77 6e 20 6d 65 6d 6f 72 79  m its own memory
37690 20 70 6f 6f 6c 20 73 75 70 70 6c 69 65 64 0a 2a   pool supplied.*
376a0 2a 20 20 20 20 20 20 62 79 20 5b 73 71 6c 69 74  *      by [sqlit
376b0 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49  e3_config]([SQLI
376c0 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41  TE_CONFIG_PAGECA
376d0 43 48 45 5d 2c 2e 2e 2e 29 20 72 61 74 68 65 72  CHE],...) rather
376e0 20 74 68 61 6e 0a 2a 2a 20 20 20 20 20 20 66 72   than.**      fr
376f0 6f 6d 20 74 68 65 20 68 65 61 70 2e 0a 2a 2a 20  om the heap..** 
37700 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 42 65  </ul>)^.**.** Be
37710 67 69 6e 6e 69 6e 67 20 77 69 74 68 20 53 51 4c  ginning with SQL
37720 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e  ite version 3.7.
37730 33 2c 20 74 68 65 20 73 6f 66 74 20 68 65 61 70  3, the soft heap
37740 20 6c 69 6d 69 74 20 69 73 20 65 6e 66 6f 72 63   limit is enforc
37750 65 64 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73 73  ed.** regardless
37760 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e   of whether or n
37770 6f 74 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 45  ot the [SQLITE_E
37780 4e 41 42 4c 45 5f 4d 45 4d 4f 52 59 5f 4d 41 4e  NABLE_MEMORY_MAN
37790 41 47 45 4d 45 4e 54 5d 0a 2a 2a 20 63 6f 6d 70  AGEMENT].** comp
377a0 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
377b0 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 57 69 74  is invoked.  Wit
377c0 68 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  h [SQLITE_ENABLE
377d0 5f 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d 45  _MEMORY_MANAGEME
377e0 4e 54 5d 2c 0a 2a 2a 20 74 68 65 20 73 6f 66 74  NT],.** the soft
377f0 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73 20 65   heap limit is e
37800 6e 66 6f 72 63 65 64 20 6f 6e 20 65 76 65 72 79  nforced on every
37810 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
37820 6f 6e 2e 20 20 57 69 74 68 6f 75 74 0a 2a 2a 20  on.  Without.** 
37830 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d  [SQLITE_ENABLE_M
37840 45 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d 45 4e 54  EMORY_MANAGEMENT
37850 5d 2c 20 74 68 65 20 73 6f 66 74 20 68 65 61 70  ], the soft heap
37860 20 6c 69 6d 69 74 20 69 73 20 6f 6e 6c 79 20 65   limit is only e
37870 6e 66 6f 72 63 65 64 0a 2a 2a 20 77 68 65 6e 20  nforced.** when 
37880 6d 65 6d 6f 72 79 20 69 73 20 61 6c 6c 6f 63 61  memory is alloca
37890 74 65 64 20 62 79 20 74 68 65 20 70 61 67 65 20  ted by the page 
378a0 63 61 63 68 65 2e 20 20 54 65 73 74 69 6e 67 20  cache.  Testing 
378b0 73 75 67 67 65 73 74 73 20 74 68 61 74 20 62 65  suggests that be
378c0 63 61 75 73 65 0a 2a 2a 20 74 68 65 20 70 61 67  cause.** the pag
378d0 65 20 63 61 63 68 65 20 69 73 20 74 68 65 20 70  e cache is the p
378e0 72 65 64 6f 6d 69 6e 61 74 65 20 6d 65 6d 6f 72  redominate memor
378f0 79 20 75 73 65 72 20 69 6e 20 53 51 4c 69 74 65  y user in SQLite
37900 2c 20 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63  , most.** applic
37910 61 74 69 6f 6e 73 20 77 69 6c 6c 20 61 63 68 69  ations will achi
37920 65 76 65 20 61 64 65 71 75 61 74 65 20 73 6f 66  eve adequate sof
37930 74 20 68 65 61 70 20 6c 69 6d 69 74 20 65 6e 66  t heap limit enf
37940 6f 72 63 65 6d 65 6e 74 20 77 69 74 68 6f 75 74  orcement without
37950 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20 5b  .** the use of [
37960 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45  SQLITE_ENABLE_ME
37970 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d 45 4e 54 5d  MORY_MANAGEMENT]
37980 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 69 72 63  ..**.** The circ
37990 75 6d 73 74 61 6e 63 65 73 20 75 6e 64 65 72 20  umstances under 
379a0 77 68 69 63 68 20 53 51 4c 69 74 65 20 77 69 6c  which SQLite wil
379b0 6c 20 65 6e 66 6f 72 63 65 20 74 68 65 20 73 6f  l enforce the so
379c0 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 6d 61  ft heap limit ma
379d0 79 0a 2a 2a 20 63 68 61 6e 67 65 73 20 69 6e 20  y.** changes in 
379e0 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
379f0 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 53 51  of SQLite..*/.SQ
37a00 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33  LITE_API sqlite3
37a10 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 73  _int64 sqlite3_s
37a20 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34  oft_heap_limit64
37a30 28 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 4e  (sqlite3_int64 N
37a40 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
37a50 45 46 3a 20 44 65 70 72 65 63 61 74 65 64 20 53  EF: Deprecated S
37a60 6f 66 74 20 48 65 61 70 20 4c 69 6d 69 74 20 49  oft Heap Limit I
37a70 6e 74 65 72 66 61 63 65 0a 2a 2a 20 44 45 50 52  nterface.** DEPR
37a80 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 69  ECATED.**.** Thi
37a90 73 20 69 73 20 61 20 64 65 70 72 65 63 61 74 65  s is a deprecate
37aa0 64 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65  d version of the
37ab0 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68   [sqlite3_soft_h
37ac0 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 5d 0a 2a  eap_limit64()].*
37ad0 2a 20 69 6e 74 65 72 66 61 63 65 2e 20 20 54 68  * interface.  Th
37ae0 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 70 72  is routine is pr
37af0 6f 76 69 64 65 64 20 66 6f 72 20 68 69 73 74 6f  ovided for histo
37b00 72 69 63 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c  rical compatibil
37b10 69 74 79 0a 2a 2a 20 6f 6e 6c 79 2e 20 20 41 6c  ity.** only.  Al
37b20 6c 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f  l new applicatio
37b30 6e 73 20 73 68 6f 75 6c 64 20 75 73 65 20 74 68  ns should use th
37b40 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6f  e.** [sqlite3_so
37b50 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28  ft_heap_limit64(
37b60 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 61 74  )] interface rat
37b70 68 65 72 20 74 68 61 6e 20 74 68 69 73 20 6f 6e  her than this on
37b80 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  e..*/.SQLITE_API
37b90 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54   SQLITE_DEPRECAT
37ba0 45 44 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  ED void sqlite3_
37bb0 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28  soft_heap_limit(
37bc0 69 6e 74 20 4e 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20  int N);.../*.** 
37bd0 43 41 50 49 33 52 45 46 3a 20 45 78 74 72 61 63  CAPI3REF: Extrac
37be0 74 20 4d 65 74 61 64 61 74 61 20 41 62 6f 75 74  t Metadata About
37bf0 20 41 20 43 6f 6c 75 6d 6e 20 4f 66 20 41 20 54   A Column Of A T
37c00 61 62 6c 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  able.**.** ^This
37c10 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
37c20 20 6d 65 74 61 64 61 74 61 20 61 62 6f 75 74 20   metadata about 
37c30 61 20 73 70 65 63 69 66 69 63 20 63 6f 6c 75 6d  a specific colum
37c40 6e 20 6f 66 20 61 20 73 70 65 63 69 66 69 63 0a  n of a specific.
37c50 2a 2a 20 64 61 74 61 62 61 73 65 20 74 61 62 6c  ** database tabl
37c60 65 20 61 63 63 65 73 73 69 62 6c 65 20 75 73 69  e accessible usi
37c70 6e 67 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  ng the [database
37c80 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e   connection] han
37c90 64 6c 65 0a 2a 2a 20 70 61 73 73 65 64 20 61 73  dle.** passed as
37ca0 20 74 68 65 20 66 69 72 73 74 20 66 75 6e 63 74   the first funct
37cb0 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  ion argument..**
37cc0 0a 2a 2a 20 5e 54 68 65 20 63 6f 6c 75 6d 6e 20  .** ^The column 
37cd0 69 73 20 69 64 65 6e 74 69 66 69 65 64 20 62 79  is identified by
37ce0 20 74 68 65 20 73 65 63 6f 6e 64 2c 20 74 68 69   the second, thi
37cf0 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20 70 61  rd and fourth pa
37d00 72 61 6d 65 74 65 72 73 20 74 6f 0a 2a 2a 20 74  rameters to.** t
37d10 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 54  his function. ^T
37d20 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
37d30 74 65 72 20 69 73 20 65 69 74 68 65 72 20 74 68  ter is either th
37d40 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61  e name of the da
37d50 74 61 62 61 73 65 0a 2a 2a 20 28 69 2e 65 2e 20  tabase.** (i.e. 
37d60 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 20  "main", "temp", 
37d70 6f 72 20 61 6e 20 61 74 74 61 63 68 65 64 20 64  or an attached d
37d80 61 74 61 62 61 73 65 29 20 63 6f 6e 74 61 69 6e  atabase) contain
37d90 69 6e 67 20 74 68 65 20 73 70 65 63 69 66 69 65  ing the specifie
37da0 64 0a 2a 2a 20 74 61 62 6c 65 20 6f 72 20 4e 55  d.** table or NU
37db0 4c 4c 2e 20 5e 49 66 20 69 74 20 69 73 20 4e 55  LL. ^If it is NU
37dc0 4c 4c 2c 20 74 68 65 6e 20 61 6c 6c 20 61 74 74  LL, then all att
37dd0 61 63 68 65 64 20 64 61 74 61 62 61 73 65 73 20  ached databases 
37de0 61 72 65 20 73 65 61 72 63 68 65 64 0a 2a 2a 20  are searched.** 
37df0 66 6f 72 20 74 68 65 20 74 61 62 6c 65 20 75 73  for the table us
37e00 69 6e 67 20 74 68 65 20 73 61 6d 65 20 61 6c 67  ing the same alg
37e10 6f 72 69 74 68 6d 20 75 73 65 64 20 62 79 20 74  orithm used by t
37e20 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 67 69  he database engi
37e30 6e 65 20 74 6f 0a 2a 2a 20 72 65 73 6f 6c 76 65  ne to.** resolve
37e40 20 75 6e 71 75 61 6c 69 66 69 65 64 20 74 61 62   unqualified tab
37e50 6c 65 20 72 65 66 65 72 65 6e 63 65 73 2e 0a 2a  le references..*
37e60 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20  *.** ^The third 
37e70 61 6e 64 20 66 6f 75 72 74 68 20 70 61 72 61 6d  and fourth param
37e80 65 74 65 72 73 20 74 6f 20 74 68 69 73 20 66 75  eters to this fu
37e90 6e 63 74 69 6f 6e 20 61 72 65 20 74 68 65 20 74  nction are the t
37ea0 61 62 6c 65 20 61 6e 64 20 63 6f 6c 75 6d 6e 0a  able and column.
37eb0 2a 2a 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64  ** name of the d
37ec0 65 73 69 72 65 64 20 63 6f 6c 75 6d 6e 2c 20 72  esired column, r
37ed0 65 73 70 65 63 74 69 76 65 6c 79 2e 20 4e 65 69  espectively. Nei
37ee0 74 68 65 72 20 6f 66 20 74 68 65 73 65 20 70 61  ther of these pa
37ef0 72 61 6d 65 74 65 72 73 0a 2a 2a 20 6d 61 79 20  rameters.** may 
37f00 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e  be NULL..**.** ^
37f10 4d 65 74 61 64 61 74 61 20 69 73 20 72 65 74 75  Metadata is retu
37f20 72 6e 65 64 20 62 79 20 77 72 69 74 69 6e 67 20  rned by writing 
37f30 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 20 6c 6f  to the memory lo
37f40 63 61 74 69 6f 6e 73 20 70 61 73 73 65 64 20 61  cations passed a
37f50 73 20 74 68 65 20 35 74 68 0a 2a 2a 20 61 6e 64  s the 5th.** and
37f60 20 73 75 62 73 65 71 75 65 6e 74 20 70 61 72 61   subsequent para
37f70 6d 65 74 65 72 73 20 74 6f 20 74 68 69 73 20 66  meters to this f
37f80 75 6e 63 74 69 6f 6e 2e 20 5e 41 6e 79 20 6f 66  unction. ^Any of
37f90 20 74 68 65 73 65 20 61 72 67 75 6d 65 6e 74 73   these arguments
37fa0 20 6d 61 79 20 62 65 0a 2a 2a 20 4e 55 4c 4c 2c   may be.** NULL,
37fb0 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 74   in which case t
37fc0 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
37fd0 20 65 6c 65 6d 65 6e 74 20 6f 66 20 6d 65 74 61   element of meta
37fe0 64 61 74 61 20 69 73 20 6f 6d 69 74 74 65 64 2e  data is omitted.
37ff0 0a 2a 2a 0a 2a 2a 20 5e 28 3c 62 6c 6f 63 6b 71  .**.** ^(<blockq
38000 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20  uote>.** <table 
38010 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c  border="1">.** <
38020 74 72 3e 3c 74 68 3e 20 50 61 72 61 6d 65 74 65  tr><th> Paramete
38030 72 20 3c 74 68 3e 20 4f 75 74 70 75 74 3c 62 72  r <th> Output<br
38040 3e 54 79 70 65 20 3c 74 68 3e 20 20 44 65 73 63  >Type <th>  Desc
38050 72 69 70 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74  ription.**.** <t
38060 72 3e 3c 74 64 3e 20 35 74 68 20 3c 74 64 3e 20  r><td> 5th <td> 
38070 63 6f 6e 73 74 20 63 68 61 72 2a 20 3c 74 64 3e  const char* <td>
38080 20 44 61 74 61 20 74 79 70 65 0a 2a 2a 20 3c 74   Data type.** <t
38090 72 3e 3c 74 64 3e 20 36 74 68 20 3c 74 64 3e 20  r><td> 6th <td> 
380a0 63 6f 6e 73 74 20 63 68 61 72 2a 20 3c 74 64 3e  const char* <td>
380b0 20 4e 61 6d 65 20 6f 66 20 64 65 66 61 75 6c 74   Name of default
380c0 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   collation seque
380d0 6e 63 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  nce.** <tr><td> 
380e0 37 74 68 20 3c 74 64 3e 20 69 6e 74 20 20 20 20  7th <td> int    
380f0 20 20 20 20 20 3c 74 64 3e 20 54 72 75 65 20 69       <td> True i
38100 66 20 63 6f 6c 75 6d 6e 20 68 61 73 20 61 20 4e  f column has a N
38110 4f 54 20 4e 55 4c 4c 20 63 6f 6e 73 74 72 61 69  OT NULL constrai
38120 6e 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 38  nt.** <tr><td> 8
38130 74 68 20 3c 74 64 3e 20 69 6e 74 20 20 20 20 20  th <td> int     
38140 20 20 20 20 3c 74 64 3e 20 54 72 75 65 20 69 66      <td> True if
38150 20 63 6f 6c 75 6d 6e 20 69 73 20 70 61 72 74 20   column is part 
38160 6f 66 20 74 68 65 20 50 52 49 4d 41 52 59 20 4b  of the PRIMARY K
38170 45 59 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 39  EY.** <tr><td> 9
38180 74 68 20 3c 74 64 3e 20 69 6e 74 20 20 20 20 20  th <td> int     
38190 20 20 20 20 3c 74 64 3e 20 54 72 75 65 20 69 66      <td> True if
381a0 20 63 6f 6c 75 6d 6e 20 69 73 20 5b 41 55 54 4f   column is [AUTO
381b0 49 4e 43 52 45 4d 45 4e 54 5d 0a 2a 2a 20 3c 2f  INCREMENT].** </
381c0 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63  table>.** </bloc
381d0 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20  kquote>)^.**.** 
381e0 5e 54 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e  ^The memory poin
381f0 74 65 64 20 74 6f 20 62 79 20 74 68 65 20 63 68  ted to by the ch
38200 61 72 61 63 74 65 72 20 70 6f 69 6e 74 65 72 73  aracter pointers
38210 20 72 65 74 75 72 6e 65 64 20 66 6f 72 20 74 68   returned for th
38220 65 0a 2a 2a 20 64 65 63 6c 61 72 61 74 69 6f 6e  e.** declaration
38230 20 74 79 70 65 20 61 6e 64 20 63 6f 6c 6c 61 74   type and collat
38240 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 69 73 20  ion sequence is 
38250 76 61 6c 69 64 20 6f 6e 6c 79 20 75 6e 74 69 6c  valid only until
38260 20 74 68 65 20 6e 65 78 74 0a 2a 2a 20 63 61 6c   the next.** cal
38270 6c 20 74 6f 20 61 6e 79 20 53 51 4c 69 74 65 20  l to any SQLite 
38280 41 50 49 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  API function..**
38290 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 70 65 63  .** ^If the spec
382a0 69 66 69 65 64 20 74 61 62 6c 65 20 69 73 20 61  ified table is a
382b0 63 74 75 61 6c 6c 79 20 61 20 76 69 65 77 2c 20  ctually a view, 
382c0 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  an [error code] 
382d0 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
382e0 2a 2a 20 5e 49 66 20 74 68 65 20 73 70 65 63 69  ** ^If the speci
382f0 66 69 65 64 20 63 6f 6c 75 6d 6e 20 69 73 20 22  fied column is "
38300 72 6f 77 69 64 22 2c 20 22 6f 69 64 22 20 6f 72  rowid", "oid" or
38310 20 22 5f 72 6f 77 69 64 5f 22 20 61 6e 64 20 61   "_rowid_" and a
38320 6e 0a 2a 2a 20 5b 49 4e 54 45 47 45 52 20 50 52  n.** [INTEGER PR
38330 49 4d 41 52 59 20 4b 45 59 5d 20 63 6f 6c 75 6d  IMARY KEY] colum
38340 6e 20 68 61 73 20 62 65 65 6e 20 65 78 70 6c 69  n has been expli
38350 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 2c 20  citly declared, 
38360 74 68 65 6e 20 74 68 65 20 6f 75 74 70 75 74 0a  then the output.
38370 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20 61 72  ** parameters ar
38380 65 20 73 65 74 20 66 6f 72 20 74 68 65 20 65 78  e set for the ex
38390 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65  plicitly declare
383a0 64 20 63 6f 6c 75 6d 6e 2e 20 5e 28 49 66 20 74  d column. ^(If t
383b0 68 65 72 65 20 69 73 20 6e 6f 0a 2a 2a 20 65 78  here is no.** ex
383c0 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65  plicitly declare
383d0 64 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41  d [INTEGER PRIMA
383e0 52 59 20 4b 45 59 5d 20 63 6f 6c 75 6d 6e 2c 20  RY KEY] column, 
383f0 74 68 65 6e 20 74 68 65 20 6f 75 74 70 75 74 0a  then the output.
38400 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20 61 72  ** parameters ar
38410 65 20 73 65 74 20 61 73 20 66 6f 6c 6c 6f 77 73  e set as follows
38420 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a  :.**.** <pre>.**
38430 20 20 20 20 20 64 61 74 61 20 74 79 70 65 3a 20       data type: 
38440 22 49 4e 54 45 47 45 52 22 0a 2a 2a 20 20 20 20  "INTEGER".**    
38450 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   collation seque
38460 6e 63 65 3a 20 22 42 49 4e 41 52 59 22 0a 2a 2a  nce: "BINARY".**
38470 20 20 20 20 20 6e 6f 74 20 6e 75 6c 6c 3a 20 30       not null: 0
38480 0a 2a 2a 20 20 20 20 20 70 72 69 6d 61 72 79 20  .**     primary 
38490 6b 65 79 3a 20 31 0a 2a 2a 20 20 20 20 20 61 75  key: 1.**     au
384a0 74 6f 20 69 6e 63 72 65 6d 65 6e 74 3a 20 30 0a  to increment: 0.
384b0 2a 2a 20 3c 2f 70 72 65 3e 29 5e 0a 2a 2a 0a 2a  ** </pre>)^.**.*
384c0 2a 20 5e 28 54 68 69 73 20 66 75 6e 63 74 69 6f  * ^(This functio
384d0 6e 20 6d 61 79 20 6c 6f 61 64 20 6f 6e 65 20 6f  n may load one o
384e0 72 20 6d 6f 72 65 20 73 63 68 65 6d 61 73 20 66  r more schemas f
384f0 72 6f 6d 20 64 61 74 61 62 61 73 65 20 66 69 6c  rom database fil
38500 65 73 2e 20 49 66 20 61 6e 0a 2a 2a 20 65 72 72  es. If an.** err
38510 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67  or occurs during
38520 20 74 68 69 73 20 70 72 6f 63 65 73 73 2c 20 6f   this process, o
38530 72 20 69 66 20 74 68 65 20 72 65 71 75 65 73 74  r if the request
38540 65 64 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75  ed table or colu
38550 6d 6e 0a 2a 2a 20 63 61 6e 6e 6f 74 20 62 65 20  mn.** cannot be 
38560 66 6f 75 6e 64 2c 20 61 6e 20 5b 65 72 72 6f 72  found, an [error
38570 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e   code] is return
38580 65 64 20 61 6e 64 20 61 6e 20 65 72 72 6f 72 20  ed and an error 
38590 6d 65 73 73 61 67 65 20 6c 65 66 74 0a 2a 2a 20  message left.** 
385a0 69 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  in the [database
385b0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 6f   connection] (to
385c0 20 62 65 20 72 65 74 72 69 65 76 65 64 20 75 73   be retrieved us
385d0 69 6e 67 20 73 71 6c 69 74 65 33 5f 65 72 72 6d  ing sqlite3_errm
385e0 73 67 28 29 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  sg()).)^.**.** ^
385f0 54 68 69 73 20 41 50 49 20 69 73 20 6f 6e 6c 79  This API is only
38600 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68   available if th
38610 65 20 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f  e library was co
38620 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a  mpiled with the.
38630 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  ** [SQLITE_ENABL
38640 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54  E_COLUMN_METADAT
38650 41 5d 20 43 2d 70 72 65 70 72 6f 63 65 73 73 6f  A] C-preprocesso
38660 72 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64  r symbol defined
38670 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
38680 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 61 62 6c  int sqlite3_tabl
38690 65 5f 63 6f 6c 75 6d 6e 5f 6d 65 74 61 64 61 74  e_column_metadat
386a0 61 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  a(.  sqlite3 *db
386b0 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
386c0 20 2f 2a 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 68   /* Connection h
386d0 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
386e0 20 63 68 61 72 20 2a 7a 44 62 4e 61 6d 65 2c 20   char *zDbName, 
386f0 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
38700 73 65 20 6e 61 6d 65 20 6f 72 20 4e 55 4c 4c 20  se name or NULL 
38710 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
38720 2a 7a 54 61 62 6c 65 4e 61 6d 65 2c 20 20 20 20  *zTableName,    
38730 20 2f 2a 20 54 61 62 6c 65 20 6e 61 6d 65 20 2a   /* Table name *
38740 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
38750 7a 43 6f 6c 75 6d 6e 4e 61 6d 65 2c 20 20 20 20  zColumnName,    
38760 2f 2a 20 43 6f 6c 75 6d 6e 20 6e 61 6d 65 20 2a  /* Column name *
38770 2f 0a 20 20 63 68 61 72 20 63 6f 6e 73 74 20 2a  /.  char const *
38780 2a 70 7a 44 61 74 61 54 79 70 65 2c 20 20 20 20  *pzDataType,    
38790 2f 2a 20 4f 55 54 50 55 54 3a 20 44 65 63 6c 61  /* OUTPUT: Decla
387a0 72 65 64 20 64 61 74 61 20 74 79 70 65 20 2a 2f  red data type */
387b0 0a 20 20 63 68 61 72 20 63 6f 6e 73 74 20 2a 2a  .  char const **
387c0 70 7a 43 6f 6c 6c 53 65 71 2c 20 20 20 20 20 2f  pzCollSeq,     /
387d0 2a 20 4f 55 54 50 55 54 3a 20 43 6f 6c 6c 61 74  * OUTPUT: Collat
387e0 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 6e 61 6d  ion sequence nam
387f0 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 4e 6f 74  e */.  int *pNot
38800 4e 75 6c 6c 2c 20 20 20 20 20 20 20 20 20 20 20  Null,           
38810 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72     /* OUTPUT: Tr
38820 75 65 20 69 66 20 4e 4f 54 20 4e 55 4c 4c 20 63  ue if NOT NULL c
3